Por Qué Existen los Hooks

Los artículos anteriores de esta serie describieron qué sucede dentro de una función load: recibir un objeto event, hacer llamadas fetch, leer cookies y retornar datos. Lo que esos artículos no cubrieron fue la pregunta de qué sucede antes de que una función load se ejecute. ¿Quién valida la sesión? ¿Quién decide si un usuario está autenticado antes de que siquiera empiece una función load? ¿De dónde viene event.locals.user cuando tus funciones load lo leen?

La respuesta es hooks.server.ts. Este archivo se encuentra en la raíz de tu directorio src/ y exporta funciones que SvelteKit llama en puntos específicos del ciclo de vida de solicitud y respuesta. A diferencia de las funciones load, (que tienen alcance a una única ruta), los hooks se ejecutan para cada solicitud que pasa por el servidor, sin importar qué ruta tienen como destino.

Este artículo cubre el sistema completo de hooks: el hook handle que envuelve cada solicitud, cómo usarlo para poblar event.locals con datos de sesión validados, la configuración correcta de TypeScript para App.Locals, el hook handleFetch para reescribir llamadas fetch del lado del servidor, el hook handleError para capturar y registrar excepciones, y el helper sequence para componer múltiples funciones hook de forma limpia.

El Problema con la Validación de Sesión en las Funciones Load

Considera una aplicación SvelteKit donde todas las diferentes rutas necesitan saber quién es el usuario actual. Con solo funciones load disponibles, hay dos opciones malas.

La primera opción mala es leer y validar la cookie de sesión en cada función load individual. Cuando tenemos veinte rutas, eso significa veinte lugares donde vive la lógica de validación, veinte lugares donde un bug podría dejar una ruta sin protección, y veinte lecturas redundantes de cookies y llamadas a la API de sesión en cada solicitud.

La segunda opción mala es leer la cookie en la función load del layout raíz del servidor y confiar en que await parent() en cada función load de página dará acceso a la sesión. Esto parece limpio, pero tiene una falla crítica: SvelteKit no vuelve a ejecutar un load de layout en cada navegación del lado del cliente. Solo lo vuelve a ejecutar cuando las dependencias de datos de ese load son invalidadas explícitamente — mediante invalidate() o invalidateAll().

Sin eso, el resultado en caché del renderizado inicial del servidor se reutiliza, lo que significa que la verificación de sesión se omite silenciosamente en las visitas posteriores a la página. Más importante aún, las acciones de formulario omiten completamente los loads de layout. Una acción de formulario en una ruta no puede usar parent() para obtener la sesión porque las acciones de formulario no son funciones load y parent() no está disponible para ellas.

Solución: hooks.server.ts y event.locals

La solución es un archivo hooks.server.ts que puede exportar cualquiera de los siguientes hooks:

handle: se ejecuta para cada solicitud — el lugar adecuado para validar la sesión y poblar event.locals
handleFetch: se ejecuta para cada llamada fetch del lado del servidor, útil para reescribir URLs e inyectar encabezados de autenticación
handleError: se ejecuta ante excepciones inesperadas, el lugar adecuado para reportar a servicios de monitoreo sin exponer detalles al cliente
sequence: una utilidad importada desde @sveltejs/kit/hooks para componer múltiples funciones Handle en una única exportación handle, ejecutándolas en orden

event.locals es un objeto JavaScript plano que SvelteKit crea de forma nueva para cada solicitud entrante. El hook handle escribe en él antes de llamar a resolve, y cada manejador del lado del servidor para esa misma solicitud — funciones load, acciones de formulario, manejadores de API — lee de él. Nunca se serializa al navegador y se descarta una vez entregada la respuesta. El resto de este artículo explica su ciclo de vida completo.

El Hook handle

El hook handle es la exportación más importante de hooks.server.ts. Se ejecuta para cada solicitud sin excepción: cargas de página, rutas de API, acciones de formulario, solicitudes de prefetch y cualquier otro tráfico HTTP que llegue a tu servidor SvelteKit. Se ejecuta una vez por solicitud, puebla event.locals con la sesión validada, y cada manejador posterior para esa solicitud lee de locals en lugar de repetir la validación. Recibe el evento de solicitud y una función resolve que continúa el pipeline de solicitudes.

