SvelteKit 3 Migration Guide
SvelteKit 3 migration guide for SveltyCMS: architectural conventions, breaking changes, and the record of the SvelteKit 3.0 upgrade (active on @sveltejs/kit ^3.0.1).
Status: Completed. SveltyCMS is actively running on SvelteKit 3 (@sveltejs/kit: ^3.0.1) with Svelte 5 runes and Tailwind CSS v4.
This document records the architectural conventions and breaking change migrations adopted for SvelteKit 3.
A) process.env.ORIGIN → event.url.origin / kit.paths.origin
Kit 3.0 removes process.env.ORIGIN. In SveltyCMS, origin resolution is handled via event.url.origin (where request event is available) or configured environment variable:
| File | Line | Change |
|---|---|---|
src/hooks/handle-system-state.ts |
90 | process.env.ORIGIN → event.url.origin |
src/plugins/sitemap/index.server.ts |
50 | process.env.ORIGIN → process.env.SVELTYCMS_ORIGIN (plugin context — no event available) |
B) External Redirects Require allowExternal: true
Kit 3.0 forbids redirects to external URLs by default. OAuth and IdP flows require { allowExternal: true }:
| File | Lines | Change |
|---|---|---|
src/routes/login/+page.server.ts |
490, 500 | redirect(303, authUrl) → redirect(303, authUrl, { allowExternal: true }) |
src/routes/login/oauth/+page.server.ts |
380, 398, 412, 612 | redirect(302, authUrl) → redirect(302, authUrl, { allowExternal: true }) |
C) handleError Returns Status Code
Kit 3.0 allows handleError in hooks.server.ts to influence the HTTP response status code by returning { message, code, status }:
| File | Line | Change |
|---|---|---|
src/hooks.server.ts |
607 | Add return { message, code, status }; after the logger.error() call |
D) fail() Status Code Propagation
Kit 3.0 propagates the status code from fail(status) to the HTTP response automatically. SveltyCMS leverages this across server actions:
src/routes/login/+page.server.ts—fail(401),fail(429)for auth/rate limitingsrc/routes/(app)/config/collectionbuilder/collectionbuilder.server.ts—fail(400),fail(404),fail(500)- All action handlers adhere to explicit error status codes
Verification & Parity
The SvelteKit 3 migration is validated continuously through the CI and local test harness:
bun run check: Validates types against$app/typesand extended$app/tsconfig.bun run test:unit: Vitest suite runs across all 625 test files on SvelteKit 3.bun run test:security: Verifies OAuth external redirects, authentication hooks, and error status handling.