Por Que os Hooks Existem

Os artigos anteriores desta série descreveram o que acontece dentro de uma função load: receber um objeto de evento, fazer chamadas fetch, ler cookies e retornar dados. O que esses artigos não abordaram foi a questão do que acontece antes de uma função load ser executada. Quem valida a sessão? Quem decide se um usuário está autenticado antes mesmo de uma única função load começar? De onde vem event.locals.user quando suas funções load o leem?

A resposta é hooks.server.ts. Esse arquivo fica na raiz do seu diretório src/ e exporta funções que o SvelteKit chama em pontos específicos do ciclo de vida da requisição e resposta. Ao contrário das funções load, (que têm escopo em uma única rota), os hooks são executados para cada requisição que passa pelo servidor, independentemente de qual rota ela tem como alvo.

Este artigo cobre o sistema completo de hooks: o hook handle que envolve cada requisição, como usá-lo para popular event.locals com dados de sessão validados, a configuração correta de TypeScript para App.Locals, o hook handleFetch para reescrever chamadas fetch do lado do servidor, o hook handleError para capturar e registrar exceções, e o helper sequence para compor múltiplas funções hook de forma limpa.

O Problema com a Validação de Sessão em Funções Load

Considere uma aplicação SvelteKit onde todas as diferentes rotas precisam saber quem é o usuário atual. Com apenas funções load disponíveis, há duas opções ruins.

A primeira opção ruim é ler e validar o cookie de sessão em cada função load individualmente. Quando temos vinte rotas, isso significa vinte lugares onde a lógica de validação reside, vinte lugares onde um bug pode deixar uma rota desprotegida, e vinte leituras de cookie e chamadas de API de sessão redundantes em cada requisição.

A segunda opção ruim é ler o cookie na função load do servidor do layout raiz e confiar que await parent() em cada função load de página dará a cada página acesso à sessão. Isso parece limpo, mas tem uma falha crítica: o SvelteKit não re-executa um load de layout em cada navegação do lado do cliente. Ele só o re-executa quando as dependências de dados desse load são explicitamente invalidadas — via invalidate() ou invalidateAll().

Sem isso, o resultado em cache da renderização inicial do servidor é reutilizado, o que significa que a verificação de sessão é silenciosamente ignorada nas visitas subsequentes à página. Mais importante ainda, as actions de formulário contornam completamente os loads de layout. Uma action de formulário em uma rota não pode usar parent() para obter a sessão porque as actions de formulário não são funções load e parent() não está disponível para elas.

Solução: hooks.server.ts e event.locals

A solução é um arquivo hooks.server.ts que pode exportar qualquer um dos seguintes hooks:

handle: executado para cada requisição — o lugar certo para validar a sessão e popular event.locals
handleFetch: executado para cada chamada fetch do lado do servidor, útil para reescrever URLs e injetar cabeçalhos de autenticação
handleError: executado para exceções inesperadas, o lugar certo para reportar a serviços de monitoramento sem expor detalhes ao cliente
sequence: um utilitário importado de @sveltejs/kit/hooks para compor múltiplas funções Handle em uma única exportação handle, executando-as em ordem

event.locals é um objeto JavaScript simples que o SvelteKit cria do zero para cada requisição recebida. O hook handle escreve nele antes de chamar resolve, e todo handler do lado do servidor para essa mesma requisição — funções load, actions de formulário, handlers de API — lê a partir dele. Ele nunca é serializado para o navegador e é descartado assim que a resposta é entregue. O restante deste artigo explica seu ciclo de vida completo.

O Hook handle

O hook handle é a exportação mais importante de hooks.server.ts. Ele é executado para cada requisição sem exceção: carregamentos de página, rotas de API, actions de formulário, requisições de prefetch e qualquer outro tráfego HTTP que atinja seu servidor SvelteKit. Ele é executado uma vez por requisição, popula event.locals com a sessão validada, e todo handler subsequente para essa requisição lê de locals em vez de refazer a validação. Ele recebe o evento de requisição e uma função resolve que continua o pipeline de requisição.

O objeto event e event.locals

Todo hook e função load no SvelteKit recebe um objeto event. É o mesmo tipo de objeto ao longo do ciclo de vida do lado do servidor: hooks o recebem, funções load o recebem, actions de formulário o recebem. As propriedades mais relevantes para os hooks são:

event.request — o objeto Web Request padrão com cabeçalhos, método e corpo
event.cookies — um wrapper tipado para ler e escrever cookies na resposta
event.url — a URL analisada da requisição recebida
event.locals — um objeto JavaScript simples, somente no servidor, criado do zero para cada requisição
event.getClientAddress() — retorna o endereço IP do cliente que está se conectando

event.locals merece atenção especial. Ele começa como um objeto vazio {} no início de cada requisição e existe puramente na memória do servidor — nada dele é enviado ao navegador. O hook handle o popula antes que o handler de rota seja executado; toda função load do servidor, action de formulário e handler de API para essa mesma requisição então lê a partir dele. Depois que a resposta é enviada, o objeto é descartado.

Pense nele como um bloco de rascunho tipado e com escopo de requisição: o hook o preenche, e todo handler a partir daí o consome — sem que nenhum deles precise buscar novamente ou revalidar os mesmos dados.

O passthrough e a forma de middleware

A implementação mais simples possível apenas chama resolve diretamente:

// src/hooks.server.ts

import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	// any code you add here runs before the route is processed
	return resolve(event)
}

Isso é um passthrough; não faz nada. Mas a estrutura revela o padrão. Tudo antes de resolve(event) é executado antes que a rota seja processada; tudo depois é executado após a resposta ser gerada.