El objeto event y event.locals

Cada hook y función load en SvelteKit recibe un objeto event. Es el mismo tipo de objeto a lo largo del ciclo de vida del lado del servidor: los hooks lo reciben, las funciones load lo reciben, las acciones de formulario lo reciben. Las propiedades más relevantes para los hooks son:

event.request — el objeto Request estándar de la Web con encabezados, método y cuerpo
event.cookies — un wrapper tipado para leer y escribir cookies en la respuesta
event.url — la URL parseada de la solicitud entrante
event.locals — un objeto JavaScript plano, solo del servidor, creado de forma nueva para cada solicitud
event.getClientAddress() — retorna la dirección IP del cliente que se conecta

event.locals merece atención especial. Comienza como un objeto vacío {} al inicio de cada solicitud y existe únicamente en memoria del servidor — nada de él se envía nunca al navegador. El hook handle lo puebla antes de que se ejecute el manejador de ruta; cada función load del servidor, acción de formulario y manejador de API para esa misma solicitud luego lee de él. Una vez enviada la respuesta, el objeto se descarta.

Piénsalo como un bloc de notas tipado con alcance de solicitud: el hook lo llena, y cada manejador downstream lo consume — sin que ninguno de ellos necesite volver a hacer fetch o revalidar los mismos datos.

El passthrough y la forma de middleware

La implementación más simple posible simplemente llama a resolve directamente:

// 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)
}

Esto es un passthrough; no hace nada. Pero la estructura revela el patrón. Todo lo que está antes de resolve(event) se ejecuta antes de que se procese la ruta; todo lo que está después se ejecuta tras generar la respuesta.

resolve(event) no es solo la siguiente función en la pila de llamadas — representa todo el pipeline downstream: el enrutamiento de SvelteKit, el manejador de ruta coincidente, todas las funciones load y acciones de formulario, y en última instancia la construcción de la respuesta. Cualquier cosa escrita en event.locals antes de que se ejecute está disponible en todo ese pipeline.

Esta es la forma canónica de middleware, y es donde pertenece la validación de sesión:

// 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)
}

Después de que este hook se ejecuta, cada función load del servidor, cada acción de formulario y cada manejador +server.ts en toda la aplicación puede leer event.locals.user para obtener el usuario validado sin hacer otra llamada a la API. La validación ocurre una vez por solicitud HTTP, al inicio del pipeline.

event.fetch está disponible en el hook handle y se comporta de la misma manera que el fetch provisto a las funciones load: resuelve URLs relativas contra el origen de la solicitud actual y reenvía cookies automáticamente. Siempre usa event.fetch para llamadas a la API dentro del hook en lugar del fetch global.

Un enfoque alternativo y a menudo preferible es llamar a tu lógica de validación de sesión directamente en lugar de hacerlo a través de HTTP, importando tu librería de autenticación o funciones de consulta a la base de datos de forma 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)
}

Las importaciones directas desde $lib/server/ están disponibles en los hooks, y son la elección correcta cuando tu lógica de autenticación ya está encapsulada en un módulo del servidor. El enfoque HTTP es útil cuando estás llamando a un proveedor de autenticación externo en lugar de tu propio almacén de sesiones.

Tipado de locals con App.Locals

El hook puebla event.locals y cada manejador del lado del servidor downstream lee de él — pero esas dos partes del contrato existen en archivos completamente separados. El hook escribe locals.user; una función load en una ruta completamente diferente lee locals.user. Sin una declaración de tipo que los conecte, TypeScript no tiene forma de verificar que ambos lados coincidan en lo que locals.user realmente es. La función load está leyendo efectivamente de un objeto sin tipo, y cualquier error tipográfico o desajuste de forma se convierte en un error en tiempo de ejecución en lugar de uno en tiempo de compilación.

SvelteKit resuelve esto con una única declaración ambient en src/app.d.ts. Declara la forma de App.Locals una vez, y TypeScript la aplica en todas partes: en el hook cuando escribes en event.locals, en cada función load, acción de formulario y manejador de API cuando lees de él. La declaración es el contrato, y el hook y los manejadores son las dos partes vinculadas por él.

El archivo de declaración `src/app.d.ts`

