Padrões Avançados e Controle de Navegação

Bem-vindo à Parte 12 da nossa série abrangente sobre roteamento no SvelteKit. Neste ponto, você já construiu fundamentos sólidos e explorou os padrões principais. Agora estamos entrando em território que realmente separa aplicações de nível produtivo de projetos básicos.

Este artigo não é apenas sobre mostrar mais funcionalidades — é sobre entender quando e por que utilizá-las. Cada padrão que abordaremos resolve desafios arquiteturais específicos que você encontrará conforme suas aplicações crescem em complexidade.

O Que Você Vai Dominar

Ao final deste artigo, você entenderá:

Correspondentes de Parâmetros: Como validar rotas na camada de roteamento (e por que isso é fundamentalmente diferente de validar em funções de carregamento)
Grupos de Rotas: O raciocínio arquitetural por trás de organizar layouts sem poluir as URLs
Quebra de Layout: Quando sair da hierarquia de layout é a escolha certa em vez de um sinal de problema no código
Roteamento Superficial: O modelo mental por trás do estado de URL que não aciona navegações completas
Ciclo de Vida de Navegação: Como interceptar, modificar e responder a cada fase da navegação

Mais importante, você entenderá o processo de tomada de decisão para escolher entre esses padrões.

Roteamento avançado não é sobre usar todos os recursos — é sobre escolher a ferramenta certa para cada problema. Uma aplicação bem arquitetada usa esses padrões com moderação, mas de forma estratégica.

Correspondentes de Parâmetros: Validação no Nível da Rota

O Problema: Defesa em Profundidade

Vamos começar com um cenário que confunde muitos desenvolvedores. Você tem uma rota de perfil de usuário:

src/routes/users/[id]/+page.svelte

Sua função de carregamento busca o usuário pelo ID e retorna seus dados. Simples o suficiente. Mas o que acontece quando alguém acessa /users/hello ou /users/../admin?

A abordagem ingênua é validar na sua função de carregamento:

// The approach most developers start with
export const load: PageLoad = async ({ params }) => {
	if (!/^\d+$/.test(params.id)) {
		error(400, 'Invalid user ID')
	}
	// fetch user...
}

Isso funciona, mas está resolvendo o problema na camada errada.

Pense bem: você está aceitando a correspondência da rota, iniciando a função de carregamento, potencialmente até atingindo middleware ou hooks — tudo isso para uma URL que nunca foi válida para começar. Em uma aplicação de alto tráfego, isso adiciona carga desnecessária. Mais importante, cria uma incompatibilidade de categoria: "formato de URL inválido" não é um erro 400 Bad Request, é "esta página não existe."

Correspondentes de parâmetros resolvem isso na própria camada de roteamento. URLs inválidas simplesmente não correspondem à rota — elas passam para outras rotas ou resultam em 404.

A validação pertence à camada mais cedo possível. Restrições de banco de dados capturam o que a lógica de negócio não captura. A lógica de negócio captura o que a validação da API não captura. A validação da API captura o que a validação de roteamento não captura. Cada camada é uma rede de segurança para a camada acima dela.

Criando Seu Primeiro Correspondente

Os correspondentes ficam em src/params/ e exportam uma função match. A função recebe o segmento da URL e retorna true se for válido:

// src/params/integer.ts
import type { ParamMatcher } from '@sveltejs/kit'

export const match: ParamMatcher = (param) => {
	return /^\d+$/.test(param)
}

Aplique o correspondente usando a sintaxe = no nome da pasta da sua rota:

src/routes/users/[id=integer]/+page.svelte

Agora o comportamento muda fundamentalmente:

/users/123 → Corresponde, params.id = '123'
/users/456789 → Corresponde, params.id = '456789'
/users/hello → NÃO corresponde, o SvelteKit tenta outras rotas
/users/12.5 → NÃO corresponde (não é um inteiro)

Observe a mudança de modelo mental: não estamos lançando erros para entradas inválidas. Estamos dizendo "esta rota simplesmente não existe para valores não inteiros."

A Cascata de Roteamento: Por Que Isso Importa

Quando uma URL não corresponde a um correspondente, o SvelteKit não retorna imediatamente um 404. Ele continua verificando outras rotas. Isso permite poderosos padrões de desambiguação:

