Skip to content

SvelteKit 3 Migration: What Changes Before You Upgrade

SvelteKit 3 is now stable, but upgrading from SvelteKit 2 involves changes to Vite configuration, imports, navigation, errors, service workers, dependencies, and deployment adapters.

SvelteKit 3 Migration: What Changes Before You Upgrade

On this page

SvelteKit 3 arrived on October 1 with a major version change that is less about adding flashy features and more about removing framework-specific machinery. The biggest upgrade work is concentrated in configuration, imports, dependencies, navigation APIs, error handling, and adapters, while the official sv migrate command can automate part of the transition. That makes SvelteKit 3 easier to approach than many major releases, but it does not make an existing application upgrade-free.

SvelteKit 3 migration starts with a newer toolchain

Before changing application code, the first thing to check is the runtime underneath SvelteKit. Version 3 requires Node.js 22.17 or newer, TypeScript 6, Svelte 5.57.1, Vite 8.0.12, and version 7 of the Svelte Vite plugin. These requirements matter because the framework is moving more of its configuration into Vite rather than maintaining a separate configuration layer. An application that still depends on an older Node.js or Vite environment therefore needs a toolchain upgrade before its SvelteKit migration is complete.

The safest starting point is to bring an existing project to the latest SvelteKit 2 release first. The migration documentation specifically recommends this because the 2.x releases can expose targeted deprecation warnings before the major upgrade. That gives developers a cleaner list of changes to resolve instead of discovering old APIs and version incompatibilities simultaneously. For a production application, creating a separate upgrade branch and running the normal test and build pipeline before touching application behavior is also a practical way to isolate framework changes from unrelated fixes.

The biggest configuration change moves SvelteKit into Vite

SvelteKit 3 no longer supports svelte.config.js as the place for project configuration. Configuration that previously lived under the SvelteKit configuration object now moves into the SvelteKit plugin inside vite.config.ts. This is more than a file rename: options are now handled alongside the rest of the Vite configuration, while settings that belong to the Svelte compiler or Vite plugin can live in the same configuration flow. The result is a more conventional Vite setup, but projects with custom configuration need to review each option rather than simply moving the old file wholesale.

Several older settings disappear or change names during this move. For example, prerender.origin becomes paths.origin, while csrf.checkOrigin is replaced by csrf.trustedOrigins. The latter change deserves attention because cross-origin form submissions are now handled through an explicit trusted-origin model rather than a switch that disables origin checking. If an application sits behind a reverse proxy or integrates with an external service that submits forms, its production configuration should be tested rather than assuming the old behavior carries forward.

The $lib alias becomes #lib

One of the most visible source-code changes in SvelteKit 3 is the removal of the automatically generated $lib alias. It is replaced by #lib, using Node.js subpath imports declared in package.json. In practical terms, imports that previously looked like $lib/server need to use the new alias and include the appropriate module extensions where required. This change reduces a SvelteKit-specific convention in favor of a mechanism understood by Node.js, TypeScript, and Vite.

The migration tool can rewrite many of these imports automatically, which is useful for a large application with hundreds of files. The important distinction is that automated rewriting changes syntax; it does not prove that every custom import, build plugin, test environment, or generated file behaves correctly afterward. Search the resulting project for remaining $lib references and run the complete test suite before considering the migration finished. A clean build is necessary, but applications with server-side code should also exercise their actual routes and data-loading paths.

Navigation APIs have several changes that can alter behavior

SvelteKit 3 also changes parts of its navigation API. For shallow routing, pushState and replaceState are deprecated in favor of goto, while invalidateAll is deprecated in favor of refreshAll. The newer approach also changes how options such as focus, scrolling, and history replacement are expressed. These are easy changes to miss because the application can continue compiling while its navigation behavior becomes subtly different.

Another change affects code that expects a navigation call to succeed regardless of the destination. SvelteKit 3 makes goto reject when a URL does not resolve to an application route, and external navigation needs to use the browser's location mechanism instead. Shallow navigation also participates more directly in navigation hooks, so applications with custom analytics, focus management, or transition logic should test those hooks rather than assuming the old event sequence remains unchanged. These details matter most in applications with complex client-side navigation, not simple sites with mostly ordinary links.

Error handling is more consistent, but old assumptions can break