Como ya se mencionó, sin ninguna declaración de tipo, event.locals tiene el tipo de un objeto vacío {}. Leer event.locals.user inmediatamente te da un error de TypeScript: Property 'user' does not exist on type 'Locals'. Tendrías que hacer cast con as any en todas partes, perdiendo toda la seguridad de tipos.

SvelteKit resuelve esto con una característica de TypeScript llamada module augmentation. El archivo src/app.d.ts (generado cuando inicializas un proyecto SvelteKit) es un archivo especial de declaración ambient que te permite extender interfaces del paquete @sveltejs/kit sin modificarlo. El bloque declare global { namespace App { ... } } accede al namespace global App que define SvelteKit y fusiona tus propiedades en él. TypeScript lo detecta automáticamente en todo el codebase, sin necesidad de importaciones en ningún lado.

El export {} al final es obligatorio para hacer que el archivo sea un módulo en lugar de un script, lo cual es lo que habilita que la augmentación global funcione.

// src/app.d.ts

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

export {}

Dado que muchas páginas pueden ser accedidas sin una sesión, establecer user como null en el tipo unión contempla el caso no autenticado, que es un patrón común para los datos de sesión. Con esta declaración en su lugar, event.locals.user ahora está completamente tipado como { id: string; email: string; role: 'user' | 'admin' | 'superadmin' } | null en todo tu código del servidor.

Poblar locals en el hook handle

Con App.Locals declarado, el hook puede escribir en event.locals con total seguridad de tipos — TypeScript detectará formas incorrectas en tiempo de compilación. El beneficio real se hace visible a medida que tu aplicación crece y App.Locals se expande para contener múltiples piezas de datos con alcance de solicitud. Extiende app.d.ts primero, luego puebla los nuevos campos en el 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)
}

Cómo fluye el tipo

La declaración en app.d.ts es la única fuente de verdad. Una vez escrita, el tipo está disponible automáticamente en cada contexto donde SvelteKit proporciona un objeto event o locals — no necesitas importarlo ni redeclararlo en ningún lado.

Qué pertenece a locals

Locals debe contener datos que sean:

Con alcance de solicitud — creados de forma nueva por solicitud, no compartidos entre solicitudes
Necesarios por múltiples manejadores — si solo una función load lo usa, hazle fetch ahí en su lugar
Derivados de la solicitud misma — datos de sesión, identidad de tenant, IDs de solicitud, feature flags condicionados al usuario, preferencias de tema por usuario leídas de una cookie, asignaciones de bucket para pruebas A/B

No pongas payloads grandes en locals. Los locals se mantienen en memoria durante la duración de la solicitud. Un registro de usuario con unos pocos campos está bien; un megabyte de datos del dashboard o una lista de todos los productos no — eso pertenece a la función load que lo necesita.

La cadena completa de propagación de locals

El diagrama a continuación captura cómo locals fluye a través de la jerarquía completa del lado del servidor para una única solicitud. hooks.server.ts es siempre la autoridad originaria: se ejecuta primero y escribe en event.locals.

Desde allí, los locals están disponibles tanto para +layout.server.ts como para +page.server.ts directamente a través del objeto event. Adicionalmente, +layout.server.ts puede pasar datos hacia abajo a +page.server.ts mediante await parent(), lo que significa que un load de página puede recibir tanto los locals validados crudos como cualquier dato derivado o enriquecido que el layout retornó.

Lo que retornan los loads del servidor de página y layout se pasa a sus correspondientes funciones load universales y componentes Svelte a través de la prop data. Es importante destacar que locals en sí nunca forma parte de ese valor de retorno y nunca llega al navegador.

Hay dos cosas que vale la pena señalar sobre esta imagen. Primero, +page.server.ts tiene dos rutas por las que puede recibir datos de sesión: directamente desde event.locals (establecido por el hook) y mediante await parent() (datos que el load del servidor del layout eligió retornar).

Usar await parent() para datos de sesión es un patrón común, pero los artículos anteriores de esta serie establecieron que llamar a await parent() antes de iniciar tus propios fetches crea una cascada de serialización.

Cuando el load de página solo necesita el usuario de sesión que ya está en event.locals, leer locals.user directamente evita la llamada a parent por completo y elimina la cascada. await parent() vale la pena cuando genuinamente necesitas algo que el layout computó y retornó, no solo el valor crudo de locals.