resolve(event) não é apenas a próxima função na pilha de chamadas — ele representa todo o pipeline downstream: roteamento do SvelteKit, o handler de rota correspondido, todas as funções load e actions de formulário, e em última instância a construção da resposta. Qualquer coisa escrita em event.locals antes que ele seja executado está disponível ao longo de todo esse pipeline.

Esta é a forma canônica de middleware, e é onde a validação de sessão deve ficar:

// src/hooks.server.ts

import type { Handle } from '@sveltejs/kit'

export const handle: Handle = async ({ event, resolve }) => {
	event.locals.user = null
	const sessionToken = event.cookies.get('session')

	if (sessionToken) {
		// event.fetch in hooks behaves like SvelteKit's enhanced fetch:
		// it handles relative URLs correctly and forwards cookies automatically.
		const res = await event.fetch('/api/session/validate', {
			headers: { Authorization: `Bearer ${sessionToken}` }
		})

		if (res.ok) {
			const user = await res.json()
			event.locals.user = user
		}
	}

	return resolve(event)
}

Após a execução desse hook, toda função load do servidor, toda action de formulário e todo handler +server.ts em toda a aplicação pode ler event.locals.user para obter o usuário validado sem fazer outra chamada de API. A validação acontece uma vez por requisição HTTP, na frente do pipeline.

event.fetch está disponível no hook handle e se comporta da mesma forma que o fetch fornecido às funções load: ele resolve URLs relativas em relação à origem da requisição atual e encaminha cookies automaticamente. Sempre use event.fetch para chamadas de API dentro do hook em vez do fetch global.

Uma abordagem alternativa e frequentemente preferível é chamar sua lógica de validação de sessão diretamente em vez de via HTTP, importando sua biblioteca de autenticação ou funções de consulta ao banco de dados inline.

// src/hooks.server.ts — calling auth logic directly (preferred in most apps)

import type { Handle } from '@sveltejs/kit'
import { validateSessionToken } from '$lib/server/auth'

export const handle: Handle = async ({ event, resolve }) => {
	event.locals.user = null
	const sessionToken = event.cookies.get('session')

	if (sessionToken) {
		event.locals.user = await validateSessionToken(sessionToken)
	}

	return resolve(event)
}

Importações diretas de $lib/server/ estão disponíveis nos hooks, e são a escolha certa quando sua lógica de autenticação já está encapsulada em um módulo do servidor. A abordagem HTTP é útil quando você está chamando um provedor de autenticação externo em vez do seu próprio armazenamento de sessão.

Tipando locals com App.Locals

O hook popula event.locals e todo handler do lado do servidor a partir daí lê dele — mas esses dois lados do contrato existem em arquivos completamente separados. O hook escreve locals.user; uma função load em uma rota completamente diferente lê locals.user. Sem uma declaração de tipo conectando-os, o TypeScript não tem como verificar que ambos os lados concordam sobre o que locals.user realmente é. A função load está efetivamente lendo de um objeto sem tipo, e qualquer erro de digitação ou incompatibilidade de forma se torna um erro em tempo de execução em vez de um erro em tempo de compilação.

O SvelteKit resolve isso com uma única declaração ambient em src/app.d.ts. Declare a forma de App.Locals uma vez, e o TypeScript a aplica em todos os lugares: no hook quando você escreve em event.locals, em toda função load, action de formulário e handler de API quando você lê dele. A declaração é o contrato, o hook e os handlers são as duas partes vinculadas por ele.

O arquivo de declaração `src/app.d.ts`

Como já mencionado, sem nenhuma declaração de tipo, event.locals é tipado como um objeto vazio {}. Ler event.locals.user imediatamente gera um erro de TypeScript: Property 'user' does not exist on type 'Locals'. Você teria que fazer cast com as any em todos os lugares, perdendo toda a segurança de tipos.

O SvelteKit resolve isso com um recurso do TypeScript chamado augmentação de módulo. O arquivo src/app.d.ts (gerado quando você cria um projeto SvelteKit) é um arquivo de declaração ambient especial que permite estender interfaces do pacote @sveltejs/kit sem modificá-lo. O bloco declare global { namespace App { ... } } acessa o namespace global App que o SvelteKit define e mescla suas propriedades nele. O TypeScript detecta isso automaticamente em toda a base de código, sem necessidade de importações em nenhum lugar.

O export {} no final é obrigatório para tornar o arquivo um módulo em vez de um script, que é o que permite que a augmentação global funcione.

// src/app.d.ts

declare global {
	namespace App {
		interface Locals {
			user: {
				id: string
				email: string
				role: 'user' | 'admin' | 'superadmin'
			} | null
		}
	}
}

export {}

Como muitas páginas podem ser acessadas sem uma sessão, definir user como null no tipo union leva em conta o caso não autenticado, o que é um padrão comum para dados de sessão. Com essa declaração no lugar, event.locals.user agora está totalmente tipado como { id: string; email: string; role: 'user' | 'admin' | 'superadmin' } | null em todo o seu código do servidor.

Populando locals no hook handle

Com App.Locals declarado, o hook pode escrever em event.locals com total segurança de tipos — o TypeScript capturará formas incorretas em tempo de compilação. O benefício real fica visível à medida que sua aplicação cresce e App.Locals se expande para conter múltiplas peças de dados com escopo de requisição. Estenda app.d.ts primeiro, depois popule os novos campos no hook:

// src/app.d.ts

declare global {
	namespace App {
		interface Locals {
			user: {
				id: string
				email: string
				role: 'user' | 'admin' | 'superadmin'
				tenantId: string | null
			} | null
			requestId: string
			featureFlags: Record<string, boolean>
		}
	}
}

export {}

// src/hooks.server.ts

