Fundação

Bem-vindo à série de Roteamento do SvelteKit — um guia abrangente em formato de documentação que vai além do básico. Seja você vindo do React Router, Vue Router, ou construindo sua primeira aplicação web moderna, esta série fornecerá a compreensão profunda que separa desenvolvedores júnior de engenheiros sênior.

Ao longo desta série, você aprenderá sobre rotas, páginas, layouts, carregamento de dados, tratamento de erros e muito mais. Cada artigo mergulha em um arquivo ou conceito específico do sistema de roteamento do SvelteKit, explicando não apenas o "como", mas o crucial "porquê" por trás de cada decisão de design.

Você irá explorar:

Páginas Dinâmicas — Construa páginas que respondem a parâmetros de URL
Páginas de Servidor — Carregue dados de forma segura no servidor
Endpoints de API — Construa uma API backend completa dentro da sua aplicação SvelteKit
Layouts — Compartilhe UI e dados entre múltiplas rotas

Ao final deste artigo, você entenderá o "porquê" filosófico por trás das escolhas de roteamento do SvelteKit e terá um modelo mental claro de como tudo se encaixa.

Entender por que um framework faz certas escolhas é mais valioso do que memorizar como usá-lo. Quando você compreende a filosofia subjacente, pode prever comportamentos, depurar mais rapidamente e tomar melhores decisões arquiteturais.

O que é Roteamento Baseado em Sistema de Arquivos?

Antes de escrevermos qualquer código, vamos entender por que o SvelteKit escolheu o roteamento baseado em sistema de arquivos. Isso não é apenas um detalhe técnico — é uma filosofia que moldará como você pensa sobre toda a sua aplicação.

A Abordagem Tradicional (E Seus Problemas)

Em muitos frameworks, você define rotas em um arquivo de configuração:

// Traditional routing configuration (NOT SvelteKit)
const routes = [
	{ path: '/', component: HomePage },
	{ path: '/about', component: AboutPage },
	{ path: '/blog', component: BlogPage },
	{ path: '/blog/:slug', component: BlogPostPage },
	{ path: '/contact', component: ContactPage }
]

Essa abordagem tem um problema fundamental: a separação de responsabilidades se torna separação do entendimento. As definições de rotas ficam em um lugar, os componentes ficam em outro, e a lógica de carregamento de dados pode estar espalhada por múltiplos arquivos. Quando você precisa modificar a página /about, deve:

Encontrar a configuração de rotas para entender qual componente é renderizado
Navegar até esse arquivo de componente
Procurar qualquer lógica de carregamento de dados associada
Torcer para não ter perdido nenhum código relacionado no lado do servidor

A Filosofia do SvelteKit: Co-localização

O SvelteKit elimina essa sobrecarga cognitiva através da co-localização — o princípio de que código relacionado deve ficar junto.

No SvelteKit, a estrutura de pastas É o roteador. Se você quer uma rota em /about, simplesmente cria uma pasta chamada about. Você não precisa registrar essa pasta em lugar nenhum; sua mera existência cria a rota.

Quando você coloca um arquivo +page.svelte dentro dessa pasta (src/routes/about/+page.svelte), você simultaneamente:

Declarou uma rota que responde a /about (por causa do nome da pasta).
Criou o componente que é renderizado para essa rota (o arquivo +page.svelte).
Estabeleceu o local para qualquer lógica de carregamento de dados (+page.js fica bem ao lado).
Definiu onde o código do lado do servidor fica (+page.server.js está bem ali também).

Isso não é apenas conveniente — é transformador. Em vez de pular entre um arquivo de configuração de roteador, uma pasta de componentes e uma pasta de API, tudo relacionado à página "About" fica em um único lugar. Precisa alterar a página about? Vá para src/routes/about/. Tudo que você precisa está lá. Sem busca, sem adivinhação.

O Diretório `src/routes`: O Mapa da Sua Aplicação

Toda aplicação SvelteKit tem um diretório src/routes. Esse diretório É a sua configuração de roteamento. Veja como os diretórios mapeiam para URLs:

src/routes/                    →  /
src/routes/about/              →  /about
src/routes/blog/               →  /blog
src/routes/contact/            →  /contact
src/routes/products/           →  /products
src/routes/products/shoes/     →  /products/shoes

O padrão é belamente simples: cada diretório se torna um segmento de URL.

Rotas Dinâmicas

Mas e se você tiver centenas de posts no blog? Você não quer criar uma pasta para cada um. O SvelteKit usa colchetes para criar parâmetros de rota dinâmicos:

src/routes/blog/[slug]/+page.svelte     →  /blog/hello-world
                                        →  /blog/my-first-post
                                        →  /blog/anything-here

A pasta [slug] corresponde a qualquer valor, e esse valor fica disponível nas suas funções de carregamento e componentes.

Entendendo os Padrões de Rotas Dinâmicas

O SvelteKit suporta vários padrões de rotas dinâmicas, cada um projetado para casos de uso específicos:

Padrão	Exemplo	Corresponde a
`[slug]`	`/blog/[slug]`	`/blog/hello` (obrigatório)
`[[lang]]`	`/[[lang]]/about`	`/about` ou `/en/about` (opcional)
`[...path]`	`/files/[...path]`	`/files/a/b/c` (rest/captura geral)
`[id=integer]`	`/posts/[id=integer]`	`/posts/123` (com validação)

Parâmetros obrigatórios [slug] são os mais comuns — eles correspondem a qualquer segmento único. Uma rota como /blog/[slug] corresponderá a /blog/hello, mas não a /blog ou /blog/hello/world.

Parâmetros opcionais [[lang]] permitem que uma única rota lide com múltiplos padrões de URL. Por exemplo, [[lang]]/about corresponde tanto a /about quanto a /en/about. Isso é perfeito para internacionalização, onde você quer um idioma padrão na raiz e versões localizadas sob códigos de idioma. Exploraremos parâmetros opcionais em profundidade em um artigo dedicado mais adiante nesta série.

Parâmetros rest [...path] capturam tudo após um determinado ponto na URL. Uma rota como /files/[...path] corresponde a /files/a, /files/a/b e /files/a/b/c/d. O valor capturado se torna "a", "a/b" ou "a/b/c/d" respectivamente. Eles são essenciais para construir navegadores de arquivos, sites de documentação ou qualquer recurso onde a profundidade da URL é desconhecida. Parâmetros rest também habilitam o tratamento personalizado de 404 dentro de seções específicas da sua aplicação — cobriremos esse padrão no nosso artigo de Roteamento Avançado.

Matchers [id=integer] adicionam validação a segmentos dinâmicos. Em vez de aceitar qualquer valor, eles só correspondem quando o parâmetro passa em um teste que você define. Por exemplo, [id=integer] só corresponde a IDs numéricos como /posts/123, não a /posts/hello. Matchers são definidos no seu diretório src/params e ajudam a criar rotas com segurança de tipos. Exploraremos como criar matchers personalizados quando cobrirmos os padrões de Roteamento Avançado.

Cada um desses padrões serve a um propósito específico na construção de lógica de roteamento robusta. À medida que você avança nesta série, verá exemplos práticos de quando e por que usar cada um.

Prioridade de Correspondência de Rotas

Quando múltiplas rotas podem potencialmente corresponder a uma URL, o SvelteKit precisa decidir qual usar. Entender esse sistema de prioridade previne bugs confusos e ajuda você a estruturar rotas de forma eficaz.

A regra de ouro: rotas mais específicas ganham. O SvelteKit ordena as rotas da mais específica para a menos específica, depois as tenta em ordem até que uma corresponda. Aqui está o que "específica" significa:

Rotas estáticas vencem rotas dinâmicas. /blog/about vence /blog/[slug]
Rotas com matchers vencem rotas sem. /posts/[id=integer] vence /posts/[slug]
Parâmetros obrigatórios vencem parâmetros opcionais e rest. /[slug] vence /[[optional]] ou /[...rest]

Considere estas rotas:

src/routes/blog/latest/+page.svelte          ← Highest priority (static)
src/routes/blog/[slug=integer]/+page.svelte  ← Second (has matcher)
src/routes/blog/[slug]/+page.svelte          ← Third (dynamic, no matcher)
src/routes/blog/[[id]]/+page.svelte          ← Fourth (optional)
src/routes/[...catchall]/+page.svelte        ← Lowest priority (rest)