SvelteKit 3 changes how errors move through an application. The handleError hook now receives all errors, including errors created with the framework's error helper, and rendering errors are routed through the same handling path before reaching an error boundary. Form actions also use the HTTP status supplied to fail instead of always returning a successful 200 response for enhanced submissions. For applications that inspect response status codes, log errors, or build custom error pages, these changes can affect both application behavior and tests.

The framework also removes several older APIs around error and server internals. Helpers such as json and text are deprecated in favor of the standard Response APIs, while internal error classes should no longer be imported for type or instance checks. This is part of a broader pattern in the release: SvelteKit is leaning more heavily on platform and web-standard behavior instead of maintaining its own parallel abstractions. That can mean fewer framework-specific concepts over time, but it also means older application code needs a deliberate cleanup pass.

Service workers and environment APIs need a separate review

Service-worker code has several migration points that are easy to overlook because it often lives outside the main route tree. The old $service-worker module has been removed, with functionality distributed among newer modules such as $app/env, $app/manifest, and $app/paths. SvelteKit 3 also provides a dedicated $app/service-worker module for type-safe access to the service-worker execution context. Projects that use offline caching, precaching, or custom service-worker logic should therefore treat this as its own migration task rather than relying only on the general codemod.

Environment-variable imports are changing as well. The older $env modules are deprecated in favor of $app/env/private and $app/env/public, while the environment module itself has been renamed from $app/environment to $app/env. The distinction between server-only and browser-safe configuration remains important, so this is not a good area for blind search-and-replace. Check which variables are intended to reach the client before changing their imports.

Adapters are part of the SvelteKit 3 upgrade

A SvelteKit application is not finished when the framework package itself builds; its deployment adapter has to match the new architecture too. The first-party adapters have their own SvelteKit 3 changes, including updates to Node, Netlify, Vercel, and Cloudflare behavior. For example, the Node adapter now uses Rolldown for bundling and removes the old ORIGIN environment-variable approach in favor of paths.origin. The Vercel adapter no longer supports the edge runtime, while the Netlify adapter changes its output and requires a newer Netlify CLI for deployment and preview workflows.

That makes deployment testing one of the most important parts of the upgrade. A local development server can pass while a production adapter exposes different behavior around static files, redirects, environment variables, or edge execution. The migration guide documents these adapter-specific differences, so teams should check the adapter they actually deploy with rather than treating the framework upgrade as a purely application-level change. For organizations maintaining custom adapters, SvelteKit 3 also removes or changes several builder APIs, making the upgrade considerably deeper.

Remote functions are still experimental

SvelteKit 3 arrives with remote functions still marked as experimental, despite the feature receiving substantial attention during development. Remote functions are designed to provide typed client-server communication without requiring developers to manually maintain the same kind of API layer for every server operation. The stable SvelteKit 3 release explicitly says they are not ready yet and require an experimental flag, so production applications should not treat them as a finished replacement for existing endpoints.

This distinction is useful when evaluating the release because the presence of a major architectural feature in the documentation does not mean its API has the stability guarantees of the rest of the framework. Developers can experiment with remote functions, but applications that need predictable long-term behavior should separate that experimentation from the core migration. A SvelteKit 3 upgrade does not require rewriting an application's existing server communication around remote functions.

The migration command handles work, not the final decision

The official migration command is the practical starting point for an existing project: npx sv migrate sveltekit-3 --tasks all --confirm. Svelte says the command automatically migrates as much as it can and produces a TODO list for changes that still require developer attention. That is valuable because mechanical changes such as dependency updates and alias replacements are precisely the kind of work a migration tool can perform consistently. It should still be treated as a patch generator rather than proof that the application is compatible.

After running it, the useful test is not simply whether the development server starts. Build the application, run its automated tests, exercise authentication and form submissions, check server-only imports, test service workers if present, and perform a deployment using the project's real adapter. Pay particular attention to custom navigation, redirects, CSRF rules, environment variables, and any code importing framework internals. SvelteKit 3 makes the mechanical part of the migration relatively approachable; the remaining work is proving that the application's assumptions still match the framework's new rules.

Copy this post

0 Comments

No comments yet. Be the first to share your thoughts.

Join the conversation

Log in or create a free account to leave a comment. You can edit or delete your own comments any time.