import type { Handle } from '@sveltejs/kit'
import { validateSessionToken } from '$lib/server/auth'
import { getFeatureFlags } from '$lib/server/flags'
import { randomUUID } from 'crypto'

export const handle: Handle = async ({ event, resolve }) => {
	// Assign a request ID for tracing
	event.locals.requestId = randomUUID()

	// Validate session
	const sessionToken = event.cookies.get('session')
	event.locals.user = null

	if (sessionToken) {
		event.locals.user = await validateSessionToken(sessionToken)
	}

	// Load feature flags (may depend on the user)
	event.locals.featureFlags = await getFeatureFlags(event.locals.user?.id ?? null)

	return resolve(event)
}

Onde o tipo flui

A declaração em app.d.ts é a única fonte de verdade. Uma vez escrita, o tipo fica disponível automaticamente em todo contexto onde o SvelteKit fornece um objeto de evento ou locals — você não o importa ou re-declara em nenhum lugar.

O que pertence a locals

Locals devem conter dados que são:

Com escopo de requisição — criados do zero por requisição, não compartilhados entre requisições
Necessários por múltiplos handlers — se apenas uma função load o utiliza, busque-o lá em vez disso
Derivados da própria requisição — dados de sessão, identidade de tenant, IDs de requisição, feature flags condicionados ao usuário, preferências de tema por usuário lidas de um cookie, atribuições de bucket para testes A/B

Não coloque grandes payloads em locals. Os locals são mantidos na memória durante a duração da requisição. Um registro de usuário com alguns campos está bem; um megabyte de dados do dashboard ou uma lista de todos os produtos não — isso pertence à função load que precisa disso.

A cadeia completa de propagação de locals

O diagrama abaixo captura como locals flui pela hierarquia completa do lado do servidor para uma única requisição. hooks.server.ts é sempre a autoridade originadora: ele é executado primeiro e escreve em event.locals.

A partir daí, locals estão disponíveis tanto para +layout.server.ts quanto para +page.server.ts diretamente através do objeto event. Além disso, +layout.server.ts pode passar dados para +page.server.ts através de await parent(), o que significa que um load de página pode receber tanto os locals validados brutos quanto quaisquer dados derivados ou enriquecidos que o layout retornou.

O que os loads do servidor de página e layout retornam é passado para suas funções load universais correspondentes e componentes Svelte via a prop data. É importante notar que locals em si nunca faz parte desse valor de retorno e nunca chega ao navegador.

Dois pontos merecem atenção nesta imagem. Primeiro, +page.server.ts tem dois caminhos pelos quais pode receber dados de sessão: diretamente de event.locals (definido pelo hook) e via await parent() (dados que o load do servidor do layout escolheu retornar).

Usar await parent() para dados de sessão é um padrão comum, mas os artigos anteriores desta série estabeleceram que chamar await parent() antes de iniciar seus próprios fetches cria uma cascata de serialização.

Quando o load de página só precisa do usuário de sessão já em event.locals, ler locals.user diretamente evita completamente a chamada ao parent e elimina a cascata. await parent() se torna valioso quando você genuinamente precisa de algo que o layout computou e retornou, não apenas do valor bruto de locals.

Segundo, o nó final — +layout.js | +page.js — representa o limite onde os dados do servidor cruzam para o território do cliente. O que quer que os loads do servidor retornem se torna a prop data nos componentes Svelte. event.locals em si nunca está nesse valor de retorno; ele permanece inteiramente na memória do servidor.

Lendo locals em funções load

Todo campo populado pelo hook está disponível com seu tipo correto em toda função load do servidor na aplicação:

// src/routes/dashboard/+page.server.ts

import type { PageServerLoad } from './$types'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ locals, fetch }) => {
	if (!locals.user) {
		error(401, 'You must be logged in to view the dashboard')
	}

	const res = await fetch(`/api/users/${locals.user.id}/dashboard`)
	const dashboardData = await res.json()

	return {
		user: locals.user,
		dashboard: dashboardData
	}
}

O objeto locals disponível nas funções load é o mesmo objeto populado pelo hook. Não há cópia ou serialização entre eles e eles compartilham a mesma referência dentro de uma única requisição.

Locals em handlers de rotas de API

Locals estão disponíveis em handlers de API +server.ts quando você desestrutura locals do parâmetro de evento do handler. O mesmo tipo App.Locals se aplica automaticamente, assim como nas funções load de página:

// src/routes/api/users/+server.ts

import type { RequestHandler } from './$types'
import { error, json } from '@sveltejs/kit'

export const GET: RequestHandler = ({ locals }) => {
	if (!locals.user) {
		error(401, 'Unauthorised')
	}

	// locals.user is fully typed here — { id, email, role } | null
	return json({ userId: locals.user.id })
}

Todos os handlers de verbos HTTP como GET, POST, PATCH, PUT, DELETE, OPTIONS e HEAD recebem o mesmo objeto de evento, portanto locals está acessível em todos eles. Isso importa para endpoints de mutação: um handler POST que aplica permissões lê o mesmo locals.user definido pelo hook que um handler GET lê.

Locals não estão disponíveis em funções load universais

Este é um ponto crítico que frequentemente causa confusão. O objeto event.locals está disponível apenas em código do lado do servidor. Funções load universais (+page.ts e +layout.ts) são executadas tanto em contextos de servidor quanto de cliente. O locals é uma construção somente para servidor e os loads universais são executados no navegador após a hidratação, onde a memória do servidor não está acessível.

Para passar dados derivados de locals para uma função load universal, o load do servidor deve retorná-los explicitamente, e o load universal os lê a partir do parâmetro data:

