diff --git a/.changeset/config.json b/.changeset/config.json
index 58e5f01c7d97..b5a4060d1a52 100644
--- a/.changeset/config.json
+++ b/.changeset/config.json
@@ -4,7 +4,7 @@
"commit": false,
"linked": [],
"access": "public",
- "baseBranch": "master",
+ "baseBranch": "main",
"bumpVersionsWithWorkspaceProtocolOnly": true,
- "ignore": ["!(@sveltejs/*|create-svelte|svelte-migrate)"]
+ "ignore": ["!(@sveltejs/*)"]
}
diff --git a/.changeset/funny-pets-melt.md b/.changeset/funny-pets-melt.md
new file mode 100644
index 000000000000..1a8a5a94605f
--- /dev/null
+++ b/.changeset/funny-pets-melt.md
@@ -0,0 +1,5 @@
+---
+"@sveltejs/adapter-cloudflare": patch
+---
+
+fix: await `init` on every request to prevent race condition
diff --git a/.changeset/gold-wolves-fix.md b/.changeset/gold-wolves-fix.md
new file mode 100644
index 000000000000..e5c2c4115012
--- /dev/null
+++ b/.changeset/gold-wolves-fix.md
@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+fix: avoid overriding Vite default `base` when running Vitest 4
diff --git a/.eslint/no-runtime-to-exports-imports.js b/.eslint/no-runtime-to-exports-imports.js
new file mode 100644
index 000000000000..d605b0658b41
--- /dev/null
+++ b/.eslint/no-runtime-to-exports-imports.js
@@ -0,0 +1,55 @@
+// @ts-expect-error no types here
+import path from 'node:path';
+
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+export default {
+ meta: {
+ type: 'problem',
+ docs: {
+ description: 'disallow relative imports from src/runtime to src/exports',
+ category: 'Possible Errors',
+ recommended: true
+ },
+ schema: [],
+ messages: {
+ noRuntimeToExportsImport:
+ 'Relative imports from src/runtime to src/exports are not allowed because they can cause Vite to resolve the same module both via regular Node and internal Vite. Use internal import maps or `@sveltejs/kit/internal` instead.'
+ }
+ },
+
+ create(context) {
+ const filename = context.filename;
+
+ // Only apply this rule to files in packages/kit/src/runtime
+ const in_runtime = filename.includes(path.join('packages', 'kit', 'src', 'runtime'));
+
+ if (!in_runtime) {
+ return {};
+ }
+
+ return {
+ ImportDeclaration(node) {
+ const import_path = node.source.value;
+
+ // Check if this is a relative import
+ if (typeof import_path === 'string' && import_path.startsWith('.')) {
+ // Resolve the import path relative to the current file
+ const current_dir = path.dirname(filename);
+ const resolved_path = path.resolve(current_dir, import_path);
+
+ // Check if the resolved path points to src/exports
+ const exports_path = path.join('packages', 'kit', 'src', 'exports');
+
+ if (resolved_path.includes(exports_path)) {
+ context.report({
+ node: node.source,
+ messageId: 'noRuntimeToExportsImport'
+ });
+ }
+ }
+ }
+ };
+ }
+};
diff --git a/.eslintrc.json b/.eslintrc.json
deleted file mode 100644
index 9501511a710b..000000000000
--- a/.eslintrc.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
- "root": true,
- "extends": "@sveltejs",
- "env": {
- "es2022": true
- },
- "ignorePatterns": [
- "packages/create-svelte/shared/",
- "packages/kit/test/prerendering/*/build",
- "packages/adapter-static/test/apps/*/build",
- "packages/adapter-cloudflare/files",
- "packages/adapter-netlify/files",
- "packages/adapter-node/files"
- ],
- "rules": {
- "no-undef": "off"
- }
-}
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index b077e088fb94..3eaabfa5d71e 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,3 +1,7 @@
+
+
+---
+
### Please don't delete this checklist! Before submitting the PR, please make sure you do the following:
- [ ] It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
- [ ] This message body should clearly illustrate what problems it solves.
@@ -8,3 +12,7 @@
### Changesets
- [ ] If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running `pnpm changeset` and following the prompts. Changesets that add features should be `minor` and those that fix bugs should be `patch`. Please prefix changeset messages with `feat:`, `fix:`, or `chore:`.
+
+### Edits
+
+- [ ] Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 120000
index 000000000000..be77ac83a189
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1 @@
+../AGENTS.md
\ No newline at end of file
diff --git a/.github/workflows/audit.yml b/.github/workflows/audit.yml
index 049ebc7508c9..80b2aef63cbd 100644
--- a/.github/workflows/audit.yml
+++ b/.github/workflows/audit.yml
@@ -13,13 +13,15 @@ permissions:
jobs:
Audit:
+ # prevents this action from running on forks
+ if: github.repository == 'sveltejs/kit'
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v4
- - uses: pnpm/action-setup@v2.4.0
- - uses: actions/setup-node@v3
+ - uses: actions/checkout@v6
+ - uses: pnpm/action-setup@v4.2.0
+ - uses: actions/setup-node@v6
with:
- node-version: '20.x'
+ node-version: '24.x'
cache: pnpm
- run: pnpm install --frozen-lockfile
# check prod dependencies as these would affect users
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5c6bd814714b..84075c46cf51 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,7 +3,7 @@ name: CI
on:
push:
branches:
- - master
+ - main
pull_request:
env:
@@ -19,87 +19,107 @@ permissions:
contents: read # to fetch code (actions/checkout)
jobs:
- Lint:
+ pkg-pr-new:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v4
- - uses: pnpm/action-setup@v2.4.0
- - uses: actions/setup-node@v3
+ - uses: actions/checkout@v6
+ - uses: pnpm/action-setup@v4.2.0
+ - uses: actions/setup-node@v6
with:
- node-version: '16.x'
+ node-version: 24
+ cache: pnpm
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm build
+ - run: pnpx pkg-pr-new publish --comment=off ./packages/*
+ lint-all:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v6
+ - uses: pnpm/action-setup@v4.2.0
+ - uses: actions/setup-node@v6
+ with:
+ node-version: 24
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm run lint
- - run: cd packages/kit && pnpm prepublishOnly
+ - run: cd packages/kit && pnpm prepublishOnly && { [ "`git status --porcelain=v1`" == "" ] || (echo "Generated types have changed — please run prepublishOnly locally and commit the changes after you have reviewed them"; git diff; exit 1); }
- run: pnpm run check
- Tests:
+ test-kit:
runs-on: ${{ matrix.os }}
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
include:
- - node-version: 16
- os: ubuntu-latest
- e2e-browser: 'chromium'
- node-version: 18
os: ubuntu-latest
e2e-browser: 'chromium'
- node-version: 20
os: ubuntu-latest
e2e-browser: 'chromium'
+ - node-version: 22
+ os: ubuntu-latest
+ e2e-browser: 'chromium'
+ - node-version: 24
+ os: ubuntu-latest
+ e2e-browser: 'chromium'
env:
KIT_E2E_BROWSER: ${{matrix.e2e-browser}}
steps:
- run: git config --global core.autocrlf false
- - uses: actions/checkout@v4
- - uses: pnpm/action-setup@v2.4.0
- - uses: actions/setup-node@v3
+ - uses: actions/checkout@v6
+ - uses: pnpm/action-setup@v4.2.0
+ - uses: actions/setup-node@v6
with:
node-version: ${{ matrix.node-version }}
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm playwright install ${{ matrix.e2e-browser }}
- - run: pnpm test
+ - run: pnpm run sync-all
+ - run: pnpm test:kit
+ env:
+ NODE_OPTIONS: ${{matrix.node-version == 22 && '--experimental-strip-types' || ''}} # allows loading svelte.config.ts
+ - name: Print flaky test report
+ run: node scripts/print-flaky-test-report.js
- name: Archive test results
if: failure()
shell: bash
run: find packages -type d -name test-results -not -empty | tar -czf test-results.tar.gz --files-from=-
- name: Upload test results
if: failure()
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v6
with:
retention-days: 3
name: test-failure-${{ github.run_id }}-${{ matrix.os }}-${{ matrix.node-version }}-${{ matrix.e2e-browser }}
path: test-results.tar.gz
- Cross-browser-test:
+ test-kit-cross-browser:
runs-on: ${{ matrix.os }}
timeout-minutes: 30
strategy:
fail-fast: false
matrix:
include:
- - node-version: 16
- os: windows-2019 # slowness reported on newer versions https://github.com/actions/runner-images/issues/5166
+ - node-version: 18
+ os: windows-latest
e2e-browser: 'chromium'
mode: 'dev'
- - node-version: 16
+ - node-version: 18
os: ubuntu-latest
e2e-browser: 'firefox'
mode: 'dev'
- - node-version: 16
+ - node-version: 18
os: macOS-latest
e2e-browser: 'webkit'
mode: 'dev'
- - node-version: 16
- os: windows-2019 # slowness reported on newer versions https://github.com/actions/runner-images/issues/5166
+ - node-version: 18
+ os: windows-latest
e2e-browser: 'chromium'
mode: 'build'
- - node-version: 16
+ - node-version: 18
os: ubuntu-latest
e2e-browser: 'firefox'
mode: 'build'
- - node-version: 16
+ - node-version: 18
os: macOS-latest
e2e-browser: 'webkit'
mode: 'build'
@@ -107,35 +127,112 @@ jobs:
KIT_E2E_BROWSER: ${{matrix.e2e-browser}}
steps:
- run: git config --global core.autocrlf false
- - uses: actions/checkout@v4
- - uses: pnpm/action-setup@v2.4.0
- - uses: actions/setup-node@v3
+ - uses: actions/checkout@v6
+ - uses: pnpm/action-setup@v4.2.0
+ - uses: actions/setup-node@v6
with:
node-version: ${{ matrix.node-version }}
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm playwright install ${{ matrix.e2e-browser }}
+ - run: pnpm run sync-all
- run: pnpm test:cross-platform:${{ matrix.mode }}
+ - name: Print flaky test report
+ run: node scripts/print-flaky-test-report.js
- name: Archive test results
if: failure()
shell: bash
run: find packages -type d -name test-results -not -empty | tar -czf test-results-cross-platform-${{ matrix.mode }}.tar.gz --files-from=-
- name: Upload test results
if: failure()
- uses: actions/upload-artifact@v3
+ uses: actions/upload-artifact@v6
with:
retention-days: 3
name: test-failure-cross-platform-${{ matrix.mode }}-${{ github.run_id }}-${{ matrix.os }}-${{ matrix.node-version }}-${{ matrix.e2e-browser }}
path: test-results-cross-platform-${{ matrix.mode }}.tar.gz
- Test-create-svelte:
+ test-kit-server-side-route-resolution:
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - mode: 'dev'
+ - mode: 'build'
+ steps:
+ - run: git config --global core.autocrlf false
+ - uses: actions/checkout@v6
+ - uses: pnpm/action-setup@v4.2.0
+ - uses: actions/setup-node@v6
+ with:
+ node-version: 24
+ cache: pnpm
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm playwright install chromium
+ - run: pnpm run sync-all
+ - run: pnpm test:server-side-route-resolution:${{ matrix.mode }}
+ - name: Print flaky test report
+ run: node scripts/print-flaky-test-report.js
+ - name: Archive test results
+ if: failure()
+ shell: bash
+ run: find packages -type d -name test-results -not -empty | tar -czf test-results-server-side-route-resolution-${{ matrix.mode }}.tar.gz --files-from=-
+ - name: Upload test results
+ if: failure()
+ uses: actions/upload-artifact@v6
+ with:
+ retention-days: 3
+ name: test-failure-server-side-route-resolution-${{ matrix.mode }}-${{ github.run_id }}
+ path: test-results-server-side-route-resolution-${{ matrix.mode }}.tar.gz
+ test-kit-svelte-async:
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - mode: 'dev'
+ - mode: 'build'
+ steps:
+ - run: git config --global core.autocrlf false
+ - uses: actions/checkout@v6
+ - uses: pnpm/action-setup@v4.2.0
+ - uses: actions/setup-node@v6
+ with:
+ node-version: 24
+ cache: pnpm
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm playwright install chromium
+ - run: pnpm run sync-all
+ - run: pnpm test:svelte-async:${{ matrix.mode }}
+ - name: Print flaky test report
+ run: node scripts/print-flaky-test-report.js
+ - name: Archive test results
+ if: failure()
+ shell: bash
+ run: find packages -type d -name test-results -not -empty | tar -czf test-results-svelte-async-${{ matrix.mode }}.tar.gz --files-from=-
+ - name: Upload test results
+ if: failure()
+ uses: actions/upload-artifact@v6
+ with:
+ retention-days: 3
+ name: test-failure-svelte-async-${{ matrix.mode }}-${{ github.run_id }}
+ path: test-results-svelte-async-${{ matrix.mode }}.tar.gz
+ test-others:
runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ node-version: [18, 20, 22, 24]
steps:
- - uses: actions/checkout@v4
- - uses: pnpm/action-setup@v2.4.0
- - uses: actions/setup-node@v3
+ - uses: actions/checkout@v6
+ - uses: pnpm/action-setup@v4.2.0
+ - uses: actions/setup-node@v6
with:
- node-version: 16
+ node-version: ${{matrix.node-version}}
cache: pnpm
- run: pnpm install --frozen-lockfile
+ - run: pnpm playwright install chromium
- run: cd packages/kit && pnpm prepublishOnly
- - run: pnpm run test:create-svelte
+ - run: pnpm run test:others
+ env:
+ NODE_OPTIONS: ${{matrix.node-version == 22 && '--experimental-strip-types' || ''}} # allows loading svelte.config.ts
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7c8960ce40a9..7461807d1192 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -3,7 +3,7 @@ name: Release
on:
push:
branches:
- - master
+ - main
permissions: {}
jobs:
@@ -12,20 +12,21 @@ jobs:
if: github.repository == 'sveltejs/kit'
permissions:
contents: write # to create release (changesets/action)
+ id-token: write # OpenID Connect token needed for provenance
pull-requests: write # to create pull request (changesets/action)
name: Release
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
- uses: actions/checkout@v4
+ uses: actions/checkout@v6
with:
# This makes Actions fetch all Git history so that Changesets can generate changelogs with the correct commits
fetch-depth: 0
- - uses: pnpm/action-setup@v2.4.0
+ - uses: pnpm/action-setup@v4.2.0
- name: Setup Node.js
- uses: actions/setup-node@v3
+ uses: actions/setup-node@v6
with:
- node-version: 16.x
+ node-version: 24.x
cache: pnpm
- run: pnpm install --frozen-lockfile
@@ -39,8 +40,7 @@ jobs:
version: pnpm changeset:version
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
- UPDATE_TEMPLATE_SSH_KEY: ${{ secrets.UPDATE_TEMPLATE_SSH_KEY }}
+ NPM_CONFIG_PROVENANCE: true
# TODO alert discord
# - name: Send a Slack notification if a publish happens
diff --git a/.gitignore b/.gitignore
index 679d1c89e690..e105f8313444 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,7 +5,6 @@ test-results/
package-lock.json
yarn.lock
vite.config.js.timestamp-*
-/packages/create-svelte/template/CHANGELOG.md
/packages/package/test/**/package
/documentation/types.js
.env
@@ -19,3 +18,4 @@ vite.config.js.timestamp-*
.test-tmp
symlink-from
.idea/
+_tmp_flaky_test_output.txt
diff --git a/.npmrc b/.npmrc
index d7445a115f87..8af70e3f1fb9 100644
--- a/.npmrc
+++ b/.npmrc
@@ -1,2 +1,2 @@
link-workspace-packages = true
-engine-strict = true
+shell-emulator = true
diff --git a/.prettierrc b/.prettierrc
index 72264f51e616..9f806b7df2d4 100644
--- a/.prettierrc
+++ b/.prettierrc
@@ -3,6 +3,7 @@
"singleQuote": true,
"trailingComma": "none",
"printWidth": 100,
+ "plugins": ["prettier-plugin-svelte"],
"overrides": [
{
"files": ["*.svelte"],
@@ -20,16 +21,21 @@
{
"files": [
"**/CHANGELOG.md",
+ "**/vite.config.js.timestamp-*",
"**/.svelte-kit/**",
+ "**/.custom-out-dir/**",
+ "**/test-results/**",
+ "**/.wrangler/**",
"documentation/**/*.md",
"packages/package/test/fixtures/**/expected/**/*",
"packages/package/test/watch/expected/**/*",
"packages/package/test/watch/package/**/*",
"packages/kit/src/core/postbuild/fixtures/**/*",
- "packages/migrate/migrations/routes/*/samples.md"
+ "packages/adapter-cloudflare/test/apps/workers/dist/**/*",
+ "packages/*/test/**/build"
],
"options": {
- "requirePragma": true
+ "rangeEnd": 0
}
}
]
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000000..13e958fe7be2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,159 @@
+# SvelteKit Coding Agent Guide
+
+This guide is for AI coding agents working in the SvelteKit monorepo.
+
+**Important:** Read and follow `CONTRIBUTING.md` as well - it contains essential information about testing, code structure, and contribution guidelines that applies here.
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Initial setup (takes 3-4 minutes, set 10+ min timeout)
+pnpm install --frozen-lockfile
+
+# Build all packages (~1-2 seconds)
+pnpm build
+
+# Format code (~15 seconds)
+pnpm run format
+
+# Lint (takes 2-3 minutes, set 5+ min timeout)
+pnpm run lint
+
+# Type checking (takes 3-4 minutes, set 8+ min timeout)
+pnpm run check
+```
+
+### Testing Commands
+
+```bash
+# Unit tests only (fastest - ~6 seconds)
+pnpm -F @sveltejs/kit test:unit
+
+# Run a single unit test file
+pnpm -F @sveltejs/kit test:unit:dev path/to/test.spec.js
+
+# Integration tests (10-30 minutes, set 60+ min timeout)
+pnpm test:kit
+
+# A single integration test suite (name of suite found in packages/kit/test/apps/*/package.json)
+pnpm -F {name-of-suite} test
+
+# Run single Playwright test (must use workdir - no pnpm -F shorthand)
+cd packages/kit/test/apps/basics && npx playwright test --grep "test name"
+
+# Other package tests (5-15 minutes, set 30+ min timeout)
+pnpm test:others
+```
+
+### Pre-submission Checklist
+
+1. `pnpm run format` - Auto-format code
+2. `pnpm run lint` - Check code style (don't cancel early)
+3. `pnpm run check` - Type checking (don't cancel early)
+4. `pnpm -F @sveltejs/kit test:unit` - Run unit tests
+5. For @sveltejs/kit changes: `pnpm -F @sveltejs/kit prepublishOnly` - Generate types
+6. Run `pnpm changeset` to document changes (prefix with `fix`, `feat`, `breaking`, or `chore`)
+
+## Code Style Examples
+
+The coding style guidelines are in `CONTRIBUTING.md`. Here are additional examples:
+
+### Imports
+
+```javascript
+// JSDoc type imports at the top
+/** @import { Handle, RequestEvent } from '@sveltejs/kit' */
+
+// Named imports (no default exports)
+import { HttpError, SvelteKitError } from '@sveltejs/kit/internal';
+```
+
+### Functions
+
+```javascript
+// Exported named functions (no default exports)
+export function coalesce_to_error(err) {
+ // Implementation
+}
+
+// JSDoc for all parameters and return types
+/**
+ * @param {unknown} error
+ * @returns {Error}
+ */
+export function coalesce_to_error(error) {
+ // Implementation
+}
+
+// Use arrow functions for callbacks
+const handler = (event) => {
+ /* ... */
+};
+```
+
+### Error Handling
+
+```javascript
+// Type checking with instanceof
+if (error instanceof HttpError || error instanceof SvelteKitError) {
+ // Handle
+}
+
+// Graceful fallbacks
+const status = error?.status ?? 500;
+
+// Optional chaining and nullish coalescing
+const content_type = request.headers.get('content-type')?.split(';', 1)[0];
+```
+
+### TypeScript/JSDoc
+
+- Use JSDoc annotations for all function parameters and return types
+- Complex types: `/** @type {Array<{ type: string, subtype: string }>} */`
+- Type casting when needed: `/** @type {Error} */ (err)`
+- Enable strict mode: `checkJs: true`, `strict: true` in tsconfig.json
+
+### Formatting (via Prettier)
+
+- **Tabs for indentation** (not spaces)
+- **Single quotes** for strings
+- **No trailing commas**
+- **100 character line width**
+- Files are auto-formatted by `pnpm run format`
+
+### Comments
+
+````javascript
+// JSDoc with usage examples for public APIs
+/**
+ * Sequence multiple handle functions
+ *
+ * @example
+ * ```js
+ * export const handle = sequence(first, second);
+ * ```
+ *
+ * @param {...Handle} handlers
+ * @returns {Handle}
+ */
+
+// Inline comments for clarifications
+// no match equals invalid header — ignore
+````
+
+## Key Packages
+
+- `@sveltejs/kit` - Main framework (`packages/kit/`)
+- `adapter-*` - Platform adapters (node, cloudflare, netlify, vercel, static, auto)
+- `@sveltejs/package` - Package building utilities
+- `@sveltejs/enhanced-img` - Enhanced image component
+- `@sveltejs/amp` - AMP support
+
+## Troubleshooting
+
+- **Browser tests fail**: `pnpm playwright install chromium`
+- **Build failures**: Ensure `pnpm install --frozen-lockfile` completed
+- **Type errors**: Run `pnpm -F @sveltejs/kit prepublishOnly`
+- **Lint issues**: Run `pnpm run format` first
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 000000000000..47dc3e3d863c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5fc83158606b..7e81bf303dad 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,13 +4,13 @@
This is a monorepo, meaning the repo holds multiple packages. It requires the use of [pnpm](https://pnpm.io/). You can [install pnpm](https://pnpm.io/installation) with:
-```bash
+```sh
npm i -g pnpm
```
`pnpm` commands run in the project's root directory will run on all sub-projects. You can checkout the code and install the dependencies with:
-```bash
+```sh
git clone git@github.com:sveltejs/kit.git
cd kit
pnpm install
@@ -22,34 +22,41 @@ pnpm install
You can use the playground at [`playgrounds/basic`](./playgrounds/basic/) to experiment with your changes to SvelteKit locally.
-### Linking
+### Linking local changes
If you want to test against an existing project, you can use [pnpm `overrides`](https://pnpm.io/package_json#pnpmoverrides) in that project:
```jsonc
{
- // ...
- "pnpm": {
- "overrides": {
- "@sveltejs/kit": "link:../path/to/svelte-kit/packages/kit",
- // additionally/optional the adapter you're using
- "@sveltejs/adapter-auto": "link:../path/to/svelte-kit/packages/adapter-auto"
- }
- }
+ // ...
+ "pnpm": {
+ "overrides": {
+ "@sveltejs/kit": "link:../path/to/svelte-kit/packages/kit",
+ // additionally/optional the adapter you're using
+ "@sveltejs/adapter-auto": "link:../path/to/svelte-kit/packages/adapter-auto"
+ }
+ }
}
```
+### Testing PR changes
+
+Each pull request will be built and published via [pkg.pr.new/](https://pkg.pr.new/). You can test the change by installing the package with your PR number:
+
+```
+npm add https://pkg.pr.new/sveltejs/kit/@sveltejs/kit@YOUR_PR_NUMBER_GOES_HERE
+```
+
## Code structure
Entry points to be aware of are:
-- [`packages/create-svelte`](https://github.com/sveltejs/kit/tree/master/packages/create-svelte) - code that's run when you create a new project with `npm create svelte@latest`
-- [`packages/package`](https://github.com/sveltejs/kit/tree/master/packages/package) - for the `svelte-package` command
-- [`packages/kit/src/core`](https://github.com/sveltejs/kit/tree/master/packages/kit/src/core) - code that's called at dev/build-time
-- [`packages/kit/src/core/sync`](https://github.com/sveltejs/kit/tree/master/packages/kit/src/core/sync) - for `svelte-kit sync`, which regenerates routing info and type definitions
-- [`packages/kit/src/runtime`](https://github.com/sveltejs/kit/tree/master/packages/kit/src/runtime) - code that's called at runtime
-- [`packages/kit/src/exports/vite`](https://github.com/sveltejs/kit/tree/master/packages/kit/src/exports/vite) - for all the Vite plugin related stuff
-- [`packages/adapter-[platform]`](https://github.com/sveltejs/kit/tree/master/packages) - for the various SvelteKit-provided adapters
+- [`packages/package`](https://github.com/sveltejs/kit/tree/main/packages/package) - for the `svelte-package` command
+- [`packages/kit/src/core`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/core) - code that's called at dev/build-time
+- [`packages/kit/src/core/sync`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/core/sync) - for `svelte-kit sync`, which regenerates routing info and type definitions
+- [`packages/kit/src/runtime`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/runtime) - code that's called at runtime
+- [`packages/kit/src/exports/vite`](https://github.com/sveltejs/kit/tree/main/packages/kit/src/exports/vite) - for all the Vite plugin related stuff
+- [`packages/adapter-[platform]`](https://github.com/sveltejs/kit/tree/main/packages) - for the various SvelteKit-provided adapters
## Good first issues
@@ -61,7 +68,7 @@ Issues with the [**soon**](https://github.com/sveltejs/kit/issues?q=is%3Aissue+i
## Testing
-Run `pnpm test` to run the tests from all subpackages. Browser tests live in subdirectories of `packages/kit/test` such as `packages/kit/test/apps/basics`.
+Run `pnpm test:kit` to run the tests from the `packages/kit` directory. You can also run `pnpm test:others` to run tests from all packages __except__ the `packages/kit` directory. Browser tests live in subdirectories of `packages/kit/test` such as `packages/kit/test/apps/basics`.
You can run the tests for only a single package by first moving to that directory. E.g. `cd packages/kit`.
@@ -87,21 +94,21 @@ If you would like to test local changes to Vite or another dependency, you can b
```jsonc
{
- // ...
- "dependencies": {
- "vite": "^4.0.0"
- },
- "pnpm": {
- "overrides": {
- "vite": "link:../path/to/vite/packages/vite"
- }
- }
+ // ...
+ "dependencies": {
+ "vite": "^4.0.0"
+ },
+ "pnpm": {
+ "overrides": {
+ "vite": "link:../path/to/vite/packages/vite"
+ }
+ }
}
```
## Documentation changes
-All documentation for SvelteKit is in the [`documentation` directory](https://github.com/sveltejs/kit/tree/master/documentation), and any improvements should be made as a Pull Request to this repository. The site itself is located in the [`sites/kit.svelte.dev` directory](https://github.com/sveltejs/kit/tree/master/sites/kit.svelte.dev) and can be run locally to preview changes.
+All documentation for SvelteKit is in the [`documentation` directory](https://github.com/sveltejs/kit/tree/main/documentation), and any improvements should be made as a Pull Request to this repository. The site itself is located in the [`sveltejs/svelte.dev` repo](https://github.com/sveltejs/svelte.dev) and can be run locally to preview changes.
## Sending PRs
@@ -116,7 +123,7 @@ There are a few guidelines we follow:
To use the git hooks in the repo, which will save you from waiting for CI to tell you that you forgot to lint, run this:
-```bash
+```sh
git config core.hookspath .githooks
```
@@ -124,12 +131,16 @@ git config core.hookspath .githooks
For changes to be reflected in package changelogs, run `pnpm changeset` and follow the prompts.
+### Type changes
+
+If your PR changes the generated types of SvelteKit, run `pnpm generate:types` inside `packages/kit` and commit the new output (don't format it with Prettier!). Review the changes carefully to ensure there are no unwanted changes. If you don't commit type changes, CI will fail.
+
## Releases
The [Changesets GitHub action](https://github.com/changesets/action#with-publishing) will create and update a PR that applies changesets and publishes new versions of changed packages to npm.
New packages will need to be published manually the first time if they are scoped to the `@sveltejs` organisation, by running this from the package directory:
-```bash
+```sh
npm publish --access=public
```
diff --git a/FUNDING.json b/FUNDING.json
new file mode 100644
index 000000000000..7ed51db691e6
--- /dev/null
+++ b/FUNDING.json
@@ -0,0 +1,7 @@
+{
+ "drips": {
+ "ethereum": {
+ "ownedBy": "0xCE08E02c37d90d75C2bf7D9e55f7606C8DB80E70"
+ }
+ }
+}
diff --git a/README.md b/README.md
index 65ff09b6b9b1..025b8acab1c1 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
# SvelteKit
-Web development, streamlined. Read the [documentation](https://kit.svelte.dev/docs) to get started.
+Web development, streamlined. Read the [documentation](https://svelte.dev/docs/kit) to get started.
### Packages
@@ -11,17 +11,15 @@ Web development, streamlined. Read the [documentation](https://kit.svelte.dev/do
| [@sveltejs/kit](packages/kit) | [Changelog](packages/kit/CHANGELOG.md) |
| [@sveltejs/adapter-auto](packages/adapter-auto) | [Changelog](packages/adapter-auto/CHANGELOG.md) |
| [@sveltejs/adapter-cloudflare](packages/adapter-cloudflare) | [Changelog](packages/adapter-cloudflare/CHANGELOG.md) |
-| [@sveltejs/adapter-cloudflare-workers](packages/adapter-cloudflare-workers) | [Changelog](packages/adapter-cloudflare-workers/CHANGELOG.md) |
| [@sveltejs/adapter-netlify](packages/adapter-netlify) | [Changelog](packages/adapter-netlify/CHANGELOG.md) |
| [@sveltejs/adapter-node](packages/adapter-node) | [Changelog](packages/adapter-node/CHANGELOG.md) |
| [@sveltejs/adapter-static](packages/adapter-static) | [Changelog](packages/adapter-static/CHANGELOG.md) |
| [@sveltejs/adapter-vercel](packages/adapter-vercel) | [Changelog](packages/adapter-vercel/CHANGELOG.md) |
| [@sveltejs/amp](packages/amp) | [Changelog](packages/amp/CHANGELOG.md) |
+| [@sveltejs/enhanced-img](packages/enhanced-img) | [Changelog](packages/enhanced-img/CHANGELOG.md) |
| [@sveltejs/package](packages/package) | [Changelog](packages/package/CHANGELOG.md) |
-| [create-svelte](packages/create-svelte) | [Changelog](packages/create-svelte/CHANGELOG.md) |
-| [svelte-migrate](packages/migrate) | [Changelog](packages/migrate/CHANGELOG.md) |
-[Additional adapters](<(https://sveltesociety.dev/components#adapters)>) are maintained by the community.
+[Additional adapters](https://sveltesociety.dev/packages?category=sveltekit-adapters) are maintained by the community.
## Bug reporting
@@ -43,4 +41,4 @@ Funds donated via Open Collective will be used for compensating expenses related
## License
-[MIT](https://github.com/sveltejs/kit/blob/master/LICENSE)
+[MIT](https://github.com/sveltejs/kit/blob/main/LICENSE)
diff --git a/documentation/docs/10-getting-started/10-introduction.md b/documentation/docs/10-getting-started/10-introduction.md
index 189fcb3bcc7d..dd093ff5abea 100644
--- a/documentation/docs/10-getting-started/10-introduction.md
+++ b/documentation/docs/10-getting-started/10-introduction.md
@@ -4,24 +4,24 @@ title: Introduction
## Before we begin
-> If you're new to Svelte or SvelteKit we recommend checking out the [interactive tutorial](https://learn.svelte.dev).
+> [!NOTE] If you're new to Svelte or SvelteKit we recommend checking out the [interactive tutorial](/tutorial/kit).
>
-> If you get stuck, reach out for help in the [Discord chatroom](https://svelte.dev/chat).
+> If you get stuck, reach out for help in the [Discord chatroom](/chat).
## What is SvelteKit?
-SvelteKit is a framework for rapidly developing robust, performant web applications using [Svelte](https://svelte.dev/). If you're coming from React, SvelteKit is similar to Next. If you're coming from Vue, SvelteKit is similar to Nuxt.
+SvelteKit is a framework for rapidly developing robust, performant web applications using [Svelte](../svelte). If you're coming from React, SvelteKit is similar to Next. If you're coming from Vue, SvelteKit is similar to Nuxt.
-To learn more about the kinds of applications you can build with SvelteKit, see the [FAQ](/docs/faq#what-can-i-make-with-sveltekit).
+To learn more about the kinds of applications you can build with SvelteKit, see the [documentation regarding project types](project-types).
## What is Svelte?
-In short, Svelte is a way of writing user interface components — like a navigation bar, comment section, or contact form — that users see and interact with in their browsers. The Svelte compiler converts your components to JavaScript that can be run to render the HTML for the page and to CSS that styles the page. You don't need to know Svelte to understand the rest of this guide, but it will help. If you'd like to learn more, check out [the Svelte tutorial](https://svelte.dev/tutorial).
+In short, Svelte is a way of writing user interface components — like a navigation bar, comment section, or contact form — that users see and interact with in their browsers. The Svelte compiler converts your components to JavaScript that can be run to render the HTML for the page and to CSS that styles the page. You don't need to know Svelte to understand the rest of this guide, but it will help. If you'd like to learn more, check out [the Svelte tutorial](/tutorial).
## SvelteKit vs Svelte
Svelte renders UI components. You can compose these components and render an entire page with just Svelte, but you need more than just Svelte to write an entire app.
-SvelteKit helps you build web apps while following modern best practices and providing solutions to common development challenges. It offers everything from basic functionalities — like a [router](glossary#routing) that updates your UI when a link is clicked — to more advanced capabilities. Its extensive list of features includes [build optimizations](https://vitejs.dev/guide/features.html#build-optimizations) to load only the minimal required code; [offline support](service-workers); [preloading](link-options#data-sveltekit-preload-data) pages before user navigation; [configurable rendering](page-options) to handle different parts of your app on the server via [SSR](glossary#ssr), in the browser through [client-side rendering](glossary#csr), or at build-time with [prerendering](glossary#prerendering); and much more. Building an app with all the modern best practices is fiendishly complicated, but SvelteKit does all the boring stuff for you so that you can get on with the creative part.
+SvelteKit helps you build web apps while following modern best practices and providing solutions to common development challenges. It offers everything from basic functionalities — like a [router](glossary#Routing) that updates your UI when a link is clicked — to more advanced capabilities. Its extensive list of features includes [build optimizations](https://vitejs.dev/guide/features.html#build-optimizations) to load only the minimal required code; [offline support](service-workers); [preloading](link-options#data-sveltekit-preload-data) pages before user navigation; [configurable rendering](page-options) to handle different parts of your app on the server via [SSR](glossary#SSR), in the browser through [client-side rendering](glossary#CSR), or at build-time with [prerendering](glossary#Prerendering); [image optimization](images); and much more. Building an app with all the modern best practices is fiendishly complicated, but SvelteKit does all the boring stuff for you so that you can get on with the creative part.
It reflects changes to your code in the browser instantly to provide a lightning-fast and feature-rich development experience by leveraging [Vite](https://vitejs.dev/) with a [Svelte plugin](https://github.com/sveltejs/vite-plugin-svelte) to do [Hot Module Replacement (HMR)](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#hot).
diff --git a/documentation/docs/10-getting-started/20-creating-a-project.md b/documentation/docs/10-getting-started/20-creating-a-project.md
index a65814e9a50f..c1d125ec0bd8 100644
--- a/documentation/docs/10-getting-started/20-creating-a-project.md
+++ b/documentation/docs/10-getting-started/20-creating-a-project.md
@@ -2,24 +2,23 @@
title: Creating a project
---
-The easiest way to start building a SvelteKit app is to run `npm create`:
+The easiest way to start building a SvelteKit app is to run `npx sv create`:
-```bash
-npm create svelte@latest my-app
+```sh
+npx sv create my-app
cd my-app
-npm install
npm run dev
```
-The first command will scaffold a new project in the `my-app` directory asking you if you'd like to set up some basic tooling such as TypeScript. See [integrations](./integrations) for pointers on setting up additional tooling. The subsequent commands will then install its dependencies and start a server on [localhost:5173](http://localhost:5173).
+The first command will scaffold a new project in the `my-app` directory asking if you'd like to set up some basic tooling such as TypeScript. See [the CLI docs](/docs/cli/overview) for information about these options and [the integrations page](./integrations) for pointers on setting up additional tooling. `npm run dev` will then start the development server on [localhost:5173](http://localhost:5173) - make sure you install dependencies before running this if you didn't do so during project creation.
There are two basic concepts:
-- Each page of your app is a [Svelte](https://svelte.dev) component
+- Each page of your app is a [Svelte](../svelte) component
- You create pages by adding files to the `src/routes` directory of your project. These will be server-rendered so that a user's first visit to your app is as fast as possible, then a client-side app takes over
Try editing the files to get a feel for how everything works.
## Editor setup
-We recommend using [Visual Studio Code (aka VS Code)](https://code.visualstudio.com/download) with [the Svelte extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode), but [support also exists for numerous other editors](https://sveltesociety.dev/tools#editor-support).
+We recommend using [Visual Studio Code (aka VS Code)](https://code.visualstudio.com/download) with [the Svelte extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode), but [support also exists for numerous other editors](https://sveltesociety.dev/collection/editor-support-c85c080efc292a34).
diff --git a/documentation/docs/10-getting-started/25-project-types.md b/documentation/docs/10-getting-started/25-project-types.md
new file mode 100644
index 000000000000..8ac78cd9d6b8
--- /dev/null
+++ b/documentation/docs/10-getting-started/25-project-types.md
@@ -0,0 +1,69 @@
+---
+title: Project types
+---
+
+SvelteKit offers configurable rendering, which allows you to build and deploy your project in several different ways. You can build all of the below types of applications and more with SvelteKit. Rendering settings are not mutually exclusive and you may choose the optimal manner with which to render different parts of your application.
+
+If you don't have a particular way you'd like to build your application in mind, don't worry! The way your application is built, deployed, and rendered is controlled by which adapter you've chosen and a small amount of configuration and these can always be changed later. The [project structure](project-structure) and [routing](glossary#Routing) will be the same regardless of the project type that you choose.
+
+## Default rendering
+
+By default, when a user visits a site, SvelteKit will render the first page with [server-side rendering (SSR)](glossary#SSR) and subsequent pages with [client-side rendering (CSR)](glossary#CSR). Using SSR for the initial render improves SEO and perceived performance of the initial page load. Client-side rendering then takes over and updates the page without having to rerender common components, which is typically faster and eliminates a flash when navigating between pages. Apps built with this hybrid rendering approach have also been called [transitional apps](https://www.youtube.com/watch?v=860d8usGC0o).
+
+## Static site generation
+
+You can use SvelteKit as a [static site generator (SSG)](glossary#SSG) that fully [prerenders](glossary#Prerendering) your site with static rendering using [`adapter-static`](adapter-static). You may also use [the prerender option](page-options#prerender) to prerender only some pages and then choose a different adapter with which to dynamically server-render other pages.
+
+Tools built solely to do static site generation may scale the prerendering process more efficiently during build when rendering a very large number of pages. When working with very large statically generated sites, you can avoid long build times with [Incremental Static Regeneration (ISR) if using `adapter-vercel`](adapter-vercel#Incremental-Static-Regeneration). And in contrast to purpose-built SSGs, SvelteKit allows for nicely mixing and matching different rendering types on different pages.
+
+## Single-page app
+
+[Single-page apps (SPAs)](glossary#SPA) exclusively use [client-side rendering (CSR)](glossary#CSR). You can [build single-page apps (SPAs)](single-page-apps) with SvelteKit. As with all types of SvelteKit applications, you can write your backend in SvelteKit or [another language or framework](#Separate-backend). If you are building an application with no backend or a [separate backend](#Separate-backend), you can simply skip over and ignore the parts of the docs talking about `server` files.
+
+## Multi-page app
+
+SvelteKit isn't typically used to build [traditional multi-page apps](glossary#MPA). However, in SvelteKit you can remove all JavaScript on a page with [`csr = false`](page-options#csr), which will render subsequent links on the server, or you can use [`data-sveltekit-reload`](link-options#data-sveltekit-reload) to render specific links on the server.
+
+## Separate backend
+
+If your backend is written in another language such as Go, Java, PHP, Ruby, Rust, or C#, there are a couple of ways that you can deploy your application. The most recommended way would be to deploy your SvelteKit frontend separately from your backend utilizing `adapter-node` or a serverless adapter. Some users prefer not to have a separate process to manage and decide to deploy their application as a [single-page app (SPA)](single-page-apps) served by their backend server, but note that single-page apps have worse SEO and performance characteristics.
+
+If you are using an external backend, you can simply skip over and ignore the parts of the docs talking about `server` files. You may also want to reference [the FAQ about how to make calls to a separate backend](faq#How-do-I-use-a-different-backend-API-server).
+
+## Serverless app
+
+SvelteKit apps are simple to run on serverless platforms. [The default zero config adapter](adapter-auto) will automatically run your app on a number of supported platforms or you can use [`adapter-vercel`](adapter-vercel), [`adapter-netlify`](adapter-netlify), or [`adapter-cloudflare`](adapter-cloudflare) to provide platform-specific configuration. And [community adapters](/packages#sveltekit-adapters) allow you to deploy your application to almost any serverless environment. Some of these adapters such as [`adapter-vercel`](adapter-vercel) and [`adapter-netlify`](adapter-netlify) offer an `edge` option, to support [edge rendering](glossary#Edge) for improved latency.
+
+## Your own server
+
+You can deploy to your own server or VPS using [`adapter-node`](adapter-node).
+
+## Container
+
+You can use [`adapter-node`](adapter-node) to run a SvelteKit app within a container such as Docker or LXC.
+
+## Library
+
+You can create a library to be used by other Svelte apps with the [`@sveltejs/package`](packaging) add-on to SvelteKit by choosing the library option when running [`sv create`](/docs/cli/sv-create).
+
+## Offline app
+
+SvelteKit has full support for [service workers](service-workers) allowing you to build many types of applications such as offline apps and [progressive web apps](glossary#PWA).
+
+## Mobile app
+
+You can turn a [SvelteKit SPA](single-page-apps) into a mobile app with [Tauri](https://v2.tauri.app/start/frontend/sveltekit/) or [Capacitor](https://capacitorjs.com/solution/svelte). Mobile features like the camera, geolocation, and push notifications are available via plugins for both platforms.
+
+These mobile development platforms work by starting a local web server and then serving your application like a static host on your phone. You may find [`bundleStrategy: 'single'`](configuration#output) to be a helpful option to limit the number of requests made. E.g. at the time of writing, the Capacitor local server uses HTTP/1, which limits the number of concurrent connections.
+
+## Desktop app
+
+You can turn a [SvelteKit SPA](single-page-apps) into a desktop app with [Tauri](https://v2.tauri.app/start/frontend/sveltekit/), [Wails](https://wails.io/docs/guides/sveltekit/), or [Electron](https://www.electronjs.org/).
+
+## Browser extension
+
+You can build browser extensions using either [`adapter-static`](adapter-static) or [community adapters](/packages#sveltekit-adapters) specifically tailored towards browser extensions.
+
+## Embedded device
+
+Because of its efficient rendering, Svelte can be run on low power devices. Embedded devices like microcontrollers and TVs may limit the number of concurrent connections. In order to reduce the number of concurrent requests, you may find [`bundleStrategy: 'single'`](configuration#output) to be a helpful option in this deployment configuration.
diff --git a/documentation/docs/10-getting-started/30-project-structure.md b/documentation/docs/10-getting-started/30-project-structure.md
index e9a63473b0d9..d1db3547ca34 100644
--- a/documentation/docs/10-getting-started/30-project-structure.md
+++ b/documentation/docs/10-getting-started/30-project-structure.md
@@ -4,7 +4,7 @@ title: Project structure
A typical SvelteKit project looks like this:
-```bash
+```tree
my-project/
├ src/
│ ├ lib/
@@ -19,7 +19,8 @@ my-project/
│ ├ error.html
│ ├ hooks.client.js
│ ├ hooks.server.js
-│ └ service-worker.js
+│ ├ service-worker.js
+│ └ tracing.server.js
├ static/
│ └ [your static assets]
├ tests/
@@ -30,7 +31,7 @@ my-project/
└ vite.config.js
```
-You'll also find common files like `.gitignore` and `.npmrc` (and `.prettierrc` and `.eslintrc.cjs` and so on, if you chose those options when running `npm create svelte@latest`).
+You'll also find common files like `.gitignore` and `.npmrc` (and `.prettierrc` and `eslint.config.js` and so on, if you chose those options when running `npx sv create`).
## Project files
@@ -38,9 +39,9 @@ You'll also find common files like `.gitignore` and `.npmrc` (and `.prettierrc`
The `src` directory contains the meat of your project. Everything except `src/routes` and `src/app.html` is optional.
-- `lib` contains your library code (utilities and components), which can be imported via the [`$lib`](modules#$lib) alias, or packaged up for distribution using [`svelte-package`](packaging)
+- `lib` contains your library code (utilities and components), which can be imported via the [`$lib`]($lib) alias, or packaged up for distribution using [`svelte-package`](packaging)
- `server` contains your server-only library code. It can be imported by using the [`$lib/server`](server-only-modules) alias. SvelteKit will prevent you from importing these in client code.
-- `params` contains any [param matchers](advanced-routing#matching) your app needs
+- `params` contains any [param matchers](advanced-routing#Matching) your app needs
- `routes` contains the [routes](routing) of your application. You can also colocate other components that are only used within a single route here
- `app.html` is your page template — an HTML document containing the following placeholders:
- `%sveltekit.head%` — `` and `
+{/if}+++
```
-> If multiple `load` functions return data with the same key, the last one 'wins' — the result of a layout `load` returning `{ a: 1, b: 2 }` and a page `load` returning `{ b: 3, c: 4 }` would be `{ a: 1, b: 3, c: 4 }`.
+> [!NOTE] If multiple `load` functions return data with the same key, the last one 'wins' — the result of a layout `load` returning `{ a: 1, b: 2 }` and a page `load` returning `{ b: 3, c: 4 }` would be `{ a: 1, b: 3, c: 4 }`.
-## $page.data
+## page.data
The `+page.svelte` component, and each `+layout.svelte` component above it, has access to its own data plus all the data from its parents.
-In some cases, we might need the opposite — a parent layout might need to access page data or data from a child layout. For example, the root layout might want to access a `title` property returned from a `load` function in `+page.js` or `+page.server.js`. This can be done with `$page.data`:
+In some cases, we might need the opposite — a parent layout might need to access page data or data from a child layout. For example, the root layout might want to access a `title` property returned from a `load` function in `+page.js` or `+page.server.js`. This can be done with `page.data`:
```svelte
- {$page.data.title}
+ {page.data.title}
```
-Type information for `$page.data` is provided by `App.PageData`.
+Type information for `page.data` is provided by `App.PageData`.
+
+> [!LEGACY]
+> `$app/state` was added in SvelteKit 2.12. If you're using an earlier version or are using Svelte 4, use `$app/stores` instead.
+> It provides a `page` store with the same interface that you can subscribe to, e.g. `$page.data.title`.
## Universal vs server
@@ -166,13 +188,15 @@ Conceptually, they're the same thing, but there are some important differences t
Server `load` functions _always_ run on the server.
-By default, universal `load` functions run on the server during SSR when the user first visits your page. They will then run again during hydration, reusing any responses from [fetch requests](#making-fetch-requests). All subsequent invocations of universal `load` functions happen in the browser. You can customize the behavior through [page options](page-options). If you disable [server side rendering](page-options#ssr), you'll get an SPA and universal `load` functions _always_ run on the client.
+By default, universal `load` functions run on the server during SSR when the user first visits your page. They will then run again during hydration, reusing any responses from [fetch requests](#Making-fetch-requests). All subsequent invocations of universal `load` functions happen in the browser. You can customize the behavior through [page options](page-options). If you disable [server-side rendering](page-options#ssr), you'll get an SPA and universal `load` functions _always_ run on the client.
+
+If a route contains both universal and server `load` functions, the server `load` runs first.
A `load` function is invoked at runtime, unless you [prerender](page-options#prerender) the page — in that case, it's invoked at build time.
### Input
-Both universal and server `load` functions have access to properties describing the request (`params`, `route` and `url`) and various functions (`fetch`, `setHeaders`, `parent` and `depends`). These are described in the following sections.
+Both universal and server `load` functions have access to properties describing the request (`params`, `route` and `url`) and various functions (`fetch`, `setHeaders`, `parent`, `depends` and `untrack`). These are described in the following sections.
Server `load` functions are called with a `ServerLoadEvent`, which inherits `clientAddress`, `cookies`, `locals`, `platform` and `request` from `RequestEvent`.
@@ -182,7 +206,7 @@ Universal `load` functions are called with a `LoadEvent`, which has a `data` pro
A universal `load` function can return an object containing any values, including things like custom classes and component constructors.
-A server `load` function must return data that can be serialized with [devalue](https://github.com/rich-harris/devalue) — anything that can be represented as JSON plus things like `BigInt`, `Date`, `Map`, `Set` and `RegExp`, or repeated/cyclical references — so that it can be transported over the network. Your data can include [promises](#streaming-with-promises), in which case it will be streamed to browsers.
+A server `load` function must return data that can be serialized with [devalue](https://github.com/rich-harris/devalue) — anything that can be represented as JSON plus things like `BigInt`, `Date`, `Map`, `Set` and `RegExp`, or repeated/cyclical references — so that it can be transported over the network. Your data can include [promises](#Streaming-with-promises), in which case it will be streamed to browsers. If you need to serialize/deserialize custom types, use [transport hooks](hooks#Universal-hooks-transport).
### When to use which
@@ -190,7 +214,29 @@ Server `load` functions are convenient when you need to access data directly fro
Universal `load` functions are useful when you need to `fetch` data from an external API and don't need private credentials, since SvelteKit can get the data directly from the API rather than going via your server. They are also useful when you need to return something that can't be serialized, such as a Svelte component constructor.
-In rare cases, you might need to use both together — for example, you might need to return an instance of a custom class that was initialised with data from your server.
+In rare cases, you might need to use both together — for example, you might need to return an instance of a custom class that was initialised with data from your server. When using both, the server `load` return value is _not_ passed directly to the page, but to the universal `load` function (as the `data` property):
+
+```js
+/// file: src/routes/+page.server.js
+/** @type {import('./$types').PageServerLoad} */
+export async function load() {
+ return {
+ serverMessage: 'hello from server load function'
+ };
+}
+```
+
+```js
+/// file: src/routes/+page.js
+// @errors: 18047
+/** @type {import('./$types').PageLoad} */
+export async function load({ data }) {
+ return {
+ serverMessage: data.serverMessage,
+ universalMessage: 'hello from universal load function'
+ };
+}
+```
## Using URL data
@@ -200,7 +246,7 @@ Often the `load` function depends on the URL in one way or another. For this, th
An instance of [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL), containing properties like the `origin`, `hostname`, `pathname` and `searchParams` (which contains the parsed query string as a [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object). `url.hash` cannot be accessed during `load`, since it is unavailable on the server.
-> In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](adapter-node), for example, you may need to configure the adapter in order for the URL to be correct.
+> [!NOTE] In some environments this is derived from request headers during server-side rendering. If you're using [adapter-node](adapter-node), for example, you may need to configure the adapter in order for the URL to be correct.
### route
@@ -234,7 +280,7 @@ To get data from an external API or a `+server.js` handler, you can use the prov
- It can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers for the page request.
- It can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context).
- Internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call.
-- During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text` and `json` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](hooks#server-hooks-handle).
+- During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text`, `json` and `arrayBuffer` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](hooks#Server-hooks-handle).
- During hydration, the response will be read from the HTML, guaranteeing consistency and preventing an additional network request - if you received a warning in your browser console when using the browser `fetch` instead of the `load` `fetch`, this is why.
```js
@@ -250,7 +296,7 @@ export async function load({ fetch, params }) {
## Cookies
-A server `load` function can get and set [`cookies`](types#public-types-cookies).
+A server `load` function can get and set [`cookies`](@sveltejs-kit#Cookies).
```js
/// file: src/routes/+layout.server.js
@@ -278,12 +324,10 @@ Cookies will only be passed through the provided `fetch` function if the target
For example, if SvelteKit is serving my.domain.com:
- domain.com WILL NOT receive cookies
- my.domain.com WILL receive cookies
-- api.domain.dom WILL NOT receive cookies
+- api.domain.com WILL NOT receive cookies
- sub.my.domain.com WILL receive cookies
-Other cookies will not be passed when `credentials: 'include'` is set, because SvelteKit does not know which domain which cookie belongs to (the browser does not pass this information along), so it's not safe to forward any of them. Use the [handleFetch hook](hooks#server-hooks-handlefetch) to work around it.
-
-> When setting cookies, be aware of the `path` property. By default, the `path` of a cookie is the current pathname. If you for example set a cookie at page `admin/user`, the cookie will only be available within the `admin` pages by default. In most cases you likely want to set `path` to `'/'` to make the cookie available throughout your app.
+Other cookies will not be passed when `credentials: 'include'` is set, because SvelteKit does not know which domain which cookie belongs to (the browser does not pass this information along), so it's not safe to forward any of them. Use the [handleFetch hook](hooks#Server-hooks-handleFetch) to work around it.
## Headers
@@ -297,8 +341,8 @@ export async function load({ fetch, setHeaders }) {
const url = `https://cms.example.com/products.json`;
const response = await fetch(url);
- // cache the page for the same length of time
- // as the underlying data
+ // Headers are only set during SSR, caching the page's HTML
+ // for the same length of time as the underlying data.
setHeaders({
age: response.headers.get('age'),
'cache-control': response.headers.get('cache-control')
@@ -308,7 +352,7 @@ export async function load({ fetch, setHeaders }) {
}
```
-Setting the same header multiple times (even in separate `load` functions) is an error — you can only set a given header once. You cannot add a `set-cookie` header with `setHeaders` — use `cookies.set(name, value, options)` instead.
+Setting the same header multiple times (even in separate `load` functions) is an error. You can only set a given header once using the `setHeaders` function. You cannot add a `set-cookie` header with `setHeaders` — use `cookies.set(name, value, options)` instead.
## Using parent data
@@ -343,15 +387,15 @@ export async function load({ parent }) {
```svelte
{data.a} + {data.b} = {data.c}
```
-> Notice that the `load` function in `+page.js` receives the merged data from both layout `load` functions, not just the immediate parent.
+> [!NOTE] Notice that the `load` function in `+page.js` receives the merged data from both layout `load` functions, not just the immediate parent.
Inside `+page.server.js` and `+layout.server.js`, `parent` returns data from parent `+layout.server.js` files.
@@ -359,16 +403,21 @@ In `+page.js` or `+layout.js` it will return data from parent `+layout.js` files
Take care not to introduce waterfalls when using `await parent()`. Here, for example, `getData(params)` does not depend on the result of calling `parent()`, so we should call it first to avoid a delayed render.
-```diff
+```js
/// file: +page.js
+// @filename: ambient.d.ts
+declare function getData(params: Record): Promise<{ meta: any }>
+
+// @filename: index.js
+// ---cut---
/** @type {import('./$types').PageLoad} */
export async function load({ params, parent }) {
-- const parentData = await parent();
+ ---const parentData = await parent();---
const data = await getData(params);
-+ const parentData = await parent();
+ +++const parentData = await parent();+++
return {
- ...data
+ ...data,
meta: { ...parentData.meta, ...data.meta }
};
}
@@ -376,7 +425,7 @@ export async function load({ params, parent }) {
## Errors
-If an error is thrown during `load`, the nearest [`+error.svelte`](routing#error) will be rendered. For _expected_ errors, use the `error` helper from `@sveltejs/kit` to specify the HTTP status code and an optional message:
+If an error is thrown during `load`, the nearest [`+error.svelte`](routing#error) will be rendered. For [_expected_](errors#Expected-errors) errors, use the `error` helper from `@sveltejs/kit` to specify the HTTP status code and an optional message:
```js
/// file: src/routes/admin/+layout.server.js
@@ -397,20 +446,24 @@ import { error } from '@sveltejs/kit';
/** @type {import('./$types').LayoutServerLoad} */
export function load({ locals }) {
if (!locals.user) {
- throw error(401, 'not logged in');
+ error(401, 'not logged in');
}
if (!locals.user.isAdmin) {
- throw error(403, 'not an admin');
+ error(403, 'not an admin');
}
}
```
-If an _unexpected_ error is thrown, SvelteKit will invoke [`handleError`](hooks#shared-hooks-handleerror) and treat it as a 500 Internal Error.
+Calling `error(...)` will throw an exception, making it easy to stop execution from inside helper functions.
+
+If an [_unexpected_](errors#Unexpected-errors) error is thrown, SvelteKit will invoke [`handleError`](hooks#Shared-hooks-handleError) and treat it as a 500 Internal Error.
+
+> [!NOTE] [In SvelteKit 1.x](migrating-to-sveltekit-2#redirect-and-error-are-no-longer-thrown-by-you) you had to `throw` the error yourself
## Redirects
-To redirect users, use the `redirect` helper from `@sveltejs/kit` to specify the location to which they should be redirected alongside a `3xx` status code.
+To redirect users, use the `redirect` helper from `@sveltejs/kit` to specify the location to which they should be redirected alongside a `3xx` status code. Like `error(...)`, calling `redirect(...)` will throw an exception, making it easy to stop execution from inside helper functions.
```js
/// file: src/routes/user/+layout.server.js
@@ -430,33 +483,40 @@ import { redirect } from '@sveltejs/kit';
/** @type {import('./$types').LayoutServerLoad} */
export function load({ locals }) {
if (!locals.user) {
- throw redirect(307, '/login');
+ redirect(307, '/login');
}
}
```
-> Don't use `throw redirect()` from within a try-catch block, as the redirect will immediately trigger the catch statement.
+> [!NOTE] Don't use `redirect()` inside a `try {...}` block, as the redirect will immediately trigger the catch statement.
+
+In the browser, you can also navigate programmatically outside of a `load` function using [`goto`]($app-navigation#goto) from [`$app.navigation`]($app-navigation).
-In the browser, you can also navigate programmatically outside of a `load` function using [`goto`](modules#$app-navigation-goto) from [`$app.navigation`](modules#$app-navigation).
+> [!NOTE] [In SvelteKit 1.x](migrating-to-sveltekit-2#redirect-and-error-are-no-longer-thrown-by-you) you had to `throw` the `redirect` yourself
## Streaming with promises
-Promises at the _top level_ of the returned object will be awaited, making it easy to return multiple promises without creating a waterfall. When using a server `load`, _nested_ promises will be streamed to the browser as they resolve. This is useful if you have slow, non-essential data, since you can start rendering the page before all the data is available:
+When using a server `load`, promises will be streamed to the browser as they resolve. This is useful if you have slow, non-essential data, since you can start rendering the page before all the data is available:
```js
-/// file: src/routes/+page.server.js
+/// file: src/routes/blog/[slug]/+page.server.js
+// @filename: ambient.d.ts
+declare global {
+ const loadPost: (slug: string) => Promise<{ title: string, content: string }>;
+ const loadComments: (slug: string) => Promise<{ content: string }>;
+}
+
+export {};
+
+// @filename: index.js
+// ---cut---
/** @type {import('./$types').PageServerLoad} */
-export function load() {
+export async function load({ params }) {
return {
- one: Promise.resolve(1),
- two: Promise.resolve(2),
- streamed: {
- three: new Promise((fulfil) => {
- setTimeout(() => {
- fulfil(3)
- }, 1000);
- })
- }
+ // make sure the `await` happens at the end, otherwise we
+ // can't start loading comments until we've loaded the post
+ comments: loadComments(params.slug),
+ post: await loadPost(params.slug)
};
}
```
@@ -464,35 +524,50 @@ export function load() {
This is useful for creating skeleton loading states, for example:
```svelte
-
+
-
+{/await}
+```
+
+When streaming data, be careful to handle promise rejections correctly. More specifically, the server could crash with an "unhandled promise rejection" error if a lazy-loaded promise fails before rendering starts (at which point it's caught) and isn't handling the error in some way. When using SvelteKit's `fetch` directly in the `load` function, SvelteKit will handle this case for you. For other promises, it is enough to attach a noop-`catch` to the promise to mark it as handled.
+
+```js
+/// file: src/routes/+page.server.js
+/** @type {import('./$types').PageServerLoad} */
+export function load({ fetch }) {
+ const ok_manual = Promise.reject();
+ ok_manual.catch(() => {});
+
+ return {
+ ok_manual,
+ ok_fetch: fetch('/fetch/that/could/fail'),
+ dangerous_unhandled: Promise.reject()
+ };
+}
```
-> On platforms that do not support streaming, such as AWS Lambda, responses will be buffered. This means the page will only render once all promises resolve. If you are using a proxy (e.g. NGINX), make sure it does not buffer responses from the proxied server.
+> [!NOTE] On platforms that do not support streaming, such as AWS Lambda or Firebase, responses will be buffered. This means the page will only render once all promises resolve. If you are using a proxy (e.g. NGINX), make sure it does not buffer responses from the proxied server.
-> Streaming data will only work when JavaScript is enabled. You should avoid returning nested promises from a universal `load` function if the page is server rendered, as these are _not_ streamed — instead, the promise is recreated when the function reruns in the browser.
+> [!NOTE] Streaming data will only work when JavaScript is enabled. You should avoid returning promises from a universal `load` function if the page is server rendered, as these are _not_ streamed — instead, the promise is recreated when the function reruns in the browser.
-> The headers and status code of a response cannot be changed once the response has started streaming, therefore you cannot `setHeaders` or throw redirects inside a streamed promise.
+> [!NOTE] The headers and status code of a response cannot be changed once the response has started streaming, therefore you cannot `setHeaders` or throw redirects inside a streamed promise.
+
+> [!NOTE] [In SvelteKit 1.x](migrating-to-sveltekit-2#Top-level-promises-are-no-longer-awaited) top-level promises were automatically awaited, only nested promises were streamed.
## Parallel loading
@@ -546,11 +621,28 @@ export async function load() {
A `load` function that calls `await parent()` will also rerun if a parent `load` function is rerun.
-Dependency tracking does not apply _after_ the `load` function has returned — for example, accessing `params.x` inside a nested [promise](#streaming-with-promises) will not cause the function to rerun when `params.x` changes. (Don't worry, you'll get a warning in development if you accidentally do this.) Instead, access the parameter in the main body of your `load` function.
+Dependency tracking does not apply _after_ the `load` function has returned — for example, accessing `params.x` inside a nested [promise](#Streaming-with-promises) will not cause the function to rerun when `params.x` changes. (Don't worry, you'll get a warning in development if you accidentally do this.) Instead, access the parameter in the main body of your `load` function.
+
+Search parameters are tracked independently from the rest of the url. For example, accessing `event.url.searchParams.get("x")` inside a `load` function will make that `load` function re-run when navigating from `?x=1` to `?x=2`, but not when navigating from `?x=1&y=1` to `?x=1&y=2`.
+
+### Untracking dependencies
+
+In rare cases, you may wish to exclude something from the dependency tracking mechanism. You can do this with the provided `untrack` function:
+
+```js
+/// file: src/routes/+page.js
+/** @type {import('./$types').PageLoad} */
+export async function load({ untrack, url }) {
+ // Untrack url.pathname so that path changes don't trigger a rerun
+ if (untrack(() => url.pathname === '/')) {
+ return { message: 'Welcome!' };
+ }
+}
+```
### Manual invalidation
-You can also rerun `load` functions that apply to the current page using [`invalidate(url)`](modules#$app-navigation-invalidate), which reruns all `load` functions that depend on `url`, and [`invalidateAll()`](modules#$app-navigation-invalidateall), which reruns every `load` function. Server load functions will never automatically depend on a fetched `url` to avoid leaking secrets to the client.
+You can also rerun `load` functions that apply to the current page using [`invalidate(url)`]($app-navigation#invalidate), which reruns all `load` functions that depend on `url`, and [`invalidateAll()`]($app-navigation#invalidateAll), which reruns every `load` function. Server load functions will never automatically depend on a fetched `url` to avoid leaking secrets to the client.
A `load` function depends on `url` if it calls `fetch(url)` or `depends(url)`. Note that `url` can be a custom identifier that starts with `[a-z]:`:
@@ -575,8 +667,8 @@ export async function load({ fetch, depends }) {
random number: {data.number}
-
+
```
### When do load functions rerun?
@@ -597,16 +689,100 @@ To summarize, a `load` function will rerun in the following situations:
- It references a property of `params` whose value has changed
- It references a property of `url` (such as `url.pathname` or `url.search`) whose value has changed. Properties in `request.url` are _not_ tracked
+- It calls `url.searchParams.get(...)`, `url.searchParams.getAll(...)` or `url.searchParams.has(...)` and the parameter in question changes. Accessing other properties of `url.searchParams` will have the same effect as accessing `url.search`.
- It calls `await parent()` and a parent `load` function reran
-- It declared a dependency on a specific URL via [`fetch`](#making-fetch-requests) (universal load only) or [`depends`](types#public-types-loadevent), and that URL was marked invalid with [`invalidate(url)`](modules#$app-navigation-invalidate)
-- All active `load` functions were forcibly rerun with [`invalidateAll()`](modules#$app-navigation-invalidateall)
+- A child `load` function calls `await parent()` and is rerunning, and the parent is a server load function
+- It declared a dependency on a specific URL via [`fetch`](#Making-fetch-requests) (universal load only) or [`depends`](@sveltejs-kit#LoadEvent), and that URL was marked invalid with [`invalidate(url)`]($app-navigation#invalidate)
+- All active `load` functions were forcibly rerun with [`invalidateAll()`]($app-navigation#invalidateAll)
+
+`params` and `url` can change in response to a `` link click, a [`