Segundo, el nodo final — +layout.js | +page.js — representa el límite donde los datos del servidor cruzan hacia territorio del cliente. Lo que retornan los loads del servidor se convierte en la prop data en los componentes Svelte. event.locals en sí nunca está en ese valor de retorno; permanece completamente en memoria del servidor.

Leyendo locals en las funciones load

Cada campo poblado por el hook está disponible con su tipo correcto en cada función load del servidor en la aplicación:

// 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
	}
}

El objeto locals disponible en las funciones load es el mismo objeto poblado por el hook. No hay copia ni serialización entre ellos y comparten la misma referencia dentro de una única solicitud.

Locals en los manejadores de rutas de API

Los locals están disponibles en los manejadores de API +server.ts cuando desestructuras locals del parámetro event del manejador. El mismo tipo App.Locals se aplica automáticamente, igual que en las funciones 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 los manejadores de verbos HTTP como GET, POST, PATCH, PUT, DELETE, OPTIONS y HEAD reciben el mismo objeto event, por lo que locals es accesible en todos ellos. Esto importa para los endpoints de mutación: un manejador POST que aplica permisos lee el mismo locals.user establecido por el hook que un manejador GET.

Los locals no están disponibles en las funciones load universales

Este es un punto crítico que a menudo causa confusión. El objeto event.locals solo está disponible en código del lado del servidor. Las funciones load universales (+page.ts y +layout.ts) se ejecutan tanto en contextos de servidor como de cliente. locals es una construcción exclusiva del servidor y los loads universales se ejecutan en el navegador después de la hidratación, donde la memoria del servidor no es accesible.

Para pasar datos derivados de locals a una función load universal, el load del servidor debe retornarlos explícitamente, y el load universal los lee desde el 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 patrón de dos pasos es la única forma en que los valores de locals llegan al código universal. El load del servidor actúa como una puerta de enlace deliberada: tú eliges qué campos cruzan el límite servidor/cliente al incluirlos en el valor de retorno. Nada de event.locals cruza esa línea automáticamente.

El Hook handleFetch

Qué hace y cuándo usarlo

El hook handleFetch intercepta todas las llamadas fetch realizadas desde funciones load y handlers +server.ts durante el renderizado del lado del servidor. Recibe el objeto de solicitud, la función fetch para continuar la llamada y el objeto event (que le da acceso a event.locals). Puede inspeccionar y modificar la solicitud saliente antes de que se ejecute.

Usa handleFetch cuando tengas una preocupación transversal que aplique a todas o la mayoría de las llamadas fetch del lado del servidor — algo que de otro modo tendrías que copiar en cada función load. Los casos comunes son:

Reescritura de URL internas — redirigir URLs públicas a direcciones de servicio internas durante SSR para evitar viajes de red innecesarios
Headers de autenticación compartidos — inyectar una API key o token de servicio a servicio en solicitudes a una API downstream
Reenvío de cookies — pasar las cookies del navegador a una API interna durante SSR (no se hace automáticamente para solicitudes de origen cruzado)

No uses handleFetch para lógica que solo aplica a una o dos solicitudes específicas — eso corresponde a esas funciones load.

Una restricción importante: handleFetch solo se ejecuta en el servidor. Una vez que la página se hidrata en el navegador, las llamadas fetch del código del lado del cliente lo omiten por completo.

Caso de uso 1: Reescritura de URL internas

Cuando tu app está desplegada detrás de un balanceador de carga o en un entorno de contenedores, un fetch a https://your-app.com/api/products desde una función load del servidor realiza un viaje completo a través de la red, aunque el handler de la API viva en el mismo proceso. handleFetch puede reescribirlo a una dirección interna:

// 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: Inyectar headers de autenticación compartidos

Si todas tus funciones load del servidor llaman a un servicio downstream que requiere una API key, puedes agregar el header de forma centralizada en lugar de hacerlo en cada función load. El parámetro event te da acceso a event.locals para que puedas adjuntar la identidad del usuario junto con el secreto del servicio:

// 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: Reenviar cookies a APIs internas

