The SvelteKit 3 Release Candidate is here

Skip to main content<br>TutorialPackagesPlaygroundBlog

SvelteKit 3 is now in the Release Candidate phase. If all goes well — meaning that people like you try it out and find that it works as expected — we will follow it up with a stable release in the near future, with no further breaking changes.

But there are some breaking changes since SvelteKit 2. We’re taking advantage of this release to prune some of the weeds in the codebase and lay the groundwork for SvelteKit’s continued evolution, more on which below.

To migrate an existing app, you can use the next version of sv migrate:

npx sv@next migrate sveltekit-3 --tasks all --confirm<br>This will automatically migrate as much of your code as possible. For everything else, it will generate a TODO list for you (or your clanker of choice) to work through. Wherever possible, SvelteKit will print useful diagnostic warnings and errors if you try to run code that hasn’t yet been updated.

To create a new app, run sv create:

npx sv@next create my-new-app<br>What’s changed?<br>For the full list of changes, consult the migration guide over on next.svelte.dev which is where the SvelteKit 3 documentation will live until the stable release. Most changes are fairly minor, but a few are worth calling out:

Configuration now lives in vite.config.ts<br>Previously, you would configure SvelteKit via a svelte.config.js file. This turned out to be limiting: it’s useful for the Vite plugin to have access to your config immediately rather than having to go through an asynchronous resolution process (which can’t begin until after we’ve resolved the entire Vite config, because tools like Vitest may run with a current working directory that isn’t the project root), and after all why wouldn’t we put the config in one place rather than two?

The $lib alias is now #lib<br>In SvelteKit 2, you would put shared code in src/lib and import it via a $lib alias. This is nicer than importing from ../../../../somewhere, which is what inevitably happens in larger codebases.

But in modern projects, aliases are unnecessary, because we have something better: subpath imports. This Node feature is natively supported by tools like Vite and TypeScript, and it means we can delete the code that previously coordinated between them. There is one small gotcha: Node and TypeScript require that your subpath imports be unambiguous — instead of importing from #lib/foo, you will need to import from #lib/foo.ts or #lib/foo/index.ts.

TypeScript configuration got simpler<br>In SvelteKit 2, your tsconfig.json needed to extend the somewhat scruffy-looking ./.svelte-kit/tsconfig.json. In SvelteKit 3, you extend $app/tsconfig instead. This generated config file is written to node_modules/$app and contains configuration that is specific to your app. While it’s simpler than the SvelteKit 2 version (we no longer need to add the $lib alias to "paths", for example) it also includes more recommended compiler options, which means you can likely delete your own compilerOptions unless you have esoteric requirements.

You should explicitly specify your include and exclude arrays, and the latter should include your service worker. Speaking of which:

Service workers got a facelift<br>Using service workers is nicer in SvelteKit 3. Instead of the weird $service-worker module, which exposed the necessary tools to perform offline caching (for example), you can now just import those things from $app/env, $app/paths and the new $app/manifest module like in every other part of your app. You can also import self from $app/service-worker to get accurate typings for fetch events and so on, provided you create a tsconfig.json alongside your service worker that extends $app/tsconfig/service-worker.

In future, we may expose helper functions for different caching strategies, so that it’s easier to build things like offline-friendly PWAs without running into barbed wire.

Environment variables are more powerful<br>SvelteKit already had arguably the most sophisticated and flexible environment variable handling of any framework. SvelteKit 3 takes it a step further with the explicit environment variables feature, which are no longer behind an experimental flag. The gist is that you define which environment variables your app depends on, in src/env.ts, and specify if they should be publicly available (in which case you can import them into code that will run in the client) and whether they should be resolved at build time (in which case they can be used for optimizations like dead code elimination) or when the app boots up. You can also use Standard Schema libraries to validate your environment variables.

In exchange, you get effortless type-safe, secure, validated environment variables that can be auto-imported when you need them.

Error handling is way better<br>SvelteKit 2 was constrained by its support for Svelte 4, which didn’t have a concept of error boundaries. This meant that we could only display your +error.svelte...