cachesdev/svelte-deep-knowledge

Conhecimento Profundo de Svelte

Use este como um índice de lacunas de conhecimento prováveis. Verifique as APIs relevantes contra o MCP oficial do Svelte durante o planejamento e a implementação.

Verificado em 2026-11-01 contra Svelte 5.57.3, SvelteKit 3.1.1 e SvelteKit 2.70.3.

Comece com as versões instaladas

1. Inspecione as versões dos pacotes e a configuração do Vite. Combine as orientações com a versão principal do Kit instalada e os sinalizadores experimentais ativados.
2. Chame list-sections do MCP do Svelte e, em seguida, busque as seções relevantes junto com get-documentation. O MCP e svelte.dev servem a documentação do Kit 3. Para um projeto Kit 2, leia a página correspondente do branch version-2 de sveltejs/kit em documentation/docs.
3. Para projetos Kit 3 e migrações Kit 2 → 3, leia a referência do Kit 3. Para projetos Kit 2, leia a referência do Kit 2.
4. Execute svelte-autofixer em componentes/módulos Svelte novos ou editados e resolva as conclusões aplicáveis. Use as verificações do projeto para integração e tipos.

Para exemplos de novas APIs do Svelte, renderização assíncrona, anexos e ferramentas do compilador, leia a referência do Svelte.

Funções remotas, limites e await

Para novos aplicativos SvelteKit que adotam async experimental, prefira funções remotas com await direto para dados de componentes e limites granulares para UI de carregamento/erro. Escolha o posicionamento de svelte:boundary com base no que deve ser renderizado no servidor.