Durante SSR, cuando una función load del servidor llama a un endpoint de API interno (otro +server.ts en la misma app), SvelteKit reenvía automáticamente las cookies del navegador. Pero para solicitudes de origen cruzado, como un subdominio o puerto diferente, las cookies no se reenvían automáticamente por las reglas SameSite nativas del fetch del navegador, aunque la solicitud se origine desde el servidor. Usa handleFetch para adjuntar la cookie de sesión explícitamente:

// 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)
}

Este patrón es particularmente común cuando tu app tiene un servicio de autenticación separado o un API gateway que necesita ver la misma cookie de sesión que envió el navegador.

El Hook handleError

Cuándo usar handleError

Usa handleError cuando necesites hacer alguna de las siguientes cosas:

Reportar a un servicio de monitoreo (Sentry, Datadog, etc.) sin repetir el código de reporte en cada función load
Sanitizar el mensaje de error mostrado al usuario — por defecto SvelteKit puede exponer texto de error interno
Adjuntar contexto de la solicitud (ID de usuario, ID de solicitud, URL) a los reportes de error, lo cual las funciones load individuales no pueden hacer sin duplicación
Diferenciar tipos de error para dar a los 404 un mensaje diferente al usuario que los 500

No uses handleError para flujo de control esperado. Si quieres retornar un 401 cuando un usuario no está autenticado, usa error(401, 'Unauthorised') dentro de la función load. handleError no se ejecutará para eso.

handleError es solo para excepciones genuinamente inesperadas.

Errores esperados vs inesperados

Esta distinción es el concepto más importante en handleError. SvelteKit tiene dos tipos de error:

Errores esperados — lanzados con error(status, message) desde @sveltejs/kit. Son flujo de control deliberado. SvelteKit los maneja directamente y no llama a handleError.
Errores inesperados — cualquier valor lanzado que no sea una instancia de error de SvelteKit: throw new Error('...'), un JSON.parse fallido, un timeout de base de datos, un rechazo de promesa no manejado. Son bugs genuinos o fallas de infraestructura. SvelteKit llama a handleError para estos.

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

Cómo SvelteKit llama a handleError

handleError recibe cuatro argumentos:

error — el valor lanzado (puede no ser una instancia de Error si alguien lanzó un objeto plano o un string)
event — el evento de solicitud completo, que te da acceso a event.locals, event.url y event.request
status — el código de estado HTTP que SvelteKit determinó (generalmente 500, pero podría ser 404 si la ruta no fue encontrada)
message — un string de mensaje corto predeterminado que SvelteKit derivó del estado

El valor de retorno de handleError se convierte en el objeto page.error que recibe +error.svelte. Por defecto, sin handleError, SvelteKit retorna { message } donde message es un string genérico y seguro. Puedes retornar cualquier forma que quieras, siempre que la declares.

Tipado del objeto error con App.PageError

Así como App.Locals tipifica event.locals, App.PageError tipifica el objeto que retorna handleError y que +error.svelte recibe a través de page.error. Agrégalo a 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 {}

Con PageError declarado, el valor de retorno de handleError es verificado por tipos, y page.error en +error.svelte está completamente 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
	}
}

Leer el error en +error.svelte

El objeto retornado por handleError está disponible como page.error en el componente +error.svelte más cercano. Con el tipo PageError declarado, page.error está completamente 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}

La contraparte del lado del cliente: hooks.client.ts

Todos los errores cubiertos anteriormente ocurren en el servidor, donde hooks.server.ts está en control. Pero una vez que la página se hidrata y el usuario navega en el navegador, los errores ocurren enteramente en código del lado del cliente. Estos incluyen fallos en el renderizado de componentes, rechazos de promesas no manejados en event handlers y errores de navegación del lado del cliente. Para esos, el hook del servidor nunca se invoca. SvelteKit proporciona hooks.client.ts con su propia exportación handleError exactamente para este caso.

La firma es casi idéntica, pero el argumento event no incluye propiedades exclusivas del servidor como cookies o locals. Úsalo para enviar errores del lado del cliente a tu rastreador de errores:

// 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'
	}
}

Una configuración completa de manejo de errores tiene tanto hooks.server.ts como hooks.client.ts exportando handleError, asegurando que ningún error (del servidor o del cliente) quede sin seguimiento silenciosamente.

Composición de Múltiples Hooks con sequence

