# 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`](/bless), [`vela deploy`](/deploy) and the commands that write code, such as [`enable`](/enable), [`disable`](/disable) and [`generate`](/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`](/build).
- Declares the variables Vela reads, such as `POCKETBASE_URL`, in `src/env.ts`. See [`vela env`](/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](/enable/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`](/test) and `npm run build`.

Servers need Node 22.17 or later too. Run [`vela provision`](/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.