src/routes/
├── users/
│   ├── [id=integer]/+page.svelte   ← /users/123
│   └── [username]/+page.svelte     ← /users/johndoe

Ambas as rotas têm parâmetros dinâmicos, mas servem a propósitos completamente diferentes. O correspondente cria prioridade automática:

Tenta [id=integer] primeiro (correspondentes têm maior especificidade)
Se não corresponder, passa para [username]

Isso é revolucionário para o design de APIs. Você pode ter /users/123 para IDs de usuário e /users/johndoe para nomes de usuário sem nenhuma lógica condicional no seu código. O roteador lida com a desambiguação automaticamente.

Esse padrão reflete como você projetaria uma API REST. A camada de roteamento torna-se sua primeira linha de validação de entrada, e suas funções de carregamento podem confiar que estão recebendo parâmetros bem formados. Este é o Princípio da Responsabilidade Única aplicado ao roteamento.

Construindo uma Biblioteca Prática de Correspondentes

Em aplicações de produção, você vai querer uma coleção de correspondentes reutilizáveis. Aqui estão padrões testados em batalha:

Correspondente de Inteiro

// src/params/integer.ts
import type { ParamMatcher } from '@sveltejs/kit'

export const match: ParamMatcher = (param) => {
	return /^\d+$/.test(param)
}

Correspondente de UUID

// src/params/uuid.ts
import type { ParamMatcher } from '@sveltejs/kit'

// Matches UUID v1-5 format
const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i

export const match: ParamMatcher = (param) => {
	return UUID_REGEX.test(param)
}

Por que isso importa: UUIDs são notoriamente fáceis de digitar errado. Sem validação, um usuário que marque como favorito /products/550e8400-e29b-41d4-a716-44665544000 (faltando o último dígito) veria um erro de banco de dados em vez de um 404 limpo.

Correspondente de Slug

// src/params/slug.ts
import type { ParamMatcher } from '@sveltejs/kit'

export const match: ParamMatcher = (param) => {
	// Lowercase letters, numbers, hyphens
	// Must start with letter, 3-100 chars
	return /^[a-z][a-z0-9-]{2,99}$/.test(param)
}

Decisão de design: Exigimos que comece com uma letra para evitar slugs como 123-product, que poderiam ser confundidos com rotas baseadas em ID.

Correspondente de Data

// src/params/date.ts
import type { ParamMatcher } from '@sveltejs/kit'

export const match: ParamMatcher = (param) => {
	// YYYY-MM-DD format
	if (!/^\d{4}-\d{2}-\d{2}$/.test(param)) {
		return false
	}

	// Verify it's actually a valid date (not 2025-02-30)
	const date = new Date(param + 'T00:00:00Z')
	return !isNaN(date.getTime()) && param === date.toISOString().split('T')[0]
}

Por que a validação extra? O regex sozinho aceitaria 2025-02-30 (30 de fevereiro não existe). O construtor Date valida a lógica real do calendário.

Observe que usamos horário UTC (T00:00:00Z). Sem isso, o comportamento de análise de datas varia conforme o fuso horário do servidor, levando a bugs do tipo "funciona no desenvolvimento, quebra em produção."

Correspondentes com Segurança de Tipos

É aqui que os correspondentes se tornam verdadeiramente poderosos. Você pode criar correspondentes que não apenas validam strings, mas também restringem tipos TypeScript:

// src/params/category.ts
import type { ParamMatcher } from '@sveltejs/kit'

const categories = ['electronics', 'clothing', 'books', 'home', 'sports'] as const
export type Category = (typeof categories)[number]

export const match = ((param: string): param is Category => {
	return categories.includes(param as Category)
}) satisfies ParamMatcher

A mágica acontece na sua função de carregamento:

// src/routes/shop/[category=category]/+page.ts
import type { PageLoad } from './$types'
import type { Category } from '$params/category'

export const load: PageLoad = async ({ params }) => {
	// TypeScript knows params.category is 'electronics' | 'clothing' | 'books' | 'home' | 'sports'
	// NOT just string!
	const category: Category = params.category
}

Predicados de tipo (param is Category) são um recurso subutilizado do TypeScript. Combinados com satisfies, você obtém tanto validação em tempo de execução quanto restrição de tipos em tempo de compilação. Esta é a defesa em profundidade no nível de tipos.