Quando um usuário visita /blog/latest, o SvelteKit tenta as rotas em ordem e para na primeira correspondência — a rota estática. Quando ele visita /blog/123, pula a rota estática (não corresponde a "latest"), depois corresponde à rota validada por inteiro. Para /blog/hello-world, desce até a rota [slug] simples.

Essa ordenação acontece automaticamente. Você não a configura, mas precisa entendê-la ao projetar a estrutura de rotas. Se você está obtendo correspondências inesperadas, verifique se uma rota mais geral está interceptando as requisições antes que elas alcancem a rota pretendida. Exploraremos casos extremos de correspondência de rotas e estratégias de depuração no nosso artigo de Roteamento Avançado.

O Prefixo Especial `+`

Dentro de qualquer diretório de rota, o SvelteKit reconhece arquivos especiais pelo prefixo +. O + não foi escolhido aleatoriamente — é um caractere que se ordena no topo das listagens de diretórios na maioria dos exploradores de arquivos, mantendo os arquivos de rota visualmente agrupados e separados dos arquivos que não são de rota. Mais importante, ele cria uma convenção inequívoca: qualquer coisa que começa com + pertence ao roteador do SvelteKit, qualquer coisa sem ele é sua para organizar livremente.

Esse design resolve um problema real: em um roteador baseado em sistema de arquivos, você pode querer co-localizar utilitários, componentes ou arquivos de teste ao lado das suas rotas. Sem uma convenção clara, o roteador teria que ou proibir isso (forçando você a separá-los) ou usar heurísticas para adivinhar quais arquivos são rotas. O prefixo + torna a distinção explícita e consistente.

Aqui está um resumo dos arquivos que você encontrará. Cada um tem um artigo dedicado nesta série:

Arquivo	Finalidade	Ambiente de Execução	Artigo
`+page.svelte`	Renderiza a UI da página	Servidor (SSR) + Cliente	+page.svelte
`+page.js`	Carregamento universal de dados	Servidor + Cliente	+page.js
`+page.server.js`	Carregamento de dados somente no servidor	Somente servidor	+page.server.js
`+layout.svelte`	Wrapper de layout compartilhado	Servidor (SSR) + Cliente	+layout.svelte
`+layout.js`	Carregamento universal de dados do layout	Servidor + Cliente	+layout.js
`+layout.server.js`	Carregamento de dados do layout somente no servidor	Somente servidor	+layout.server.js
`+error.svelte`	UI de boundary de erro	Servidor (SSR) + Cliente	+error.svelte
`+server.js`	Handlers de endpoint de API	Somente servidor	+server.js

Você notará dois arquivos de carregamento de dados para cada nível (+page.js e +page.server.js, +layout.js e +layout.server.js). Esta é uma das decisões arquiteturais mais importantes do SvelteKit. As variantes .server são executadas exclusivamente no servidor e têm acesso a bancos de dados, chaves de API privadas e cookies — nenhum de seus códigos chega ao navegador. As variantes não-.server são executadas em ambos o servidor e o navegador, o que habilita a navegação instantânea no lado do cliente (sem viagem de ida e volta ao servidor nas mudanças de página), mas significa que só podem usar código que funciona em ambos os ambientes. A escolha entre elas se resume a: esses dados requerem capacidades exclusivas do servidor? Se sim, use .server. Se os dados são públicos e seguros para calcular no navegador, use a versão universal.

Arquivos sem o prefixo + são ignorados pelo roteador do SvelteKit — você pode co-localizar com segurança funções auxiliares, componentes ou utilitários bem ao lado das suas rotas.

Por exemplo, esta estrutura é perfeitamente válida:

src/routes/blog/
├── +page.svelte         # Route file (SvelteKit recognizes this)
├── +page.js             # Route file (SvelteKit recognizes this)
├── BlogCard.svelte      # Component (ignored by router)
├── utils.js             # Helper functions (ignored by router)
└── formatDate.js        # Utility (ignored by router)