// src/routes/+page.server.ts — server load returns the locals value

import type { PageServerLoad } from './$types'

export const load: PageServerLoad = ({ locals }) => {
	return {
		theme: locals.theme // pass the value out through the return object
	}
}

// src/routes/+page.ts — universal load receives it via data

import type { PageLoad } from './$types'

export const load: PageLoad = ({ data }) => {
	return {
		theme: data.theme // data.theme came from +page.server.ts
	}
}

Este padrão em duas etapas é a única maneira de os valores de locals chegarem ao código universal. O load do servidor atua como um gateway deliberado: você escolhe quais campos cruzam o limite servidor/cliente ao incluí-los no valor de retorno. Nada de event.locals vaza automaticamente por essa linha.

O Hook handleFetch

O que ele faz e quando usá-lo

O hook handleFetch intercepta todas as chamadas fetch feitas a partir de funções de carregamento e handlers +server.ts durante a renderização no lado do servidor. Ele recebe o objeto de requisição, a função fetch para continuar a chamada e o objeto event (que dá acesso a event.locals). Ele pode inspecionar e modificar a requisição de saída antes que ela seja executada.

Use handleFetch quando você tiver uma preocupação transversal que se aplica a todas ou à maioria das chamadas fetch do lado do servidor — algo que você, de outra forma, teria que copiar para cada função de carregamento. Casos comuns são:

Reescrita de URL interna — redirecionar URLs voltadas ao público para endereços de serviço internos durante o SSR para evitar idas e vindas pela rede
Headers de autenticação compartilhados — injetar uma chave de API ou token de serviço a serviço em requisições para uma API downstream
Encaminhamento de cookies — passar os cookies do navegador para uma API interna durante o SSR (não feito automaticamente para requisições cross-origin)

Não use handleFetch para lógica que se aplica apenas a uma ou duas requisições específicas — isso pertence a essas funções de carregamento.

Uma restrição importante: handleFetch só é executado no servidor. Depois que a página é hidratada no navegador, as chamadas fetch do código do lado do cliente o ignoram completamente.

Caso de uso 1: Reescrita de URL interna

Quando seu aplicativo é implantado atrás de um balanceador de carga ou em um ambiente de contêiner, um fetch para https://your-app.com/api/products a partir de uma função de carregamento do servidor faz uma ida e volta completa pela rede, mesmo que o handler da API viva no mesmo processo. handleFetch pode reescrever isso para um endereço interno:

// src/hooks.server.ts

import type { HandleFetch } from '@sveltejs/kit'

export const handleFetch: HandleFetch = async ({ request, fetch }) => {
	// During SSR, rewrite public-facing API calls to the internal service address
	if (request.url.startsWith('https://your-app.com/api/')) {
		const internalUrl = request.url.replace(
			'https://your-app.com/api/',
			'http://internal-api-service:3001/'
		)
		request = new Request(internalUrl, request)
	}

	return fetch(request)
}

Caso de uso 2: Injetando headers de autenticação compartilhados

Se todas as suas funções de carregamento do servidor chamam um serviço downstream que requer uma chave de API, você pode adicionar o header de forma centralizada em vez de em cada função de carregamento. O parâmetro event dá acesso a event.locals, para que você possa anexar a identidade do usuário junto com o segredo do serviço:

// src/hooks.server.ts

import type { HandleFetch } from '@sveltejs/kit'
import { INTERNAL_API_SECRET } from '$env/static/private'

export const handleFetch: HandleFetch = async ({ request, fetch, event }) => {
	if (request.url.includes('internal-api-service')) {
		request = new Request(request, {
			headers: {
				...Object.fromEntries(request.headers),
				'X-Internal-Secret': INTERNAL_API_SECRET,
				'X-User-Id': event.locals.user?.id ?? 'anonymous'
			}
		})
	}

	return fetch(request)
}

Caso de uso 3: Encaminhando cookies para APIs internas

Durante o SSR, quando uma função de carregamento do servidor chama um endpoint de API interno (outro +server.ts no mesmo aplicativo), o SvelteKit encaminha automaticamente os cookies do navegador. Mas para requisições cross-origin, como um subdomínio ou porta diferente, os cookies não são encaminhados automaticamente pelas regras SameSite nativas do fetch do navegador, mesmo que a requisição se origine do servidor. Use handleFetch para anexar o cookie de sessão explicitamente:

// src/hooks.server.ts

import type { HandleFetch } from '@sveltejs/kit'

export const handleFetch: HandleFetch = async ({ request, fetch, event }) => {
	// Forward session cookie to the internal auth service on a different subdomain
	if (request.url.startsWith('https://api.internal.yourapp.com/')) {
		const cookie = event.request.headers.get('cookie')
		if (cookie) {
			request = new Request(request, {
				headers: { ...Object.fromEntries(request.headers), cookie }
			})
		}
	}

	return fetch(request)
}

Esse padrão é particularmente comum quando seu aplicativo tem um serviço de autenticação separado ou um gateway de API que precisa ver o mesmo cookie de sessão que o navegador enviou.

O Hook handleError

Quando usar handleError

Use handleError quando precisar realizar qualquer um dos seguintes:

Reportar para um serviço de monitoramento (Sentry, Datadog, etc.) sem repetir o código de reporte em cada função de carregamento
Sanitizar a mensagem de erro exibida ao usuário — por padrão, o SvelteKit pode expor texto de erro interno
Anexar contexto da requisição (ID do usuário, ID da requisição, URL) aos relatórios de erro, o que funções de carregamento individuais não conseguem fazer sem duplicação
Diferenciar tipos de erro para dar aos erros 404 uma mensagem diferente para o usuário do que aos erros 500

