SvelteKit 3: como migrar com sv migrate e a mudança de $lib que o comando não faz por você

SvelteKit 3: como migrar com sv migrate e a mudança de $lib que o comando não faz por você

SvelteKit 3.0 foi lançado em 1º de outubro de 2026 e quase toda a migração é automatizada com um comando, npx sv migrate sveltekit-3. O que esse comando não faz é mudar $lib para #lib: esse passo é manual. Neste guia você verá o que muda, o que a ferramenta de migração resolve e o que você precisa fazer.

O time do Svelte o apresenta como o mesmo framework com mais polimento e mais segurança de tipos. Para a API do dia a dia é verdade, mas a estrutura do projeto muda: a configuração se muda de arquivo, o alias de importação mais usado se substitui, os módulos de variáveis de ambiente ficam obsoletos e os service workers se configuram de outro jeito.

O que é SvelteKit e em que se diferencia de Svelte?

SvelteKit é o framework oficial de aplicações para Svelte: se encarrega do roteamento, do carregamento de dados, do renderizado em servidor e do deploy através de adapters. É para Svelte o que Next.js é para React. Svelte compila os componentes e SvelteKit os converte em uma aplicação desplegável, seja com renderizado em servidor, pré-renderizada como site estático ou como single-page app. Tem licença MIT e se desenvolve em github.com/sveltejs/kit.

O que muda no SvelteKit 3?

O anúncio oficial destaca cinco mudanças, e quatro delas afetam arquivos que você já tem no seu projeto.

A configuração passa de svelte.config.js para vite.config

svelte.config.js não é mais suportado. A configuração agora se passa diretamente ao plugin sveltekit do Vite, e as opções que antes viviam em config.kit.* passam a ser opções de primeiro nível do plugin:

import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter()
		})
	]
});

As opções que não são do SvelteKit se reencaminham para vite-plugin-svelte. Com a mudança desaparecem várias opções:

  • files.lib
  • vitePlugin
  • preloadStrategy
  • prerender.origin, substituída pela nova paths.origin
  • csrf.checkOrigin, substituída por csrf.trustedOrigins

$lib passa a ser #lib

SvelteKit já não gera o alias $lib. Em seu lugar você mesmo declara #lib usando os subpath imports do Node.js, que Vite e TypeScript resolvem de forma nativa. É a mudança que sv migrate não faz por você; os passos estão mais abaixo.

As variáveis de ambiente passam para $app/env

Os módulos $env/... ficam obsoletos em favor de $app/env/private e $app/env/public. $app/environment se renomeia para $app/env, e agora você também pode importá-lo dentro de um service worker.

Os service workers precisam de menos código repetitivo

O módulo $service-worker foi eliminado e suas exportações se distribuem entre módulos padrão:

  • version vem de $app/env.
  • assets, immutable e prerendered vêm do novo $app/manifest.
  • As utilidades de rotas vêm de $app/paths.

Um novo módulo, $app/service-worker, lhe dá um contexto de service worker com tipos. Além disso, SvelteKit agora registra o service worker como módulo ES e não como script clássico.

A quinta mudança destacada é o tratamento de erros. No SvelteKit 3, handleError recebe todos os erros, incluindo os esperados que você cria com error(...), e os erros de renderizado são enviados ao +error.svelte mais próximo.

O que você precisa antes de migrar para SvelteKit 3?

Segundo o guia oficial de migração, SvelteKit 3 exige essas versões mínimas:

Dependência Mínimo
Node 22.17
TypeScript 6
Svelte 5.57.1
Vite 8.0.12
@sveltejs/vite-plugin-svelte 7

O time do Svelte recomenda atualizar primeiro para a última versão 2.x, porque essa versão mostra avisos de obsolescência dirigidos exatamente ao código que você terá que mudar. Faça commit do seu projeto antes de começar: se a árvore de trabalho tem mudanças sem confirmar, sv migrate te avisará.

Como migrar para SvelteKit 3 com sv migrate?

O anúncio de lançamento propõe um comando que faz tudo de uma vez:

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

A documentação do CLI recomenda uma abordagem mais prudente: execute uma tarefa por vez e faça commit depois de cada uma, para que cada diff seja fácil de revisar. Para ver as tarefas disponíveis sem executar nada, use:

npx sv migrate sveltekit-3 --tasks

A migração sveltekit-3 é composta de nove tarefas. As duas primeiras são requisitos prévios e se executam sempre:

Tarefa O que faz
package-json Atualiza as versões dos pacotes para SvelteKit 3
tsconfig Faz seu tsconfig.json estender $app/tsconfig em vez de .svelte-kit/tsconfig.json
svelte-config Move as opções suportadas de svelte.config.* para vite.config.*
environment Substitui os módulos de ambiente antigos por $app/env e cria as declarações src/env.js ou src/env.ts quando faltam
paths Migra as APIs obsoletas de $app/paths (base, assets e resolveRoute se substituem por asset() e resolve())
external-redirects Adapta os redirecionamentos externos ao novo comportamento
shallow-routing Substitui pushState e replaceState por goto(..., { shallow: true })
params Reúne os param matchers em um único src/params.js ou src/params.ts
app-state Migra $app/stores para $app/state

Para executar uma única tarefa:

npx sv migrate sveltekit-3 --tasks svelte-config

A documentação adverte que o projeto não precisa funcionar se apenas algumas tarefas foram executadas: a maioria das aplicações precisa de todas as que lhes correspondem. A ferramenta apenas reescreve os padrões que consegue identificar com segurança. Onde não consegue, deixa um comentário @migration-task, então procure por esse marcador exato no projeto antes de considerar a migração concluída.

Como corrigir $lib depois de migrar para SvelteKit 3?

$lib não aparece na lista de tarefas. Quando sv migrate termina, cada importação com $lib no seu código continua apontando para um alias que SvelteKit 3 já não gera. Para corrigi-lo são necessários três passos.

1. Declare #lib em package.json:

{
	"imports": {
		"#lib": "./src/lib/index.js",
		"#lib/*": "./src/lib/*"
	}
}

2. Substitua $lib por #lib em todo o código.

3. Adicione a extensão de arquivo a essas importações. Os subpath imports a exigem, então a mudança não é um simples localizar e substituir do prefixo:

// antes
import { foo } from '$lib/foo';
// depois
import { foo } from '#lib/foo.js';

A opção files.lib também desapareceu: se você havia personalizado seu diretório lib, aponte as entradas de imports para esse diretório.

O que mais pode quebrar em produção?

Essas mudanças do guia de migração modificam o comportamento em tempo de execução, e algumas não produzem nenhum erro de build:

  • $app/stores foi eliminado, não apenas ficou obsoleto. A tarefa app-state migra os arquivos .svelte, então verifique se há usos restantes em outros arquivos.
  • adapter-node elimina a variável de ambiente ORIGIN. Defina paths.origin em sua configuração do Vite.
  • adapter-vercel não suporta mais o runtime edge.
  • As APIs do Cloudflare saem de platform. Importe env de cloudflare:workers; cf agora é uma propriedade de request.
  • Os redirecionamentos externos precisam de permissão explícita. Passe { external: true } ou uma lista de origens permitidas para redirect(...).
  • Os nomes de cookies devem ser ASCII. SvelteKit agora usa cookie v2, que rejeita caracteres não ASCII como á nos nomes dos cookies. Vale a pena revisar em aplicações em português.
  • Os cookies usam path: '/' por padrão, em vez da rota da requisição atual.
  • error(...) recebe uma string como segundo argumento. As propriedades adicionais agora vão em um terceiro argumento.
  • goto() rejeita URLs que não correspondem a uma rota da sua aplicação. Para navegar para um site externo, use window.location.href.
  • As respostas 2xx vazias são devolvidas sem corpo, conforme exigido pela especificação HTTP.

As remote functions estão prontas no SvelteKit 3?

Ainda não. No momento da publicação desta nota, as remote functions continuavam sendo experimentais: exigem a flag experimental.remoteFunctions junto com a opção assíncrona do compilador Svelte. O time do Svelte as marca como sua máxima prioridade. Se você estava esperando por elas, ainda assim vale a pena atualizar agora, porque a migração não depende delas.


Se você está acompanhando outras atualizações maiores desta temporada, já contamos o que muda no htmx 4.0 se você vem do htmx 2.