A Restrição Crítica: Correspondentes São Universais

Esta é a limitação crítica que pega muitos desenvolvedores de surpresa:

Correspondentes são executados TANTO no servidor quanto no navegador. O código do seu correspondente é enviado ao cliente para navegação do lado do cliente. Isso significa:

Permitido em Correspondentes	Não Permitido em Correspondentes
Validação pura de string	Consultas ao banco de dados
Operações com RegEx	Acesso ao sistema de arquivos
Lógica síncrona simples	Importações de `$lib/server/*`
	Variáveis de ambiente (exceto as públicas)

// AVOID: This will break client-side navigation
import { db } from '$lib/server/database'

export const match: ParamMatcher = async (param) => {
	const user = await db.users.findUnique({ where: { id: param } })
	return !!user
}

// PREFERRED: Validate format, check existence in load function
export const match: ParamMatcher = (param) => {
	return /^[a-f0-9]{24}$/.test(param) // MongoDB ObjectId format
}

A regra prática: Correspondentes validam o formato, funções de carregamento validam a existência.

Se você se encontrar querendo acesso ao banco de dados em um correspondente, está tentando resolver o problema errado. A questão não é "este usuário existe?" mas sim "este é um formato de ID de usuário válido?" Verificações de existência pertencem às funções de carregamento, onde você tem plenas capacidades do servidor.

Grupos de Rotas: Organização Arquitetural Sem Poluição de URLs

Grupos de rotas resolvem uma das dores de crescimento mais comuns em aplicações SvelteKit: como você organiza seus layouts e código sem forçar essa organização nas suas URLs?

O Problema: Layouts Querem Ser Donos das URLs

Imagine que você está construindo um produto SaaS. Você tem três seções distintas:

Páginas de marketing (/, /about, /pricing) — Públicas, layout de marketing com grandes seções hero
Páginas do app (/dashboard, /settings, /profile) — Autenticadas, layout do app com sidebar
Páginas de autenticação (/login, /register, /forgot-password) — Públicas, layout minimalista centralizado

O instinto natural no SvelteKit é criar hierarquias de layout:

src/routes/
├── +layout.svelte           ← Root layout
├── marketing/
│   ├── +layout.svelte       ← Marketing layout
│   ├── +page.svelte         ← /marketing (wait, we wanted /)
│   └── about/+page.svelte   ← /marketing/about (not /about!)
├── app/
│   ├── +layout.svelte
│   └── dashboard/+page.svelte  ← /app/dashboard (not /dashboard!)

As URLs estão poluídas com sua estrutura organizacional. Os usuários veem /app/dashboard quando deveriam ver /dashboard.

Grupos de Rotas: Organização Sem URLs

Grupos de rotas usam parênteses para criar fronteiras de layout que são invisíveis nas URLs:

src/routes/
├── (marketing)/
│   ├── +layout.svelte       ← Marketing layout
│   ├── +page.svelte         ← / (the homepage!)
│   ├── about/
│   │   └── +page.svelte     ← /about
│   └── pricing/
│       └── +page.svelte     ← /pricing
├── (app)/
│   ├── +layout.svelte       ← App layout with sidebar
│   ├── +layout.server.ts    ← Auth protection for all app routes
│   ├── dashboard/
│   │   └── +page.svelte     ← /dashboard
│   └── settings/
│       └── +page.svelte     ← /settings
└── (auth)/
    ├── +layout.svelte       ← Minimal centered layout
    ├── login/
    │   └── +page.svelte     ← /login
    └── register/
        └── +page.svelte     ← /register

Os parênteses dizem ao SvelteKit: "isso é organizacional, não um segmento de URL." Os usuários veem /dashboard, não /(app)/dashboard.

Grupos de rotas são sobre separação de responsabilidades. Cada grupo pode ter seu próprio layout, sua própria função de carregamento de layout, seus próprios limites de erro. Você não está apenas organizando arquivos — está criando mini-aplicações independentes dentro da sua aplicação.

O Padrão de Autenticação: Uma Verificação, Muitas Rotas

Um dos usos mais poderosos dos grupos de rotas é a autenticação centralizada. Em vez de verificar a autenticação em cada função de carregamento, você faz isso uma vez no nível do grupo:

