Svelte 5 Migration Without the Mess

Stop rule: If the baseline does not pass before migration, stop. Otherwise you will not know whether the migration caused the failure or merely revealed it.

1. Define the boundary

Know exactly what is changing and how you will recover.

Name the application, repository, owner, and migration decision maker.A migration without an owner tends to collect unfinished exceptions.

Record the current Svelte, SvelteKit, Node, package-manager, and adapter versions.

Create a recoverable branch or backup and prove you can restore it.

List the routes and features that must not break.

Mark high-consequence areas such as authentication, payments, forms, uploads, and private data.

2. Establish a passing baseline

Capture what “working” means before changing syntax.

Install from the lockfile on a clean checkout.

Run the compiler and record every existing error and warning.

Run automated tests and save the result.

Build the current production target successfully.

Manually test the critical user paths and record expected results.

3. Choose and pin the target

Reduce moving parts so a failure has fewer possible causes.

Choose exact target versions for Svelte, SvelteKit, Vite, adapters, and test tools.

Review official migration notes and breaking changes for the chosen versions.

Check third-party packages for Svelte 5 compatibility and replacement risk.

Commit the updated lockfile separately from component conversions.

Restore a passing compiler, test, and build baseline after the dependency update.

4. Migrate one component at a time

Make a behavior map before changing the component API.

Choose a low-risk leaf component for the first migration.

Map export let props to $props(), including defaults, renames, and bindable values.

Classify each $: statement as a derived value or a side effect before converting it.

Convert DOM events and manually handle modifiers or multiple handlers.

Convert dispatched events and every parent listener as one API change.

Map slots, named slots, fallback content, and slot props before introducing snippets.

Explain every captured initial prop that Svelte flags with state_referenced_locally.

5. Control shared state

A gradual migration may keep stores and runes side by side.

List writable, readable, and derived stores used by the component.

Decide whether each store should remain unchanged during component migration.

If moving shared state, use a .svelte.js or .svelte.ts module and preserve its public behavior.

Test subscriptions, cleanup, reset behavior, and state shared across multiple consumers.

6. Protect SSR and hydration

Browser success does not prove server success.

Keep values needed in server HTML out of client-only $effect logic.

Request important routes directly and inspect the server-produced HTML.

Watch for hydration warnings, flicker, duplicated work, and client/server value differences.

Test prerendered, server-rendered, and client-only routes according to their real deployment mode.

7. Verify after every small change

Keep the suspect list short.

Run the compiler with zero unexplained errors or warnings.

Run business-rule tests outside the component.

Run component tests against visible behavior rather than internal syntax.

Run the production build, not only the development server.

Commit the passing component migration before starting the next one.

8. Release with a recovery plan

Production is another test environment, only less forgiving.

Deploy to a staging environment that matches production closely enough to matter.

Run the critical-path smoke test against the deployed build.

Document the rollback trigger and exact rollback procedure.

Record framework versions, known exceptions, and remaining legacy components.

Monitor errors and user-visible failures before declaring the migration complete.

Evidence record

A few recorded facts are more useful than “I think it passed.”

Application or repository

Target Svelte/SvelteKit versions

Baseline date

Planned release date

Latest test/build result

Known exceptions and remaining risks