Não use handleError para fluxo de controle esperado. Se você quiser retornar um 401 quando um usuário não está autenticado, use error(401, 'Unauthorised') dentro da função de carregamento. handleError não será executado para isso.

O handleError é apenas para exceções genuinamente inesperadas.

Erros esperados vs. inesperados

Essa distinção é o conceito mais importante em handleError. O SvelteKit tem dois tipos de erro:

Erros esperados — lançados com error(status, message) de @sveltejs/kit. Esses são fluxo de controle deliberado. O SvelteKit os trata diretamente e não chama handleError.
Erros inesperados — qualquer valor lançado que não seja uma instância de erro do SvelteKit: throw new Error('...'), um JSON.parse falho, um timeout de banco de dados, uma rejeição de promise não tratada. Esses são bugs reais ou falhas de infraestrutura. O SvelteKit chama handleError para esses.

error(404, 'Not found')   			 → handleError NOT called (expected)
throw new Error('DB timeout')   → handleError IS called (unexpected)
undefined.property              → handleError IS called (runtime error)

Como o SvelteKit chama handleError

handleError recebe quatro argumentos:

error — o valor lançado (pode não ser uma instância de Error se alguém lançou um objeto simples ou string)
event — o evento de requisição completo, dando acesso a event.locals, event.url e event.request
status — o código de status HTTP que o SvelteKit determinou (geralmente 500, mas pode ser 404 se a rota não foi encontrada)
message — uma string de mensagem padrão curta que o SvelteKit derivou do status

O valor de retorno de handleError se torna o objeto page.error que +error.svelte recebe. Por padrão, sem handleError, o SvelteKit retorna { message } onde message é uma string genérica segura. Você pode retornar qualquer formato que quiser, desde que o declare.

Tipando o objeto de erro com App.PageError

Assim como App.Locals tipifica event.locals, App.PageError tipifica o objeto que handleError retorna e que +error.svelte recebe via page.error. Adicione-o em src/app.d.ts:

// src/app.d.ts

declare global {
	namespace App {
		interface Locals {
			user: { id: string; email: string; role: string } | null
			requestId: string
		}
		interface PageError {
			message: string
			errorId?: string // a correlatable ID you can show to users
		}
	}
}

export {}

Com PageError declarado, o valor de retorno de handleError é verificado por tipo, e page.error em +error.svelte é totalmente tipado.

Implementando handleError

// src/hooks.server.ts

import type { HandleError } from '@sveltejs/kit'
import { randomUUID } from 'crypto'

export const handleError: HandleError = async ({ error, event, status, message }) => {
	const errorId = randomUUID()

	// Avoid logging 404s to your error tracker since they are expected
	if (status !== 404) {
		// In production, replace console.error with your error tracking service
		// (e.g. Sentry, Datadog). Here a structured log is used for illustration.
		console.error({
			errorId,
			status,
			message: error instanceof Error ? error.message : String(error),
			stack: error instanceof Error ? error.stack : undefined,
			url: event.url.pathname,
			userId: event.locals.user?.id ?? null,
			requestId: event.locals.requestId
		})
	}

	// The returned object is what page.error will contain in +error.svelte
	// Never expose internal error details (stack traces, DB errors) to the client
	return {
		message: status === 404 ? 'Page not found' : 'An unexpected error occurred',
		errorId // show the user a reference ID they can report
	}
}

Lendo o erro em +error.svelte

O objeto retornado por handleError está disponível como page.error no componente +error.svelte mais próximo. Com o tipo PageError declarado, page.error é totalmente tipado:

<!-- src/routes/+error.svelte -->
<script>
	import { page } from '$app/state'
</script>

<h1>{page.status}</h1>
<p>{page.error.message}</p>