// src/routes/(app)/+layout.server.ts
import { redirect } from '@sveltejs/kit'
import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ locals, url }) => {
	// This runs for ALL routes in the (app) group
	// /dashboard, /settings, /profile, /billing - all protected automatically
	if (!locals.user) {
		// Preserve where they were trying to go for post-login redirect
		const redirectTo = encodeURIComponent(url.pathname + url.search)
		redirect(303, `/login?redirectTo=${redirectTo}`)
	}

	// User is authenticated - make their data available to all child routes
	return {
		user: {
			id: locals.user.id,
			name: locals.user.name,
			email: locals.user.email,
			avatar: locals.user.avatar
		}
	}
}

Por que isso é melhor do que verificações por rota:

DRY: Uma verificação de autenticação cobre rotas ilimitadas
Impossível de esquecer: Novas rotas em (app) são automaticamente protegidas
Fonte única da verdade: A lógica de autenticação muda em um único lugar
Disponibilidade de dados: Os dados do usuário fluem automaticamente para todas as rotas filhas

<!-- src/routes/(app)/+layout.svelte -->
<script lang="ts">
	import type { LayoutProps } from './$types'
	import Sidebar from '$lib/components/Sidebar.svelte'
	import Header from '$lib/components/Header.svelte'

	let { data, children }: LayoutProps = $props()
</script>

<div class="app-layout">
	<Sidebar user={data.user} />

	<div class="main-area">
		<Header user={data.user} />

		<main>
			{@render children()}
		</main>
	</div>
</div>

<style>
	.app-layout {
		display: grid;
		grid-template-columns: 250px 1fr;
		min-height: 100vh;
	}

	.main-area {
		display: flex;
		flex-direction: column;
	}

	main {
		flex: 1;
		padding: 2rem;
	}
</style>

Todas as páginas em (app) agora têm acesso a data.user porque os dados do layout fluem para os filhos.

Esse padrão escala muito bem. Precisa de acesso baseado em funções? Crie grupos (admin) e (user). Precisa de níveis de assinatura? Crie grupos (free), (pro), (enterprise). O sistema de arquivos se torna sua arquitetura de autorização.

Posicionamento da Página Inicial: A Questão da Página Raiz

Você pode colocar +page.svelte diretamente em um grupo de rotas para criar a página raiz:

src/routes/
├── (marketing)/
│   ├── +layout.svelte
│   └── +page.svelte         ← This IS the homepage (/)
└── (app)/
    └── dashboard/
        └── +page.svelte     ← /dashboard

Isso mantém sua página inicial junto com seus irmãos de marketing, usando o layout de marketing.

A Armadilha de Conflito: Um Grupo por URL

Aqui está um erro que vai lhe dar erros de build crípticos:

src/routes/
├── (marketing)/
│   └── +page.svelte         ← /
└── (app)/
    └── +page.svelte         ← Also / - CONFLICT!

Apenas um grupo pode reivindicar um determinado caminho de URL. Grupos de rotas afetam layouts, não a resolução de URLs. Dois grupos não podem ter uma página na mesma URL.

Pense nos grupos de rotas como "contêineres de layout", não "namespaces de URL". O espaço de URLs é plano — os grupos apenas permitem que você aplique layouts diferentes a partes diferentes desse espaço plano.

Escapando de Layouts: A Válvula de Escape

Layouts se aninham. Esse é o seu poder e, ocasionalmente, o seu problema. Às vezes uma página profundamente aninhada precisa escapar completamente de sua hierarquia de layout.

Entendendo Por Que Você Quereria Isso

Considere um dashboard empresarial com esta estrutura:

src/routes/
├── +layout.svelte                  ← Root: nav, footer
├── (app)/
│   ├── +layout.svelte              ← App chrome: sidebar
│   └── dashboard/
│       ├── +layout.svelte          ← Dashboard nav: tabs, breadcrumbs
│       └── reports/
│           ├── +layout.svelte      ← Reports: toolbar, filters
│           └── [id]/
│               └── +page.svelte    ← Uses ALL 4 layouts!

Para /dashboard/reports/123, o usuário vê:

Root layout → App layout → Dashboard layout → Reports layout → Page content

Isso são potencialmente quatro camadas de navegação, sidebars e elementos de interface. Mas e se você precisar:

Incorporar um relatório em um iframe no site de um cliente (sem elementos de interface)
Imprimir um relatório (apenas o conteúdo, sem navegação)
Exibir uma visualização em tela cheia (autenticação do app, mas sem UI distrativa)

Você precisa escapar da cadeia de layout.

A Sintaxe `@`: Escolhendo Sua Ancestralidade de Layout

O símbolo @ nos nomes de arquivos especifica onde "reiniciar" a cadeia de layout:

+page@.svelte           ← Reset to root layout only
+page@(app).svelte      ← Reset to (app) layout (keep auth, skip dashboard/reports chrome)
+page@dashboard.svelte  ← Reset to dashboard layout (skip just reports chrome)

Exemplo do Mundo Real: Relatórios Incorporáveis

src/routes/
├── +layout.svelte
├── (app)/
│   ├── +layout.svelte
│   └── dashboard/
│       ├── +layout.svelte
│       └── reports/
│           ├── +page.svelte              ← Full app chrome - internal use
│           └── [id]/
│               ├── +page.svelte          ← Full app chrome - viewing a report
│               └── embed/
│                   └── +page@.svelte     ← ROOT ONLY - embeddable!

A página de incorporação escapa para o layout raiz apenas:

<!-- src/routes/(app)/dashboard/reports/[id]/embed/+page@.svelte -->
<script lang="ts">
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()
</script>

<!-- No navigation, no sidebar, no header, no footer -->
<!-- Clean slate for iframe embedding -->
<div class="embedded-report">
	<h1>{data.report.title}</h1>
	<ReportChart data={data.report.chartData} />
</div>

<style>
	.embedded-report {
		padding: 1rem;
		font-family: system-ui;
		/* iframe-friendly styles */
	}
</style>

Agora /dashboard/reports/123/embed exibe apenas o conteúdo do relatório — perfeito para <iframe src="/dashboard/reports/123/embed">.

O padrão de incorporação é incrivelmente útil para integrações. Clientes podem incorporar seus relatórios em seus dashboards, páginas do Notion ou ferramentas internas. Uma página serve a dois contextos de UX completamente diferentes.

Quando NÃO Usar Quebra de Layout

Quebra de layout é uma ferramenta poderosa. Como todas as ferramentas poderosas, pode causar danos quando usada incorretamente.

Sinais de que você pode estar usando @ em excesso:

Múltiplas páginas na mesma pasta usando diferentes resets com @
Modelo mental complexo de "qual página usa quais layouts"
Membros da equipe confusos sobre herança de layout

Considere alternativas primeiro:

<!-- Alternative: Conditional layout content -->
<!-- src/routes/(app)/dashboard/+layout.svelte -->
<script lang="ts">
	import { page } from '$app/state'

	let { data, children } = $props()

	// Hide sidebar for specific routes
	const isMinimalMode = $derived(
		page.url.pathname.includes('/embed') ||
			page.url.pathname.includes('/fullscreen') ||
			page.url.pathname.includes('/print')
	)
</script>