El problema con una gran función handle

Cuando solo tienes validación de sesión que hacer, una sola función handle está bien. Pero las aplicaciones reales acumulan preocupaciones transversales: registro de solicitudes, limitación de tasa, headers de seguridad, carga de feature flags, resolución multi-tenant, manejo de CORS. Si sigues agregando todo esto a una función handle, se convierte en una pared de código imposible de mantener donde cada preocupación está entrelazada con todas las demás.

Podrías intentar dividir la lógica en funciones auxiliares llamadas desde un único handle, pero eso no es lo mismo que una composición verdadera. Cada preocupación no puede decidir independientemente interrumpir la solicitud, no puede envolver el ciclo de vida de la respuesta de forma independiente y no puede activarse o desactivarse limpiamente en diferentes entornos.

sequence resuelve esto permitiendo que cada preocupación viva en su propia función Handle enfocada, y luego conectándolas en una sola línea.

Cuándo usar sequence

Usa sequence en cuanto tengas más de una preocupación distinta en hooks.server.ts. Los candidatos comunes para hooks separados son:

Validación de sesión — siempre necesita ejecutarse primero para que los hooks posteriores y todas las funciones load puedan leer locals.user
Limitación de tasa — puede interrumpir la solicitud antes de que ocurra cualquier trabajo de autenticación, ahorrando recursos
Registro de solicitudes — envuelve todo para medir la duración total de la solicitud incluyendo todo el trabajo downstream
Headers de respuesta de seguridad — opera sobre la respuesta terminada, por lo que se ejecuta al final
Resolución multi-tenant — lee un subdominio o header para establecer locals.tenantId antes de la validación de sesión, ya que la validación de sesión puede depender del tenant
Manejo de preflight CORS — puede interrumpir solicitudes OPTIONS inmediatamente sin tocar la autenticación ni el enrutamiento
Hidratación de feature flags — carga los flags después de que el usuario es conocido, por lo que se ejecuta después de la validación de sesión

Mantener estos como funciones nombradas separadas también los hace individualmente testeables y reutilizables en diferentes archivos hooks.server.ts en un monorepo.

Cómo funciona sequence

sequence llama a cada hook en orden, pasando el evento y una función resolve que delega al siguiente hook en la cadena. El resultado es middleware anidado: el hook más externo comienza primero y termina último, razón por la cual un hook de registro colocado primero puede medir el tiempo total de la solicitud incluyendo todo el trabajo subsiguiente.

// 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 envuelve al siguiente como middleware anidado. El hook más externo (logging) comienza antes que todo y termina después de todo, razón por la cual puede medir la duración total de la solicitud. La operación más interna es el handler de ruta real.

sequence llama a cada hook en orden, pasando el evento y una función resolve que llama al siguiente hook en la cadena. El hook de logging ve el tiempo completo de la solicitud porque hace await de resolve(event), que ejecuta todos los hooks subsiguientes. El hook de seguridad modifica los headers de respuesta después de que la ruta ha sido procesada.

El orden importa

El orden en que pasas los hooks a sequence tiene consecuencias directas:

Sesión antes que cualquier cosa que lea locals.user — los hooks posteriores en la cadena y todas las funciones load dependen de que locals.user esté poblado
Limitación de tasa antes que la sesión — si una solicitud tiene límite de tasa puedes rechazarla antes de hacer cualquier trabajo de base de datos para autenticación
Logging más externo (primero) — necesita hacer await resolve(event) que ejecuta toda la cadena interna, dando una medición precisa del tiempo total
Headers de seguridad más externo-último (último) — estos operan sobre el objeto de respuesta final después de que el handler de ruta ha ejecutado

Un orden incorrecto produce bugs sutiles. Un hook de limitación de tasa colocado después del hook de sesión sigue validando la sesión para cada solicitud que debería haber sido bloqueada. Un hook de seguridad colocado antes del hook de sesión establece headers en una respuesta antes de que resolve haya ejecutado, y dado que los hooks mutan el mismo objeto de respuesta, los headers pueden ser sobreescritos.

Interrumpir la cadena

