SvelteKit 3.0 Ships: Breaking Changes and How to Fix

SvelteKit 3.0 shipped October 1 — and the headline feature developers were actually waiting for didn’t make the cut. Remote functions, the type-safe RPC system that had been driving excitement about SvelteKit 3 since its release candidate, shipped behind an experimental flag. What did land is a batch of necessary housekeeping: a config relocation, a contested alias rename, and improvements to environment variables and error handling. The migration is not optional if you want to stay current. Here’s what changed, why it matters, and how to fix it fast.

Run This First

Before anything else, run the official migration command:

npx sv migrate sveltekit-3 --tasks all --confirm

This handles the majority of the mechanical work — the alias rename, the config move, the tsconfig update. It won’t catch everything, but it handles the tedious parts so you can focus on what needs human review. Run it in a clean branch and audit the diff before merging.

The Four Changes That Actually Matter

1. $lib Is Now #lib (Prepare for a Search-and-Replace)

The most disruptive change in SvelteKit 3 is the retirement of the $lib alias in favor of #lib. Every import like import { something } from '$lib/utils' in your codebase must become import { something } from '#lib/utils'. The automated migration handles this, but it’s worth understanding why the change happened.

However, SvelteKit is aligning with Node.js native subpath imports — a standard defined in package.json, not a framework-specific invention. The tradeoff is real: $app, $env, and other framework imports still use the $ prefix, so you now have a mixed convention in the same codebase. Maintainer Rich Harris acknowledged the inconsistency, called it the right tradeoff, and offered developers the option to define their own alias if they strongly prefer the old convention.

It’s a defensible decision. It’s also annoying. Both things are true.

2. Config Moves to vite.config.ts

Moreover, SvelteKit configuration now lives in vite.config.ts instead of svelte.config.js. This enables synchronous plugin reading and aligns SvelteKit more closely with the Vite ecosystem. Your tsconfig.json should now extend $app/tsconfig rather than the generated .svelte-kit file. The sv migrate command handles the move — spot-check the result afterwards.

3. Environment Variables Are Now a First-Class Feature

Furthermore, environment variable handling, previously behind an experimental flag, is now stable. You define your env vars in src/env.ts and can use Standard Schema-compatible libraries — Zod, Valibot, ArkType — to validate them at startup. Validation errors surface immediately at boot rather than at runtime when a missing variable is first accessed. If you had env var handling scattered in utility files, this is a good time to consolidate.

4. Error Handling and Service Workers Got Cleaned Up

+error.svelte components now render on both load failures and render failures, and every error flows through handleError — no more edge cases where errors slipped through without going through your central handler. Stack traces get sourcemaps now, making debugging production errors significantly less painful. Service workers shed some boilerplate, pulling configuration from $app/env and $app/paths rather than the generated .svelte-kit directory.

Remote Functions: Not Yet, But Close

Remote functions are the feature that made SvelteKit 3 worth watching. The idea: write server-side functions in .remote.ts files, export them, and import them in your components as if they were local. SvelteKit compiles them into HTTP endpoints and generates typed client wrappers. Individual components can fetch and mutate data without page-wide refreshes or route-level load functions. The design is cleaner than Next.js Server Actions — which were primarily built for mutations, not queries — and the four explicit function types (query, form, command, prerender) make the intent obvious.

However, they’re not here yet. Remote functions still require Async Svelte support, which itself requires an experimental flag. The team calls them their top priority. The next milestone to watch is Svelte Summit on November 19-20 in Ljubljana, where the Svelte project celebrates its tenth anniversary — a plausible target for the stable release announcement.

Should You Switch From Next.js?

If you’re starting a new project and don’t have React legacy to protect, SvelteKit is worth a serious look. The State of JS 2025 data is hard to dismiss: 93% developer satisfaction for SvelteKit versus 74% for Next.js — and that Next.js number has been falling since 2023, when it stood at 89%. Performance metrics tell a similar story: 1.2 seconds time-to-interactive and a 42KB gzipped bundle versus 2.8 seconds and 120KB for Next.js.

In fact, the gap in weekly downloads — 500K for SvelteKit, 6.5M for Next.js — reflects inertia more than merit. Most teams don’t switch their primary framework for a greenfield project; they reach for what they know. But for teams feeling the friction of Next.js’s App Router migration, React Server Components complexity, or Vercel pricing, SvelteKit 3 is the most credible alternative it has ever been.

Therefore, if you’re already on Next.js with a large codebase and team, the switching cost probably isn’t worth it today. Wait for remote functions to ship stable, then reassess.

The Bottom Line

SvelteKit 3.0 is a cleanup release dressed up as a major version. The breaking changes are real but manageable — run sv migrate, review the output, and you’re mostly done in an afternoon. The excitement about SvelteKit 3 was always really about remote functions, and those are still coming. The version number is here; the feature is not. Watch Svelte Summit in November for the stable announcement.

For the full migration guide, see the official SvelteKit 3 release post and release candidate notes.