{#if isMinimalMode}
	<main class="minimal">
		{@render children()}
	</main>
{:else}
	<Sidebar user={data.user} />
	<main class="with-sidebar">
		{@render children()}
	</main>
{/if}

Quando usar @ vs layouts condicionais:

Use `@` quando...	Use layouts condicionais quando...
A página é verdadeiramente independente	Você está apenas ocultando alguns elementos de UI
Você precisa de tratamento diferente de `<head>`	A página ainda pertence ao mesmo contexto
Performance importa (menos código de layout)	Você quer animar entre modos
A página pode ser renderizada sem JavaScript	Você precisa que o estado seja preservado durante a troca de modo

Quebra de layout é sobre identidade, não aparência. Uma página de incorporação não é "o dashboard sem uma sidebar" — é uma página fundamentalmente diferente que por acaso exibe conteúdo similar. Se você está apenas alternando visibilidade, use condicionais.

Roteamento Superficial: Estado de URL Sem Transições de Página

Roteamento superficial é uma das funcionalidades mais elegantes do SvelteKit, mas também uma das mais mal compreendidas. Vamos construir o modelo mental desde os primeiros princípios.

O Problema: Modais, Filtros e Estado Compartilhável

Considere uma galeria de fotos. Quando um usuário clica em uma miniatura:

Sem roteamento superficial:

Navegação completa para /photos/123
Posição de rolagem do navegador perdida
Componente da galeria desmonta e remonta
Estado de animação perdido
Parece lento e brusco

O que os usuários realmente querem:

Modal abre sobre a galeria
URL atualiza para /photos/123 (para que possam compartilhar o link!)
Botão voltar fecha o modal
Galeria permanece montada embaixo

Este é o problema do "URL de modal" — você quer estado baseado em URL sem navegação baseada em URL.

O Modelo Mental: Histórico Sem Hidratação

pushState e replaceState modificam a pilha de histórico do navegador e a barra de URL sem acionar o sistema de navegação do SvelteKit. Nenhuma função de carregamento é executada. Nenhum layout é remontado. Apenas mudanças de URL e estado.

Pense nisso como "navegação cosmética" — a URL muda para fins de compartilhamento e marcação, mas sua aplicação não navega de verdade. A percepção crítica é que sua aplicação suporta duas experiências diferentes para a mesma URL dependendo de como o usuário chegou:

Clicou de dentro do app: A galeria já está renderizada; pushState adiciona uma entrada no histórico para que o botão voltar funcione, e o modal abre sobre a página existente.
Chegou diretamente por um link compartilhado: O +page.svelte real para /photos/123 renderiza com carregamento completo de dados no lado do servidor, exibindo a foto em seu próprio contexto independente.

Mesma URL, duas experiências diferentes, ambas corretas. Isso é aprimoramento progressivo aplicado ao estado de URL.

<script lang="ts">
	import { pushState } from '$app/navigation'
	import { page } from '$app/state'

	// The gallery data - stays loaded
	let photos = $state([
		/* ... */
	])

	function openPhoto(id: string) {
		// Update URL and store state, but DON'T navigate
		pushState(`/photos/${id}`, { selectedPhotoId: id })
	}

	function closePhoto() {
		// Go back in history (closes modal, restores previous URL)
		history.back()
	}

	// Derive modal visibility from state
	const selectedPhoto = $derived(
		page.state.selectedPhotoId ? photos.find((p) => p.id === page.state.selectedPhotoId) : null
	)
</script>

<!-- Gallery stays rendered -->
<div class="gallery">
	{#each photos as photo}
		<button onclick={() => openPhoto(photo.id)}>
			<img src={photo.thumbnail} alt={photo.title} />
		</button>
	{/each}
</div>

<!-- Modal overlays when photo selected -->
{#if selectedPhoto}
	<div class="modal-backdrop" onclick={closePhoto}>
		<div class="modal" onclick={(e) => e.stopPropagation()}>
			<img src={selectedPhoto.fullSize} alt={selectedPhoto.title} />
			<h2>{selectedPhoto.title}</h2>
			<button onclick={closePhoto}>Close</button>
		</div>
	</div>
{/if}

A URL mostra /photos/123 mas nunca saímos da página da galeria. O usuário compartilha o link, o destinatário cai na rota /photos/123 real com o conteúdo completo da página.

O shallow routing é sobre intenção. A URL /photos/123 significa "estou visualizando a foto 123." Mas como cheguei lá importa para a UX. Cliquei a partir da galeria? Mostra um modal. Cheguei a partir de um link compartilhado? Mostra a página completa. Mesma URL, experiências diferentes.

Padrão Avançado: Pré-carregando Dados para Modais

O exemplo anterior assume que a galeria já possui todos os dados das fotos. Mas e se o modal precisar de dados adicionais (imagem em alta resolução, comentários, metadados)?

O preloadData do SvelteKit permite buscar dados de rota sem navegar:

<script lang="ts">
	import { preloadData, pushState, goto } from '$app/navigation'
	import { page } from '$app/state'
	import PhotoDetail from './[id]/+page.svelte'

	async function openPhoto(id: string, event: MouseEvent) {
		// Don't interfere with ctrl+click (open in new tab)
		if (event.metaKey || event.ctrlKey || event.shiftKey) return

		event.preventDefault()
		const href = `/photos/${id}`

		// Fetch the data that /photos/[id] would load
		const result = await preloadData(href)

		if (result.type === 'loaded' && result.status === 200) {
			// Success: open modal with preloaded data
			pushState(href, { photoData: result.data })
		} else if (result.type === 'redirect') {
			// The route redirected (maybe photo was deleted)
			goto(result.location)
		} else {
			// Error loading data: fall back to full navigation
			goto(href)
		}
	}
</script>

<!-- Links work normally for accessibility, JS enhances them -->
{#each photos as photo}
	<a
		href="/photos/{photo.id}"
		onclick={(e) => openPhoto(photo.id, e)}
		data-sveltekit-preload-data="hover"
	>
		<img src={photo.thumbnail} alt={photo.title} />
	</a>
{/each}

{#if page.state.photoData}
	<div class="modal-backdrop" onclick={() => history.back()}>
		<div class="modal" onclick={(e) => e.stopPropagation()}>
			<!-- Render the actual page component with preloaded data! -->
			<PhotoDetail data={page.state.photoData} />
		</div>
	</div>
{/if}

Observe que usamos tags <a>, não <button>. Isso é fundamental para acessibilidade e SEO. Leitores de tela anunciam links corretamente, mecanismos de busca podem rastreá-los, e ctrl+clique abre novas abas. O JavaScript aprimora, não substitui.

`replaceState`: Atualizar Sem Histórico

Às vezes você quer atualizar a URL sem criar uma nova entrada no histórico. Filtros são o exemplo clássico—cada tecla pressionada em uma caixa de busca não deveria criar um passo no botão de voltar.

<script lang="ts">
	import { replaceState } from '$app/navigation'
	import { page } from '$app/state'

	function updateFilters(key: string, value: string) {
		const url = new URL(page.url)

		if (value) {
			url.searchParams.set(key, value)
		} else {
			url.searchParams.delete(key)
		}

		// Update URL without creating history entry
		replaceState(url, page.state)
	}
</script>

<input
	type="search"
	value={page.url.searchParams.get('q') ?? ''}
	oninput={(e) => updateFilters('q', e.currentTarget.value)}
	placeholder="Search..."
/>

<select onchange={(e) => updateFilters('sort', e.currentTarget.value)}>
	<option value="">Sort by...</option>
	<option value="newest">Newest first</option>
	<option value="price-low">Price: Low to High</option>
	<option value="price-high">Price: High to Low</option>
</select>

Use pushState quando: A mudança de estado é um "destino" (abrir um modal, visualizar um item)

Use replaceState quando: A mudança de estado é incremental (filtrar, ordenar, entrada de formulário)

Hooks do Ciclo de Vida de Navegação: Controle Total

O SvelteKit fornece hooks para interceptar cada fase da navegação. É aqui que você implementa avisos de "alterações não salvas", animações de transição de página, analytics e indicadores de carregamento personalizados.

Os Três Hooks: Quando São Disparados

User clicks link
       ↓
┌─────────────────────────┐
│   beforeNavigate()      │ ← Can CANCEL navigation
│   "Should we leave?"    │
└────────────┬────────────┘
             ↓
┌─────────────────────────┐
│   onNavigate()          │ ← Can DELAY navigation
│   "Prepare for change"  │   (View Transitions live here)
└────────────┬────────────┘
             ↓
      [ Navigation happens ]
      [ DOM updates ]
             ↓
┌─────────────────────────┐
│   afterNavigate()       │ ← React to completed navigation
│   "Navigation finished" │   (Analytics, scroll, cleanup)
└─────────────────────────┘

`beforeNavigate`: O Guardião

Este hook é executado primeiro e pode cancelar a navegação completamente. Perfeito para proteção de "alterações não salvas":

<script lang="ts">
	import { beforeNavigate } from '$app/navigation'

	let hasUnsavedChanges = $state(false)
	let formContent = $state('')

	beforeNavigate((navigation) => {
		if (!hasUnsavedChanges) return // Let navigation proceed

		if (navigation.willUnload) {
			// User is leaving the site entirely (closing tab, external link)
			// cancel() here triggers browser's native "Leave site?" dialog
			navigation.cancel()
		} else {
			// Internal navigation - show custom confirmation
			if (!confirm('You have unsaved changes. Leave anyway?')) {
				navigation.cancel()
			}
		}
	})

	function handleInput(e: Event) {
		formContent = (e.target as HTMLTextAreaElement).value
		hasUnsavedChanges = true
	}

	function handleSave() {
		// Save logic...
		hasUnsavedChanges = false
	}
</script>

<form>
	<textarea oninput={handleInput} value={formContent}></textarea>
	<button type="button" onclick={handleSave}>Save</button>
</form>

Use cancel() com moderação. Usuários odeiam ficar presos. Bloqueie a navegação apenas quando houver realmente trabalho não salvo, e sempre forneça uma forma clara de descartar as alterações e sair.

`afterNavigate`: Analytics e Limpeza

É executado após a conclusão da navegação e a atualização do DOM. É aqui que você rastreia visualizações de página e gerencia o comportamento de rolagem:

<script lang="ts">
	import { afterNavigate } from '$app/navigation'

	afterNavigate((navigation) => {
		// Track page views with context
		analytics.track('page_view', {
			from: navigation.from?.url.pathname ?? '(entry)',
			to: navigation.to?.url.pathname,
			type: navigation.type,
			duration: performance.now() // Time since page load
		})

		// Custom scroll behavior based on navigation type
		if (navigation.type === 'link' || navigation.type === 'goto') {
			// User intentionally navigated - smooth scroll to top
			window.scrollTo({ top: 0, behavior: 'smooth' })
		}
		// 'popstate' (back/forward) - browser handles scroll restoration
	})
</script>

Não lute contra o navegador no scroll do popstate. Usuários esperam que voltar/avançar os retorne à posição de rolagem anterior. Quebrar essa expectativa é um erro comum de UX.

Conclusão

Os padrões avançados de roteamento no SvelteKit revelam a verdadeira flexibilidade do framework—a capacidade de quebrar convenções quando necessário, mantendo os benefícios do roteamento baseado em convenções. Correspondentes de parâmetros fornecem validação de parâmetros com segurança de tipos na camada de roteamento, grupos de rotas organizam aplicações complexas sem poluição de URL, a quebra de layouts habilita páginas independentes quando a hierarquia não se encaixa, o shallow routing cria URLs de modal compartilháveis, e os hooks de navegação fornecem controle do ciclo de vida para guards, preparação e analytics.

Dominar esses padrões significa saber quando usá-los e quando manter os padrões. A maioria das aplicações prospera com as convenções do SvelteKit, mas aplicações em produção inevitavelmente encontram casos em que os padrões normais precisam de complementação. Ao entender correspondentes de parâmetros para versionamento de rotas de API, grupos de rotas para seções autenticadas, shallow routing para estados de modal e hooks de navegação para integração de analytics, você constrói aplicações que lidam com complexidade de forma elegante sem lutar contra o framework. Esses não são escotilhas de escape—são ferramentas poderosas que complementam os fundamentos de roteamento.

Principais Conclusões

Correspondentes de parâmetros validam parâmetros de rota na camada de roteamento usando arquivos src/params/*.js, fornecendo validação de parâmetros com segurança de tipos antes da renderização dos componentes
Grupos de rotas organizam layouts usando parênteses como (authenticated) para criar hierarquias de layout sem afetar as URLs, perfeito para rotas protegidas
Quebra de layout com a sintaxe @ permite que páginas ignorem layouts pai: +page@.svelte renderiza diretamente sob a raiz, escapando da hierarquia normal de layouts
O shallow routing atualiza URLs sem navegação usando pushState e replaceState para caixas de diálogo modais, filtros ou abas onde a navegação completa perderia o estado do componente
beforeNavigate habilita guards de navegação para avisos de alterações não salvas, verificações de autenticação ou redirecionamentos condicionais antes da conclusão da navegação
onNavigate prepara para mudanças de página - perfeito para View Transitions, gerenciamento de rolagem ou estados de carregamento que precisam iniciar antes da renderização da nova página
afterNavigate rastreia navegações concluídas para analytics, gerenciamento de foco ou operações de limpeza que devem ocorrer após a nova página estar visível
Correspondentes de parâmetros habilitam validação personalizada - crie correspondentes como integer, slug ou uuid para garantir que as rotas correspondam apenas a formatos de parâmetros válidos

Veja Também

Documentação Oficial do SvelteKit - Roteamento Avançado
Correspondentes de Parâmetros - Validação de parâmetros personalizada
Grupos de Rotas - Padrões de organização de layout
Hooks de Navegação - beforeNavigate, onNavigate, afterNavigate
Shallow Routing - pushState e replaceState
Quebra de Layouts - Sintaxe de reset @
Roteamento Especializado - Padrões de arquitetura para produção