SvelteKit 3

Upgrade a SvelteKit 2 project to SvelteKit 3.

Syntax

$ vela migrate sveltekit-3

Vela 0.15 writes SvelteKit 3 code only. In a SvelteKit 2 project, one whose package.json declares @sveltejs/kit 2 or that still has a svelte.config.js, vela bless, vela deploy and the commands that write code, such as enable, disable and generate, refuse to run and point here. vela dev, build, preview and test:server still run, with a one-line warning.

A SvelteKit 2 project pins vela ^0.14, which never moves to 0.15 on its own, so run the migration through npx:

$ npx vela@^0.15 migrate sveltekit-3

Or stay on Vela 0.14, which keeps working with SvelteKit 2.

Options

  • --cwd <path> - The project to migrate, defaults to the current project
  • --no-install - Skip installing dependencies
  • --force - Run even when the git working tree has uncommitted changes
  • --skip-sv - Only run the Vela steps, for a project sv has already migrated

What it does

It needs Node 22.17 or later, and a clean git working tree so the migration’s changes can be reviewed on their own.

First it runs SvelteKit’s own migration, sv migrate sveltekit-3. The config moves out of svelte.config.js into the sveltekit() plugin in vite.config.ts, tsconfig.json extends $app/tsconfig, $lib imports become #lib, environment variables are declared in src/env.ts and read from $app/env, and SvelteKit APIs move to their new modules.

Then it does what a Vela project needs on top:

  • Restores VELA_ORIGIN as paths.origin, which sv drops when it moves the config. See vela build.
  • Declares the variables Vela reads, such as POCKETBASE_URL, in src/env.ts. See vela env.
  • Adds #lib to the package.json imports, points components.json at it, and rewrites the $lib imports sv leaves behind, such as those outside src/.
  • Replaces the i18n $locales alias with a #locales import.
  • Raises the minimum versions of vela and the packages SvelteKit 3 needs, and overrides dependencies that still declare a SvelteKit 2 peer.
  • Drops the lockfile entries that would otherwise make the install fail.

Then it installs dependencies and formats what changed.

What’s left

What can’t be done safely by machine is listed in MIGRATION_TASKS.md, and marked in the code with @migration-task comments. Work through both and delete the file, then run npm run check, vela test:server and npm run build.

Servers need Node 22.17 or later too. Run vela provision on each before the first SvelteKit 3 deploy.

Running the command again is safe. On a project already on SvelteKit 3 it skips sv and only re-checks the Vela steps.