{#if page.error.errorId}
	<p>Reference: <code>{page.error.errorId}</code></p>
{/if}

A contraparte do lado do cliente: hooks.client.ts

Cada erro coberto acima acontece no servidor, onde hooks.server.ts está no controle. Mas assim que a página é hidratada e o usuário navega no navegador, os erros acontecem inteiramente no código do lado do cliente. Esses incluem falhas de renderização de componentes, rejeições de promise não tratadas em manipuladores de eventos e erros de navegação do lado do cliente. Para esses, o hook do servidor nunca é invocado. O SvelteKit fornece hooks.client.ts com sua própria exportação handleError exatamente para esse caso.

A assinatura é quase idêntica, mas o argumento event não inclui propriedades exclusivas do servidor, como cookies ou locals. Use-o para enviar erros do lado do cliente para o seu rastreador de erros:

// src/hooks.client.ts

import type { HandleClientError } from '@sveltejs/kit'

export const handleError: HandleClientError = async ({ error, event, status, message }) => {
	if (status !== 404) {
		// Use a client-side error reporting SDK here
		window.errorTracker?.report({ error, url: event.url.pathname, status })
	}

	return {
		message: status === 404 ? 'Page not found' : 'Something went wrong'
	}
}

Uma configuração completa de tratamento de erros tem tanto hooks.server.ts quanto hooks.client.ts exportando handleError, garantindo que nenhum erro (do servidor ou do cliente) passe despercebido e sem rastreamento.

Compondo Múltiplos Hooks com sequence

O problema com uma única função handle grande

Quando você tem apenas a validação de sessão para fazer, uma única função handle é suficiente. Mas aplicações reais acumulam preocupações transversais: logging de requisições, limitação de taxa, headers de segurança, carregamento de feature flags, resolução multi-tenant, tratamento de CORS. Se você continuar adicionando tudo isso a uma única função handle, ela se tornará uma parede de código impossível de manter, onde cada preocupação está entrelaçada com todas as outras.

Você poderia tentar dividir a lógica em funções auxiliares chamadas a partir de um único handle, mas isso não é o mesmo que uma composição verdadeira. Cada preocupação não pode, de forma independente, decidir curto-circuitar a requisição, não pode encapsular o ciclo de vida da resposta de forma independente e não pode ser ativada ou desativada de forma limpa em diferentes ambientes.

sequence resolve isso permitindo que cada preocupação viva em sua própria função Handle focada e, em seguida, conectando-as em uma única linha.

Quando usar sequence

Use sequence assim que tiver mais de uma preocupação distinta em hooks.server.ts. Candidatos comuns para hooks separados são:

Validação de sessão — sempre precisa ser executada primeiro para que hooks posteriores e todas as funções de carregamento possam ler locals.user
Limitação de taxa — pode curto-circuitar a requisição antes que qualquer trabalho de autenticação aconteça, economizando recursos
Logging de requisições — encapsula tudo para medir a duração total da requisição, incluindo todo o trabalho downstream
Headers de resposta de segurança — opera na resposta finalizada, então é executado por último
Resolução multi-tenant — lê um subdomínio ou header para definir locals.tenantId antes da validação de sessão, já que a validação de sessão pode depender do tenant
Tratamento de preflight CORS — pode curto-circuitar requisições OPTIONS imediatamente sem tocar em autenticação ou roteamento
Hidratação de feature flags — carrega as flags após o usuário ser conhecido, então é executado após a validação de sessão

Manter esses como funções nomeadas separadas também os torna individualmente testáveis e reutilizáveis em diferentes arquivos hooks.server.ts em um monorepo.

Como sequence funciona

sequence chama cada hook em ordem, passando o evento e uma função resolve que delega para o próximo hook na cadeia. O resultado é um middleware aninhado: o hook mais externo começa primeiro e termina por último, razão pela qual um hook de logging colocado primeiro pode medir o tempo total da requisição, incluindo todo o trabalho subsequente.

// src/hooks.server.ts

import { sequence } from '@sveltejs/kit/hooks'
import type { Handle } from '@sveltejs/kit'

const logging: Handle = async ({ event, resolve }) => {
	const start = performance.now()
	const response = await resolve(event)
	const duration = Math.round(performance.now() - start)

	console.log(`${event.request.method} ${event.url.pathname} ${response.status} ${duration}ms`)

	return response
}

const session: Handle = async ({ event, resolve }) => {
	const token = event.cookies.get('session')
	event.locals.user = null

	if (token) {
		const { validateSessionToken } = await import('$lib/server/auth')
		event.locals.user = await validateSessionToken(token)
	}

	return resolve(event)
}

const security: Handle = async ({ event, resolve }) => {
	const response = await resolve(event)

	response.headers.set('X-Frame-Options', 'DENY')
	response.headers.set('X-Content-Type-Options', 'nosniff')
	response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')

	return response
}

export const handle = sequence(logging, session, security)

Cada hook encapsula o próximo como um middleware aninhado. O hook mais externo (logging) começa antes de tudo e termina depois de tudo, razão pela qual ele pode medir a duração total da requisição. A operação mais interna é o handler de rota real.

sequence chama cada hook em ordem, passando o evento e uma função resolve que chama o próximo hook na cadeia. O hook de logging vê o tempo completo da requisição porque aguarda resolve(event), que executa todos os hooks subsequentes. O hook de segurança modifica os headers de resposta após a rota ter sido processada.

A ordem importa

A ordem em que você passa os hooks para sequence tem consequências diretas:

Sessão antes de qualquer coisa que leia locals.user — hooks posteriores na cadeia e todas as funções de carregamento dependem de locals.user estar preenchido
Limitação de taxa antes da sessão — se uma requisição está sendo limitada, você pode rejeitá-la antes de fazer qualquer trabalho no banco de dados para autenticação
Logging como o mais externo (primeiro) — ele precisa de await resolve(event), que executa toda a cadeia interna, fornecendo tempo total preciso
Headers de segurança como o mais externo por último (último) — esses operam no objeto de resposta final após o handler de rota ter sido executado

Uma ordem errada produz bugs sutis. Um hook de limitação de taxa colocado após o hook de sessão ainda valida a sessão para cada requisição que deveria ter sido bloqueada. Um hook de segurança colocado antes do hook de sessão define headers em uma resposta antes que resolve tenha sido executado e, como os hooks modificam o mesmo objeto de resposta, os headers podem ser sobrescritos.

Curto-circuitando a cadeia

Um hook não precisa chamar resolve. Se ele retornar uma Response diretamente, o restante da cadeia — e o handler de rota — nunca é executado. Essa é a maneira correta de implementar limitação de taxa, respostas de preflight CORS e bloqueio de IP, porque você quer rejeitar a requisição antes que qualquer trabalho downstream seja feito.

// A rate-limit hook that short-circuits without calling resolve

const rateLimit: Handle = async ({ event, resolve }) => {
	const ip = event.getClientAddress()
	const allowed = await checkRateLimit(ip)

	if (!allowed) {
		// Return a response directly — session, route handler, security headers all skipped
		return new Response('Too Many Requests', {
			status: 429,
			headers: { 'Retry-After': '60' }
		})
	}

	return resolve(event)
}

export const handle = sequence(logging, rateLimit, session, security)

Quando rateLimit retorna antecipadamente, logging ainda termina porque encapsula a chamada resolve(event). session e security nunca são executados. Esse é o resultado correto: você quer registrar que a requisição foi limitada, mas não quer validar uma sessão ou definir headers de segurança para uma resposta que é simplesmente 429 Too Many Requests.

Request
  └─ logging (starts timer)
       └─ rateLimit → returns 429 directly ✗ (session and security skipped)
  └─ logging (logs "429 Too Many Requests 1ms")
Response

Compartilhando dados entre hooks via locals

Hooks anteriores na cadeia sequence podem definir propriedades em event.locals que hooks posteriores na cadeia leem. Este é essencialmente o mesmo mecanismo que os hooks usam para compartilhar dados com funções de load, mas aplicado dentro do próprio pipeline de hooks.

Um exemplo comum é a resolução multi-tenant: o tenant é identificado a partir do subdomínio antes que a validação de sessão seja executada, porque a tabela de sessões pode ter escopo por tenant.

// src/hooks.server.ts

const tenant: Handle = async ({ event, resolve }) => {
	// Resolve tenant from hostname: acme.yourapp.com → tenantId 'acme'
	const hostname = event.request.headers.get('host') ?? ''
	const subdomain = hostname.split('.')[0]
	event.locals.tenantId = subdomain !== 'www' ? subdomain : null

	return resolve(event)
}

const session: Handle = async ({ event, resolve }) => {
	event.locals.user = null
	const token = event.cookies.get('session')

	if (token && event.locals.tenantId) {
		// Session validation is tenant-scoped — reads locals.tenantId set by the tenant hook
		event.locals.user = await validateSessionForTenant(token, event.locals.tenantId)
	}

	return resolve(event)
}

export const handle = sequence(logging, tenant, session, security)

O hook tenant é executado antes de session na cadeia, portanto, quando session lê event.locals.tenantId, ele já está definido. As funções de load downstream podem então ler tanto locals.tenantId quanto locals.user sem qualquer conhecimento de como foram populados.

Dividindo hooks em arquivos separados

Para aplicações maiores, defina cada hook em seu próprio arquivo e importe-os em hooks.server.ts. Isso mantém cada responsabilidade autocontida e testável de forma independente.

src/
  hooks.server.ts          ← only imports and sequence()
  lib/
    server/
      hooks/
        logging.ts         ← const logging: Handle
        session.ts         ← const session: Handle
        security.ts        ← const security: Handle
        rate-limit.ts      ← const rateLimit: Handle

// src/hooks.server.ts

import { sequence } from '@sveltejs/kit/hooks'
import { logging } from '$lib/server/hooks/logging'
import { rateLimit } from '$lib/server/hooks/rate-limit'
import { session } from '$lib/server/hooks/session'
import { security } from '$lib/server/hooks/security'

export const handle = sequence(logging, rateLimit, session, security)

hooks.server.ts se torna uma declaração de intenção em uma única linha. Adicionar ou remover uma responsabilidade é uma única alteração de importação.

Erros Comuns e Anti-Padrões

Definindo locals em +layout.server.ts em vez do Hook

Como +layout.server.ts tem acesso a event.locals, é tecnicamente possível escrever em locals lá em vez de no hook. Evite isso. O SvelteKit executa +layout.server.ts e +page.server.ts simultaneamente para maximizar o paralelismo. Se o load do layout define locals.user e o load da página tenta lê-lo, há uma condição de corrida: o load da página pode ser executado antes que o layout tenha terminado de escrever, lendo um valor não inicializado.

// Avoid: Setting locals in a layout server load

// src/routes/+layout.server.ts
export const load: LayoutServerLoad = async ({ locals, cookies }) => {
	// BAD: writing to locals here is not safe
	locals.user = await getUser(cookies.get('session'))
	return {}
}

// src/routes/dashboard/+page.server.ts
export const load: PageServerLoad = ({ locals }) => {
	// RACE: locals.user may not be set yet because the layout runs in parallel
	if (!locals.user) error(401, 'Unauthorised')
}

// Preferred: Always set locals in hooks.server.ts, before any load runs

// src/hooks.server.ts
export const handle: Handle = async ({ event, resolve }) => {
	event.locals.user = await validateSessionToken(event.cookies.get('session') ?? '')
	return resolve(event)
}

O hook é executado sequencialmente antes de qualquer manipulador de rota, o que significa que event.locals está totalmente populado antes que +layout.server.ts ou +page.server.ts sejam iniciados. Essa é a garantia que torna o locals seguro para leitura em qualquer lugar do pipeline do lado do servidor.

Se você se encontrar precisando chamar await parent() apenas para acessar dados de sessão que deveriam estar em locals, esse é um forte sinal de que os dados estão sendo definidos no lugar errado.

Lançando um redirect dentro do handle

É tentador realizar redirecionamentos de autenticação dentro do hook handle, já que ele é executado para cada requisição. Isso é tecnicamente possível, mas geralmente está errado. Redirecionar a partir de handle se aplica a todas as requisições, incluindo requisições de assets estáticos, requisições de prefetch internas do SvelteKit e chamadas de API de serviços externos. Um redirecionamento abrangente em handle pode quebrar coisas de maneiras não óbvias.

// Avoid: Redirecting from handle is too broad

export const handle: Handle = async ({ event, resolve }) => {
	if (!event.locals.user && !event.url.pathname.startsWith('/login')) {
		redirect(302, '/login')
	}
	return resolve(event)
}

// Preferred: Redirect from individual page or layout server load functions,
// using locals.user populated by handle

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

export const load: LayoutServerLoad = ({ locals }) => {
	if (!locals.user) redirect(302, '/login')
	return { user: locals.user }
}

A abordagem de guarda baseada em layout é mais cirúrgica. Ela protege exatamente as rotas no grupo de rotas (protected), deixa as rotas públicas intactas e é fácil de compreender ao ler a árvore de rotas.

Mutando event.locals após o resolve

Definir propriedades em event.locals após chamar resolve(event) não tem efeito na requisição atual porque as funções de load e os manipuladores já foram executados nesse ponto. Os locals devem ser populados antes de resolve.

// Wrong: Setting locals after resolve

export const handle: Handle = async ({ event, resolve }) => {
	const response = await resolve(event)
	event.locals.user = await getUser(event.cookies.get('session')) // ← too late
	return response
}

// Correct: Setting locals before resolve

export const handle: Handle = async ({ event, resolve }) => {
	event.locals.user = await getUser(event.cookies.get('session')) // ← runs before load
	return resolve(event)
}

Esquecendo de Inicializar Locals como null

Se uma função de load lê event.locals.user sem que o hook sempre o defina, o TypeScript reclamará que a propriedade pode não estar definida. Sempre inicialize cada propriedade de locals no hook, mesmo que com null, para garantir que o formato corresponda a App.Locals:

// Avoid: Conditionally setting — user may be undefined if no cookie

export const handle: Handle = async ({ event, resolve }) => {
	const token = event.cookies.get('session')
	if (token) {
		event.locals.user = await validateSessionToken(token)
	}
	return resolve(event)
}

// Preferred: Always set a value

export const handle: Handle = async ({ event, resolve }) => {
	event.locals.user = null

	const token = event.cookies.get('session')
	if (token) {
		event.locals.user = await validateSessionToken(token)
	}

	return resolve(event)
}

Considerações de Performance e Escalabilidade

O hook handle é executado em cada única requisição HTTP ao seu servidor SvelteKit. Qualquer operação assíncrona dentro dele adiciona latência a cada requisição. A validação de sessão que faz uma consulta ao banco de dados ou uma chamada de API deve ser o mais rápida possível.

Para validação de sessão, prefira JWTs com janelas de expiração curtas ou tokens de sessão assinados que podem ser validados localmente sem uma ida e volta ao banco de dados. Se você precisar validar contra um banco de dados ou cache em cada requisição, certifique-se de que a consulta está indexada e considere um cache em memória rápido como o Redis para evitar acessar o banco de dados a cada visualização de página.

O hook handleFetch é executado para cada chamada fetch feita durante o SSR e também pode adicionar latência lá. Mantenha-o leve. Reescrita de URL é rápida; fazer chamadas de rede adicionais dentro de handleFetch aumentaria a latência.

O logging em handleError deve ser não bloqueante sempre que possível. Em plataformas edge como o Cloudflare Workers, você pode usar event.platform?.context?.waitUntil(promise) para adiar trabalho não crítico (como enviar para um rastreador de erros) após a resposta. Em adaptadores Node.js, essa API não está disponível, portanto prefira escrever em uma fila ou usar um padrão fire-and-forget em vez de fazer uma chamada HTTP síncrona ao seu rastreador de erros dentro do caminho crítico.

Conclusão

hooks.server.ts é o único ponto de entrada pelo qual toda requisição do lado do servidor passa. O hook handle é executado primeiro, antes de qualquer função de load ou action de formulário, e é o lugar certo para realizar a configuração com escopo de requisição: validação de sessão, rastreamento de requisições, carregamento de feature flags. Qualquer coisa escrita em event.locals dentro do hook está disponível para toda função de load, action de formulário e manipulador de API na aplicação durante a duração daquela requisição.

A declaração de tipo em src/app.d.ts faz a ponte entre o hook e a função de load: qualquer formato que você declarar para App.Locals é o tipo que event.locals terá em todo o código. Juntos, o hook e a declaração de tipo substituem o que de outra forma seria código repetido de leitura de sessão espalhado por dezenas de funções de load.

handleFetch e handleError completam o ciclo de vida para as outras duas preocupações principais: modificação de requisições upstream e captura de erros inesperados. sequence permite que você mantenha cada preocupação em sua própria função focada e as componha sem aninhamento.

Principais Pontos

O hook handle em hooks.server.ts intercepta cada requisição HTTP antes que qualquer manipulador de rota seja executado. Use-o para popular event.locals com dados com escopo de requisição, como o usuário da sessão validada.

Declare App.Locals em src/app.d.ts para obter segurança TypeScript completa no hook e em toda função de load do servidor que lê de locals. Sempre inicialize cada propriedade com um valor base, tipicamente null, dentro do hook.

handleFetch reescreve ou enriquece chamadas fetch do lado do servidor antes de serem executadas, útil para alias de URLs internas e injeção de cabeçalhos de autenticação compartilhados. handleError é executado em exceções inesperadas, o lugar certo para reportar a serviços de monitoramento sem expor detalhes internos ao cliente.

O helper sequence de @sveltejs/kit/hooks compõe múltiplas funções Handle em uma, executando-as em ordem. Divida os hooks por responsabilidade e componha-os de forma limpa em vez de escrever uma função grande.

Próximos Passos

Com locals populado no hook, toda função de load do servidor na aplicação tem acesso ao usuário validado sem nenhuma leitura redundante de sessão. O próximo artigo, Usando Dados do Pai em Funções de Load, aborda como as funções de load acessam dados retornados pelos loads de layout ancestrais através da função parent(), a armadilha de cascata que esperar por ela muito cedo cria e os padrões que preservam o paralelismo enquanto ainda mesclam dados do pai e da página.

Leitura Adicional

Documentação de Hooks do SvelteKit — referência oficial para todos os tipos de hook, incluindo handle, handleFetch, handleError e o helper sequence
SvelteKit App.Locals — referência oficial para tipagem de event.locals com a interface App.Locals em app.d.ts
Erros e Redirecionamentos em Funções de Load — como error() e redirect() funcionam em funções de load, complementando o padrão de guarda baseado em locals introduzido aqui