Un hook no tiene que llamar a resolve. Si retorna un Response directamente, el resto de la cadena — y el handler de ruta — nunca se ejecuta. Esta es la forma correcta de implementar limitación de tasa, respuestas de preflight CORS y bloqueo de IPs, porque quieres rechazar la solicitud antes de que se realice cualquier trabajo downstream.

// 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)

Cuando rateLimit retorna anticipadamente, logging aún termina porque envuelve la llamada a resolve(event). session y security nunca se ejecutan. Este es el resultado correcto: quieres registrar que la solicitud fue limitada por tasa, pero no quieres validar una sesión ni establecer headers de seguridad para una respuesta que es simplemente 429 Too Many Requests.

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

Compartir datos entre hooks mediante locals

Los hooks que aparecen antes en la cadena de sequence pueden establecer propiedades en event.locals que los hooks posteriores en la cadena leen. Este es esencialmente el mismo mecanismo que usan los hooks para compartir datos con las funciones de carga, pero aplicado dentro del propio pipeline de hooks.

Un ejemplo común es la resolución multi-tenant: el tenant se identifica a partir del subdominio antes de que se ejecute la validación de sesión, ya que la tabla de sesiones puede estar limitada al 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)

El hook tenant se ejecuta antes que session en la cadena, de modo que cuando session lee event.locals.tenantId este ya está establecido. Las funciones de carga posteriores pueden entonces leer tanto locals.tenantId como locals.user sin necesidad de saber cómo fueron poblados.

Dividir los hooks en archivos separados

Para aplicaciones más grandes, defina cada hook en su propio archivo e impórtelos en hooks.server.ts. Esto mantiene cada responsabilidad autocontenida y permite probarla de forma independiente.

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 convierte en una declaración de intención de una sola línea. Agregar o eliminar una responsabilidad implica un único cambio de importación.

Errores Comunes y Anti-Patrones

Establecer locals en +layout.server.ts en lugar del Hook

Dado que +layout.server.ts tiene acceso a event.locals, técnicamente es posible escribir en locals allí en lugar de hacerlo en el hook. Evite esto. SvelteKit ejecuta +layout.server.ts y +page.server.ts de forma simultánea para maximizar el paralelismo. Si la carga del layout establece locals.user y la carga de la página intenta leerlo, existe una condición de carrera: la carga de la página puede ejecutarse antes de que el layout haya terminado de escribir, leyendo un valor no 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)
}

El hook se ejecuta de forma secuencial antes que cualquier manejador de ruta, lo que significa que event.locals está completamente poblado antes de que +layout.server.ts o +page.server.ts comiencen. Esa es la garantía que hace que locals sea seguro de leer en cualquier parte del pipeline del lado del servidor.

Si se encuentra necesitando llamar a await parent() únicamente para acceder a datos de sesión que deberían haber estado en locals, eso es una señal clara de que los datos se están estableciendo en el lugar equivocado.

Lanzar un redirect dentro de handle

Es tentador realizar redirecciones de autenticación dentro del hook handle, ya que se ejecuta para cada solicitud. Esto es técnicamente posible pero generalmente incorrecto. Redirigir desde handle se aplica a todas las solicitudes, incluyendo solicitudes de recursos estáticos, solicitudes de prefetch internas de SvelteKit y llamadas a la API desde servicios externos. Una redirección amplia en handle puede romper cosas de maneras no evidentes.

// 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 }
}

El enfoque de guardia basado en layout es más quirúrgico. Protege exactamente las rutas del grupo de rutas (protected), deja las rutas públicas intactas y es fácil de entender leyendo el árbol de rutas.

Mutar event.locals después de resolve

Establecer propiedades en event.locals después de llamar a resolve(event) no tiene efecto en la solicitud actual porque las funciones de carga y los manejadores ya se han ejecutado en ese punto. Los locals deben poblarse 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)
}

Olvidar inicializar Locals a null

Si una función de carga lee event.locals.user sin que el hook siempre lo establezca, TypeScript se quejará de que la propiedad posiblemente no esté definida. Siempre inicialice cada propiedad de locals en el hook, aunque sea con null, para garantizar que la forma coincida con 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)
}

Consideraciones de Rendimiento y Escalabilidad

El hook handle se ejecuta en cada solicitud HTTP individual a su servidor SvelteKit. Cualquier operación asíncrona dentro de él agrega latencia a cada solicitud. La validación de sesión que realiza una consulta a la base de datos o una llamada a la API debe ser lo más rápida posible.