• Ative experimental.remoteFunctions e compilerOptions.experimental.async juntos. A configuração oficial de funções remotas requer ambos os sinalizadores.
• load, ações de formulário e rotas +server continuam suportados, mas não incentivados. Siga a arquitetura existente, a menos que a tarefa inclua migração.
• .loading, .error e .current continuam sendo APIs de consulta suportadas. O await direto é o mecanismo preferido.
• Use await query(args) em contextos de renderização e imperativos.
• {#await} continua suportado, embora não seja incentivado, e tem seu próprio comportamento de estado de promessa. Use await direto e limites para renderização assíncrona coordenada; preserve {#await} quando seu comportamento se adequar à tarefa.

Verifique com as seções do MCP kit/remote-functions, svelte/await-expressions e svelte/svelte-boundary.

Comportamento de renderização assíncrona

• Await em nível de componente chegou no Svelte 5.36; SSR assíncrono chegou no 5.39. Await é suportado no script de nível superior, $derived e marcação.
• Svelte coordena atualizações de UI dependentes enquanto o trabalho assíncrono é resolvido. Expressões await de template independentes são executadas simultaneamente. Awaits sequenciais de script ainda criam cascatas; inicie o trabalho independente antes de aguardar seus resultados.
• O snippet pending de um limite aparece na criação inicial. Use $effect.pending() para trabalho subsequente nesse limite; sua contagem exclui limites filhos.
• Durante o SSR, um limite com pending renderiza o placeholder e pula seu conteúdo. Expressões await fora de tais limites resolvem antes que await render(...) seja concluído. Coloque o conteúdo necessário no HTML inicial de acordo. Esta API ainda não fornece SSR com streaming.
• $state.eager(value), adicionado no 5.41, expõe feedback imediato enquanto as atualizações coordenadas esperam. Use para feedback do usuário, como um indicador de navegação ativo.
• tick() espera por mudanças de estado pendentes; settled(), adicionado no 5.36, também espera pelo trabalho assíncrono causado por elas e pelas atualizações de DOM resultantes.

Limites de erro

• <svelte:boundary> suporta failed(error, reset) e onerror(error, reset) para falhas de renderização/efeito. Trate erros de manipulação de eventos e de async desconectados em seus locais de chamada.
• Snippets failed também capturam erros durante o SSR, desde o Svelte 5.53. No SvelteKit, o erro passa por handleError primeiro, então o snippet recebe o App.Error sanitizado. onerror é executado quando o limite com falha é hidratado.
• O Kit 3 envia erros de renderização através de handleError para o +error.svelte mais próximo, que atua como um limite. Um handleError assíncrono do cliente precisa de compilerOptions.experimental.async. O Kit 2.54+ precisa de experimental.handleRenderingErrors para a mesma integração.
• A nota "desde 5.51" mais antiga da documentação do limite entra em conflito com o changelog publicado. Use 5.53 como a versão de introdução e verifique os patches atuais ao diagnosticar problemas de SSR/hidratação.

Recursos de template

Tags de declaração, Svelte 5.56+

• Prefira {let ...} e {const ...} para variáveis locais da marcação. {@const} está documentado como legado e permanece disponível para projetos mais antigos.
• Declarações simples inicializam valores. Use runas explícitas para reatividade: {let count = $state(0)} e {const doubled = $derived(count * 2)}.
• Migrar {@const area = width * height} reativo requer {const area = $derived(width * height)}. Um {const area = width * height} simples não é reativo.
• Declarações usam escopo léxico dentro de seu elemento/bloco, podem sombrear variáveis externas e devem preceder o uso. Vários declaradores são suportados.

Anexos

• Prefira {@attach ...} para novas integrações de elemento no Svelte 5.29+. Retorne a limpeza do anexo.
• Anexos rastreiam leituras reativas e são executados novamente quando as dependências mudam. Valores falsos os desabilitam. Evite repetir configuração cara lendo opções em mudança através de um getter dentro de um efeito filho.
• Wrappers de componente devem encaminhar props que carregam anexos para o elemento pretendido. createAttachmentKey() suporta anexos em objetos spread.
• fromAction(action, () => argument) preserva o comportamento de uma ação existente. Seu segundo argumento é um getter. Este auxiliar chegou no 5.32, depois dos próprios anexos.

Classes, bindings e HTML

• class aceita arrays e objetos aninhados desde 5.16. ClassValue de svelte/elements está disponível desde 5.19 para props de wrapper.
• Bindings de função usam bind:value={get, set} desde 5.9. Use null como getter para bindings somente leitura.
• Inputs numéricos podem produzir undefined quando vazios ou inválidos. O estado de checkbox pode usar bind:checked e bind:indeterminate; grupos de rádio usam bind:group.
• Inputs suportam defaultValue/defaultChecked desde 5.6. Selects suportam defaultValue desde 5.57, incluindo comportamento de reset de formulário. Verifique a precedência de binding ao fornecer padrões.
• Selects nativos personalizáveis são suportados desde 5.47. Verifique o suporte do navegador e o padrão documentado <selectedcontent> antes de substituir um widget select personalizado.
• Comentários no estilo JavaScript entre atributos são válidos desde 5.53: <div /* explicação */ class="card">.
• {@html} aceita TrustedHTML desde 5.52. O suporte a Trusted Types não sanitiza entrada arbitrária; use uma fonte confiável ou política de sanitização.

Blocos each e snippets

• {#each items as { id, name }} desestrutura itens. A iteração de intervalo pode usar {#each { length: 8 }, index}.
• Prefira chaves de item estáveis para listas cuja identidade importa. Ao editar um item, vincule sua propriedade através do objeto do item para que as mutações atinjam a fonte.
• Snippets são declarados na marcação e renderizados com {@render snippet(...)}. Snippets de nível superior podem ser exportados de <script module> desde 5.5 se não capturarem estado da instância.
• Snippets suportam genéricos desde 5.30. Genéricos de componente usam <script lang="ts" generics="T">.
• No modo runas, variáveis de componente renderizam dinamicamente como <Component />. Componentes recursivos podem importar a si mesmos.

Runas e estado compartilhado

Estado e props

• $state.raw rastreia reatribuição sem proxy profundo. Use para valores grandes substituídos como um todo. $state.snapshot extrai dados simples e respeita toJSON().
• Instâncias de classe não são tratadas com proxy profundo. Use campos $state, ou sua primeira atribuição no construtor desde 5.31. Campos reativos tornam-se accessors não enumeráveis; preserve this ao passar métodos como callbacks.
• Passar um valor reativo para uma função passa seu valor atual. Passe um getter quando a função precisar de valores futuros. Desestruturar um proxy também lê os valores atuais.
• Use .svelte.js/.svelte.ts para lógica de runas compartilhada. Exporte um objeto de estado estável ou accessors quando os consumidores precisarem de estado mutável; exportar diretamente estado de runa reatribuído é restrito.
• Escope o estado específico do usuário através do contexto do componente durante o SSR. O estado de módulo compartilhado pode vazar entre requisições.
• $props.id(), adicionado no 5.20, fornece um ID de instância de componente que corresponde entre SSR e hidratação.
• $bindable() declara uma prop vinculável. Props podem ser reatribuídas localmente; mutar o proxy não vinculável de um pai gera avisos de ownership. Valores de fallback não são automaticamente tratados com proxy.
• Mantenha o tipo real não inicializado de $state<T>(), que inclui undefined, ou forneça um valor inicial válido. Use estreitamento nos locais de acesso.

Derivados e efeitos

• Use $derived(expression) ou $derived.by(fn) para valores computados. Derivados declarados com let podem ser reatribuídos para UI otimista desde 5.25; mudanças de dependência os recalculam.
• Valores $derived desestruturados permanecem reativos. Objetos retornados não são automaticamente proxies profundos. Igualdade referencial pode pular trabalho downstream.
• Efeitos rastreiam leituras síncronas de sua execução mais recente. Leituras dentro de um callback assíncrono comum após await não são dependências automáticas.
• $effect é executado no navegador. Retorne a limpeza de forma síncrona; reserve efeitos para sincronização externa e coloque trabalho acionado pelo usuário em handlers.
• $effect.tracking() detecta um contexto de rastreamento. $effect.root() cria um escopo gerenciado manualmente e retorna um dispostor.
• getAbortSignal(), adicionado no 5.35, deve ser executado dentro de um efeito ou derivado. Seu sinal é abortado na reexecução ou destruição. Use para trabalho fetch de propriedade dessa computação reativa.
• untrack(fn) exclui leituras do rastreamento de dependências.
• $inspect(...).with(fn) recebe "init"/"update" seguido por valores. $inspect.trace(label?), adicionado no 5.14, deve ser a primeira instrução na função rastreada.
• $host() é para elementos personalizados e retorna seu elemento DOM hospedeiro.

Módulos de tempo de execução

• createContext<T>() fornece contexto tipado desde 5.40. Desde 5.57 retorna [get, set, has]; has() verifica disponibilidade antes de get(), que lança erro quando não definido. A busca de contexto inclui o componente atual e ancestrais. Chame accessors de contexto durante a inicialização e defina o contexto antes do primeiro await no script. Desde 5.57.1, um setContext posterior lança set_context_after_init durante o SSR.
• svelte/reactivity fornece SvelteMap, SvelteSet, SvelteDate, SvelteURL e SvelteURLSearchParams. Entradas de Map/Set não se tornam profundamente reativas.
• Svelte 5.57 adiciona SvelteMap.getOrInsert(key, value) e getOrInsertComputed(key, key => value). O callback computado é executado quando a chave está ausente, incluindo o tratamento correto de entradas undefined existentes.
• MediaQuery e createSubscriber chegaram no 5.7. Use createSubscriber para conectar eventos externos a leituras rastreadas com configuração e limpeza de assinatura compartilhadas. MediaQuery aceita um fallback de SSR; use CSS quando puder expressar o mesmo comportamento.
• svelte/reactivity/window fornece valores .current reativos para dimensões, posição de rolagem, status online, posição da tela e proporção de pixels desde 5.11. Considere valores de janela indisponíveis durante o SSR.
• on() de svelte/events preserva a ordenação com handlers de evento declarativos e retorna limpeza. Use <svelte:window>/<svelte:document> para listeners globais declarativos.
• flushSync(fn?) libera atualizações pendentes de forma síncrona. createRawSnippet suporta marcação programática com configuração/limpeza. getAllContexts() fornece o mapa de contexto atual para montagem programática; chame durante a inicialização.
• Spring e Tween de svelte/motion substituem os stores spring()/tweened() obsoletos desde 5.8. Ambos expõem .target, .current, .set() e .of(fn). Spring.set suporta preserveMomentum; prefersReducedMotion suporta movimento acessível.
• Desde 5.55, as exportações de motion incluem TweenOptions, SpringOptions, SpringUpdateOptions e Updater.
• hydratable(key, fn), adicionado no 5.44, serializa dados para reutilização durante a hidratação. Ele usa devalue e suporta promessas aninhadas. Chaves com namespace evitam colisões. As funções remotas do Kit já lidam com essa camada.
• Com CSP, integrações SSR personalizadas devem configurar render com um nonce por resposta ou hashes estáticos e colocar valores correspondentes nos cabeçalhos de resposta. Svelte 5.46 adicionou suporte CSP para render; 5.57 exporta RenderOutput, SyncRenderOutput, Csp e Sha256Source de svelte/server.
• Para ferramentas, print() converte um AST Svelte moderno para código fonte desde 5.45; parseCss() chegou no 5.48. As opções do compilador css, runes e customElement podem ser funções dependentes do nome do arquivo desde 5.54. Leia a referência do Svelte antes de usar essas APIs.

SvelteKit

Novos aplicativos usam Kit 3 (npx sv create). Migre um aplicativo Kit 2 com npx sv migrate sveltekit-3 e, em seguida, trabalhe nos TODOs gerados. As orientações do Kit 2 aplicam-se apenas a projetos que permanecem na 2.x.

Linha de base do Kit 3

• O Kit 3 requer Node 22.17, TypeScript 6, Svelte 5.57.1, Vite 8.0.12 e vite-plugin-svelte 7.
• A configuração reside em sveltekit({...}) dentro de vite.config.ts, com as opções do Kit no nível superior ao lado de compilerOptions. O Kit 3 não lê mais svelte.config.js.
• #lib substitui $lib através de imports de subcaminho em package.json. Escreva extensões de arquivo, como #lib/server/db.ts.
• Um segmento de nome de arquivo server, ou qualquer diretório server fora de src/routes, marca um módulo como somente servidor. Um segmento de nome de arquivo remote, como em data.remote.ts ou remote.ts, marca um módulo remoto.
• Declare variáveis de ambiente em src/env.ts com defineEnvVars de @sveltejs/kit/env. Importe valores de $app/env/private e $app/env/public, e browser, building, dev, version de $app/env. Variáveis públicas podem aparecer em app.html como %sveltekit.env.NAME%. $env/* e $app/environment são aliases obsoletos.
• $app/stores foi removido; use $app/state. page.url é somente leitura; copie com new URL(...).