O SvelteKit só se preocupa com os arquivos prefixados com +. Todo o resto é seu para organizar da forma que fizer sentido para o seu projeto. Essa co-localização de código relacionado é um dos recursos mais poderosos do SvelteKit — seus componentes, utilitários e lógica de rota podem viver juntos, tornando a refatoração e a manutenção muito mais fáceis.

Um Diretório de Rota Típico

Para ver como esses arquivos funcionam juntos, vamos olhar para uma estrutura de rota típica:

src/routes/blog/
├── +page.svelte         # The UI users see
├── +page.ts             # Loads data for the page
├── +layout.svelte       # Wraps this and child pages
├── helpers.ts           # Ignored by router (no + prefix)
└── [slug]/
    ├── +page.svelte     # Individual blog post UI
    └── +page.server.ts  # Server-only data loading

Quando um usuário visita /blog:

O SvelteKit encontra src/routes/blog/
Verifica se +page.js existe para carregar dados para a página
Renderiza +page.svelte dentro de +layout.svelte

Este é um exemplo simplificado, mas o padrão é previsível e consistente. Tudo está co-localizado.

Entendendo o Layout Raiz

O layout raiz em src/routes/+layout.svelte merece atenção especial porque envolve toda a sua aplicação. Cada página, cada layout aninhado, cada rota é renderizada dentro deste layout raiz.

Se você não criar um layout raiz, o SvelteKit fornece um padrão mínimo:

<script>
	let { children } = $props()
</script>

{@render children()}

Esse padrão apenas renderiza suas páginas sem nenhum wrapper. Mas na maioria das aplicações reais, você vai querer adicionar seu próprio layout raiz para incluir elementos de todo o site, como navegação, rodapés, análises ou estilos globais.

O layout raiz também é especial em termos de tratamento de erros. Se ocorrer um erro na própria função de carregamento do layout raiz — não em uma página, mas no próprio layout — o SvelteKit não pode renderizar o layout raiz para exibir o erro, porque o layout raiz é o que renderiza as páginas de erro. Nesse caso, o SvelteKit recorre a um arquivo estático src/error.html. Esta é a única situação em que o SvelteKit ignora toda a hierarquia de componentes e renderiza um arquivo HTML puro. Entender esse caso extremo importa para produção: mantenha a função de carregamento do seu layout raiz mínima e robusta, porque uma falha ali produz a experiência de usuário mais perturbadora possível.

Exploraremos hierarquias de layout e limites de tratamento de erros em detalhes na seção de Layouts desta série.

Como as Rotas São Resolvidas: O Quadro Completo

Entender como o SvelteKit resolve uma URL em uma página renderizada ajuda você a prever comportamentos e depurar problemas. Vamos percorrer o que acontece quando um usuário visita /blog/hello-world:

Passo 1: Correspondência de Rota

O SvelteKit examina o seu diretório src/routes e encontra a melhor correspondência:

src/routes/blog/[slug]/+page.svelte  ← Matches!

O parâmetro [slug] captura "hello-world" e o disponibiliza como params.slug.

Passo 2: Carregamento de Dados (De Cima para Baixo)

Antes de renderizar qualquer coisa, o SvelteKit executa todas as funções de carregamento na hierarquia de layout, começando pela raiz:

1. src/routes/+layout.server.js           (if it exists)
2. src/routes/blog/+layout.server.js      (if it exists)
3. src/routes/blog/[slug]/+page.server.js (if it exists)

Cada função de carregamento recebe dados das funções de carregamento pai via parent(). Isso permite que rotas filhas se baseiem em dados carregados em níveis superiores. Funções de carregamento do servidor são executadas apenas no servidor e têm acesso a bancos de dados, variáveis de ambiente e outros recursos exclusivos do servidor.

Passo 3: Renderização da Hierarquia (De Fora para Dentro)

Após todos os dados serem carregados, o SvelteKit renderiza a hierarquia de layout do layout mais externo até a página mais interna:

src/routes/+layout.svelte
  └── wraps src/routes/blog/+layout.svelte
      └── wraps src/routes/blog/[slug]/+page.svelte

Cada layout recebe data da sua função de carregamento correspondente e children contendo o próximo nível abaixo. O componente mais interno é o seu +page.svelte, que renderiza o conteúdo real da página.