Para la validación de sesión, prefiera JWTs con ventanas de expiración cortas o tokens de sesión firmados que puedan validarse localmente sin un viaje de ida y vuelta a la base de datos. Si debe validar contra una base de datos o caché en cada solicitud, asegúrese de que la consulta esté indexada y considere un caché en memoria rápido como Redis para evitar consultar la base de datos en cada vista de página.

El hook handleFetch se ejecuta para cada llamada fetch realizada durante SSR y también puede agregar latencia. Manténgalo liviano. Reescribir URLs es rápido; realizar llamadas de red adicionales dentro de handleFetch multiplicaría la latencia.

El registro en handleError debe ser no bloqueante cuando sea posible. En plataformas edge como Cloudflare Workers, puede usar event.platform?.context?.waitUntil(promise) para diferir trabajo no crítico (como el envío a un rastreador de errores) hasta después de la respuesta. En adaptadores de Node.js esa API no está disponible, por lo que se prefiere escribir en una cola o usar un patrón de fire-and-forget en lugar de realizar una llamada HTTP sincrónica a su rastreador de errores dentro del camino crítico.

Conclusión

hooks.server.ts es el único punto de entrada por el que pasan todas las solicitudes del lado del servidor. El hook handle se ejecuta primero, antes de cualquier función de carga o acción de formulario, y es el lugar correcto para realizar la configuración con ámbito de solicitud: validación de sesión, trazado de solicitudes, carga de feature flags. Todo lo que se escriba en event.locals dentro del hook está disponible para cada función de carga, acción de formulario y manejador de API en la aplicación durante la duración de esa solicitud.

La declaración de tipo en src/app.d.ts conecta el hook con la función de carga: cualquier forma que declare para App.Locals es el tipo que event.locals tendrá en todo el código. Juntos, el hook y la declaración de tipo reemplazan lo que de otro modo sería código repetido de lectura de sesión disperso en docenas de funciones de carga.

handleFetch y handleError completan el ciclo de vida para las otras dos preocupaciones clave: modificación de solicitudes upstream y captura de errores inesperados. sequence le permite mantener cada preocupación en su propia función enfocada y componerlas sin anidamiento.

Puntos Clave

El hook handle en hooks.server.ts intercepta cada solicitud HTTP antes de que se ejecute cualquier manejador de ruta. Úselo para poblar event.locals con datos con ámbito de solicitud como el usuario de sesión validado.

Defina el tipo de App.Locals en src/app.d.ts para obtener seguridad completa de TypeScript en el hook y en cada función de carga del servidor que lea desde locals. Siempre inicialice cada propiedad con un valor base, típicamente null, dentro del hook.

handleFetch reescribe o enriquece las llamadas fetch del lado del servidor antes de que se ejecuten, útil para alias de URLs internas e inyección de cabeceras de autenticación compartidas. handleError se ejecuta ante excepciones inesperadas, el lugar correcto para reportar a servicios de monitoreo sin exponer detalles internos al cliente.

El helper sequence de @sveltejs/kit/hooks compone múltiples funciones Handle en una sola, ejecutándolas en orden. Divida los hooks por preocupación y compóngalos de forma limpia en lugar de escribir una función grande.

Qué sigue

Con locals poblado en el hook, cada función de carga del servidor en la aplicación tiene acceso al usuario validado sin ninguna lectura redundante de sesión. El siguiente artículo, Usar Datos del Padre en Funciones de Carga, cubre cómo las funciones de carga acceden a los datos devueltos por las cargas de layout ancestrales a través de la función parent(), la trampa de la cascada que genera esperarla demasiado pronto, y los patrones que preservan el paralelismo mientras aún fusionan los datos del padre y de la página.

Lecturas Adicionales

Documentación de Hooks de SvelteKit — referencia oficial para todos los tipos de hooks incluyendo handle, handleFetch, handleError y el helper sequence
App.Locals de SvelteKit — referencia oficial para tipar event.locals con la interfaz App.Locals en app.d.ts
Errores y Redirecciones en Funciones de Carga — cómo funcionan error() y redirect() en las funciones de carga, complementando el patrón de guardia basado en locals introducido aquí