SvelteKit 3 chega a release candidate e move configuração para o Vite

RC marca a reta final antes da versão estável

A equipe do Svelte moveu o SvelteKit 3 para a fase de release candidate em 30 de setembro, segundo reportagem do InfoQ. O time descreve a versão não como um lançamento repleto de recursos novos, mas como uma oportunidade de podar código legado e preparar o terreno para a evolução do framework. Se os testes correrem bem, a versão estável deve sair sem novas mudanças que quebrem compatibilidade.

Isso significa que quem já está testando a RC hoje está, na prática, validando o que vai virar o SvelteKit 3 final. Para times que mantêm aplicações SvelteKit em produção, é o momento de rodar a suíte de testes contra a RC antes que qualquer breaking change chegue sem aviso na versão estável.

Configuração sai do svelte.config.js e vai para o Vite

A mudança mais visível é onde o projeto guarda sua configuração. O svelte.config.js, que existia desde o SvelteKit 2, desaparece: agora a configuração fica dentro do vite.config.ts, para que o plugin do Vite consiga lê-la de forma síncrona, em vez de esperar uma etapa assíncrona que só começava depois que toda a configuração do Vite terminasse de resolver.

A documentação de referência do projeto registra que configurar via Vite já era possível desde a versão 2.62 - a RC apenas fecha uma transição que já estava em andamento. Quem já tinha migrado a configuração nessa versão anterior não deve sentir o impacto agora; quem ainda está no modelo antigo precisa mover o arquivo antes de atualizar.

$lib vira #lib: a mudança que dividiu opiniões

A parte mais debatida da RC é a aposentadoria do alias $lib, substituído por #lib. A troca se apoia nos subpath imports nativos do Node, declarados no package.json, em vez de um caminho específico do SvelteKit que Vite e TypeScript↳TypeScript23 conteúdosTypeScript: ReadonlyArrayDev (Back & Front) · jun 2019Onde usar ANY no TypeScriptDev (Back & Front) · out 2025Tudo sobre o Node rodar TypeScript nativamente!Dev (Back & Front) · jul 2025Ver tudo em Dev (Back & Front) → precisavam coordenar manualmente. Na prática, $lib/foo agora precisa virar #lib/foo.js - com extensão de arquivo explícita.

No Reddit, um desenvolvedor reclamou da inconsistência criada pela mudança:

Odeio a mudança de $lib para #lib, agora fica inconsistente com outras coisas como $app. Espero que não seja obrigatório usar #lib e que a gente possa usar qualquer alias que quiser

I hate the $lib -> #lib change, it now makes it inconsistent with other things like $app. Hopefully it's not enforced to be #lib and we can just use whatever alias we wantDesenvolvedor no Reddit, em thread sobre o SvelteKit 3

Outro usuário respondeu discordando de início, mas mudou de ideia ao entender a lógica por trás da decisão:

Sim, qual a lógica nisso? Edição: ah, não, é uma ótima mudança. Eles estão movendo isso para a definição nativa de alias do package.json. Isso significa que dá pra usar o alias em código de lib/server que você queira rodar sem o SvelteKit também

Yeah what's the logic in that? Edit: oh nvm it's a great change. They're moving it to the native package.json alias definition. This means you can use the alias in lib/server stuff that you might want to run without sveltekit too.Desenvolvedor no Reddit, em resposta ao comentário anterior

O argumento técnico por trás da mudança é que #lib, por ser um alias nativo do Node, funciona em qualquer contexto - inclusive em módulos de servidor que rodam fora do SvelteKit, algo que $lib não permitia por depender do próprio framework para resolver o caminho.

Na issue original do GitHub que discutiu a decisão, o mantenedor Rich Harris foi direto sobre o trade-off: disse que adoraria que todo mundo usasse nodenext, mas reconheceu que os desenvolvedores poderiam se revoltar contra imports sem extensão de arquivo. Para quem discordar da obrigatoriedade, a saída que ele apontou é simples: criar o próprio alias.

Migração tem CLI pronta, mas exige atenção aos detalhes

Para quem já tem aplicação em produção, o time do Svelte publicou um guia de migração que aponta para um comando de CLI:

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

O comando automatiza boa parte da transição, mas dois pontos exigem revisão manual: toda referência a $lib no código - imports, aliases customizados em bibliotecas internas, configuração de editor - precisa ser reescrita para #lib com extensão de arquivo, e o tsconfig.json do projeto passa a estender $app/tsconfig em vez do arquivo antes gerado dentro de .svelte-kit. Times com bases de código grandes devem rodar a migração automatizada e depois caçar manualmente os casos que o script não cobre, como imports dinâmicos ou caminhos construídos em runtime.

Outras mudanças: erros, rotas e o motor por baixo do capô

SvelteKit 3 agora exige Svelte 5, o que destrava uma reformulação no tratamento de erros: componentes +error.svelte renderizam tanto em falhas de load quanto de renderização, todo erro passa por handleError, e stack traces ganham sourcemaps - o que deve tornar debugging em produção menos doloroso. Service workers passam a importar de $app/env, $app/paths e de um novo módulo $app/manifest. Variáveis de ambiente explícitas saem do status experimental e ganham validação opcional via Standard Schema.

O roteamento raso (shallow routing) também muda de API: sai pushState, entra goto com a opção shallow: true. Sob o capô, o framework agora exige Vite 8 e seu bundler Rolldown para builds mais rápidos - mas o time do Svelte decidiu não adotar o FetchableDevEnvironment, argumentando que a proposta força frameworks a absorver complexidade demais.

O que ainda fica de fora

As chamadas remote functions, uma abordagem de RPC cliente-servidor com tipagem segura que ecoa as Server Actions do React e as server functions do Next.js, continuam atrás de uma flag experimental. O próprio time reconhece que, em comparação com essa abordagem, as funções load e actions atuais ficam meio desajeitadas.

Para quem constrói com SvelteKit no Brasil, o recado prático é rodar a RC num branch separado, testar o CLI de migração antes de tocar em produção, e mapear onde $lib aparece na base de código antes que a versão estável remova de vez a rota de compatibilidade. O SvelteKit é o framework oficial de aplicações do Svelte desde o lançamento 1.0, no fim de 2022, e segue como a forma padrão de construir apps com o compilador do Svelte diante de concorrentes como Next.js e Remix.

Fonte: InfoQ