Passo 4: Hidratação (Servidor para Cliente)

No carregamento inicial da página, toda essa hierarquia é renderizada no servidor (SSR) e enviada como HTML. Quando o JavaScript carrega, o Svelte "hidrata" a página — anexando ouvintes de eventos e tornando-a interativa. Nas navegações subsequentes, o SvelteKit executa apenas as funções de carregamento do lado do cliente e substitui a página sem um recarregamento completo.

Esse processo de resolução acontece para cada rota na sua aplicação. Entendê-lo ajuda você a raciocinar sobre fluxo de dados, decidir onde colocar funções de carregamento e estruturar seus layouts de forma eficaz. Mergulharemos mais fundo em estratégias de carregamento de dados, composição de layouts e navegação do lado do cliente em artigos futuros.

O Modelo Mental

Pense no seu diretório src/routes como uma árvore:

src/routes/
├── +layout.svelte       (root - wraps everything)
├── +page.svelte         (home page)
├── about/
│   └── +page.svelte
└── blog/
    ├── +layout.svelte   (wraps blog pages)
    ├── +page.svelte     (blog index)
    └── [slug]/
        └── +page.svelte (individual posts)

Conclusão

O sistema de roteamento do SvelteKit representa uma mudança fundamental em como pensamos sobre a construção de aplicações web. Ao tornar o sistema de arquivos a fonte da verdade para a estrutura de URLs da sua aplicação, ele elimina a desconexão entre rotas e código que assola as configurações tradicionais de roteadores. Cada pasta se torna um segmento de URL, cada +page.svelte se torna uma rota, e as relações entre layouts, páginas e arquivos de dados emergem naturalmente da própria estrutura de diretórios.

Essa abordagem baseada em sistema de arquivos não é apenas uma questão de conveniência — é sobre criar aplicações que são mais fáceis de entender, mais fáceis de manter e mais fáceis de escalar. Quando as rotas são definidas pela localização do arquivo em vez de configuração, novos desenvolvedores podem navegar pela sua base de código intuitivamente, a refatoração se torna uma questão de mover arquivos, e a relação entre estrutura de URL e organização do código permanece clara mesmo à medida que as aplicações crescem. Ao dominar esses conceitos fundamentais, você constrói o modelo mental necessário para aproveitar todo o poder do SvelteKit.

Principais Conclusões

O roteamento baseado em sistema de arquivos usa a estrutura de pastas para definir segmentos de URL - src/routes/blog/[slug] cria o padrão de rota /blog/:slug automaticamente
+page.svelte define rotas renderizáveis - pastas sem esse arquivo servem como segmentos de URL, mas não renderizam páginas por si mesmas
+layout.svelte envolve as rotas descendentes criando uma interface compartilhada que persiste entre navegações, com layouts aninhados formando uma hierarquia de componentes
Os arquivos de dados fornecem dados para o servidor/cliente - +page.js (universal), +page.server.js (somente servidor) e os arquivos de layout correspondentes carregam dados para seus componentes
Segmentos dinâmicos usam colchetes - [param] captura segmentos de URL como parâmetros, [...rest] corresponde aos caminhos restantes e [[optional]] torna os segmentos opcionais
O layout raiz envolve tudo - src/routes/+layout.svelte fornece o shell HTML e a interface global para toda a sua aplicação
A filosofia de convenção sobre configuração elimina os arquivos de configuração de rotas e torna explícita a relação entre URLs e código por meio da estrutura de arquivos
Os arquivos de rota co-localizados permitem modularidade - páginas, layouts, carregamento de dados e endpoints de API ficam juntos, tornando as funcionalidades independentes e fáceis de refatorar

Veja Também

Documentação Oficial do SvelteKit - Roteamento - O guia oficial para o sistema de roteamento do SvelteKit e as convenções de arquivos
Estrutura de Projeto do SvelteKit - Entendendo o diretório src/routes
Parâmetros Dinâmicos - Correspondência de parâmetros e padrões avançados
Comparação de Roteamento por Sistema de Arquivos - Como outros frameworks abordam o roteamento por sistema de arquivos