La Oportunidad Antes de que la Página Renderice

Un usuario envía un formulario de inicio de sesión. El servidor crea una sesión, emite una cookie y lo redirige a su dashboard. En esa próxima solicitud, antes de que se ejecute una sola línea del componente del dashboard, tu aplicación tiene una oportunidad: leer la cookie, validar la sesión, resolver la identidad del usuario. Toda la página depende de hacer eso correctamente en la fracción de segundo entre que llega la solicitud y sale la respuesta.

Esa oportunidad vive dentro de una función de server load. Usarla correctamente implica entender tres cosas que están cerca entre sí pero se comportan de manera diferente: leer cookies con el objeto cookies, establecer cookies con cookies.set() en lugar de a través de un header de respuesta, y establecer otros headers de respuesta con setHeaders de una manera que tenga en cuenta cómo SSR y la navegación del cliente interactúan de forma diferente.

La mayoría de los tutoriales sobre este tema reducen las cookies a una sola línea: cookies.get('session'). Eso te da un punto de partida, pero omite el razonamiento que determina cuándo leer una cookie es el enfoque correcto, por qué establecer una cookie requiere una API completamente diferente, cómo las reglas de reenvío de cookies interactúan con despliegues multi-dominio, y qué hace realmente setHeaders durante una solicitud renderizada en el servidor versus una navegación del cliente.

Este artículo trabaja todo eso. Al final tendrás un modelo mental preciso de cómo se comportan el objeto cookies y la función setHeaders en las funciones de server load, por qué funcionan de la manera en que lo hacen, y cómo aplicarlos a un patrón práctico de carga de sesión que sirve como base para la autenticación en la mayoría de las aplicaciones SvelteKit.

Una convención continúa del resto de esta serie: sin ORMs, sin abstracciones de cliente de base de datos. Cada acceso a datos en los ejemplos usa llamadas fetch simples a endpoints de API. Esto mantiene los ejemplos enfocados en el comportamiento de SvelteKit que se explica en lugar de en cualquier capa de datos particular.

Cuatro Preocupaciones, Una Solicitud

Considera una aplicación SvelteKit autenticada típica. Cuando un usuario inicia sesión, el servidor crea un registro de sesión y envía el identificador de sesión de vuelta al navegador como una cookie HTTP. Cada solicitud posterior de ese navegador lleva la cookie. El servidor la lee, busca la sesión y sabe quién es el usuario.

En SvelteKit, las funciones de server load son donde ocurre esta búsqueda. El +layout.server.ts en la raíz de la aplicación lee la cookie de sesión, la resuelve a una identidad de usuario y devuelve esa identidad a cada página de la aplicación. Cada +page.server.ts que necesita autenticación puede entonces leer el usuario resuelto de los datos del layout padre en lugar de volver a leer la cookie por sí mismos.

El patrón suena sencillo, pero implica cuatro preocupaciones distintas que cada una necesita un manejo cuidadoso:

Leer cookies correctamente significa entender el objeto cookies en el evento de load, qué cookies son accesibles desde qué rutas, y qué sucede cuando una cookie está ausente.

Reenviar credenciales desde las funciones de server load a endpoints de API internos implica el event.fetch de SvelteKit, que automáticamente lleva cookies a solicitudes del mismo origen. Las reglas que gobiernan qué cookies se reenvían y a qué orígenes importan para aplicaciones que abarcan múltiples dominios o subdominios.

Establecer cookies en respuesta a un server load requiere cookies.set(), no un header de respuesta. Hay una razón específica para esta restricción, y entenderla previene una clase sutil de bugs.

Establecer headers de respuesta con setHeaders controla cómo el navegador y cualquier caché intermediario tratan la respuesta. Tiene un efecto significativo durante SSR y un efecto diferente y más limitado durante la navegación del lado del cliente. Conocer la diferencia es lo que hace que setHeaders sea útil en lugar de confuso.

El Objeto cookies vs setHeaders

Las funciones de server load reciben un objeto de evento de load. La propiedad cookies en ese objeto no es un parser de header HTTP sin procesar. Es una API estructurada que SvelteKit construye a partir del header de solicitud Cookie entrante y mantiene a lo largo de la vida útil de la solicitud.

Cuando llamas a cookies.get('session'), SvelteKit analiza la cadena de cookie, encuentra la cookie nombrada y devuelve su valor. Cuando llamas a cookies.set('session', value, options), SvelteKit encola un header de respuesta Set-Cookie y también actualiza su estado interno de cookies para que las lecturas posteriores dentro de la misma solicitud reflejen el nuevo valor. Cuando llamas a cookies.delete('session'), encola un header que expira la cookie inmediatamente y la elimina del estado interno.

Este modelo con estado es intencional. Una sola solicitud podría implicar leer una cookie de sesión, determinar que ha expirado, eliminar la cookie antigua y establecer una nueva actualizada. El objeto cookies mantiene la consistencia a través de todas esas operaciones sin que tengas que rastrear el estado interno manualmente.

La función setHeaders es una herramienta separada con un propósito más limitado. Establece headers de respuesta distintos de Set-Cookie para la solicitud actual. Afecta la respuesta HTTP que recibe el navegador o el caché, no los datos que fluyen hacia el componente de página.

Implementación

Paso 1: Leer Cookies en una Función de Server Load

El objeto cookies está disponible en el evento de load en +page.server.ts y +layout.server.ts. No está disponible en las funciones de load universales (+page.ts, +layout.ts) porque esas pueden ejecutarse en el navegador, donde el acceso directo a cookies está gobernado por la API document.cookie de JavaScript en lugar de los headers HTTP.

El uso más importante de cookies.get() en una aplicación típica es leer el identificador de sesión en el server load del layout raíz. Este es el lugar natural para ello porque el layout raíz envuelve cada página. Cualquier identidad de usuario resuelta aquí fluye hacia cada página en la jerarquía de rutas a través de la fusión de datos de SvelteKit.

// src/routes/+layout.server.ts

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

export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	const sessionId = cookies.get('session_id')

	// If no session cookie exists, the user is not logged in.
	// Return a null user. Pages that require authentication will
	// redirect from their own load functions when they see null here.
	if (!sessionId) {
		return { user: null }
	}

	// Validate the session against the API. event.fetch automatically
	// forwards the original request's cookies to same-origin calls,
	// but here we are being explicit by passing the session ID in a
	// header, which works reliably regardless of cookie forwarding rules.
	const response = await fetch('/api/session/validate', {
		headers: {
			'X-Session-Id': sessionId
		}
	})

	if (!response.ok) {
		// Session invalid or expired. Return null so pages can react.
		return { user: null }
	}

	const user = await response.json()
	return { user }
}

// src/routes/api/session/validate/+server.ts

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

interface UserRecord {
	id: string
	email: string
	displayName: string
	role: 'admin' | 'editor' | 'viewer'
	avatarUrl: string | null
}

// In a real application this handler queries whatever session store
// your application uses: Redis, a database table, JWT verification.
// The load function does not care. It calls fetch and reads the result.
export const GET: RequestHandler = async ({ request }) => {
	const sessionId = request.headers.get('X-Session-Id')

	if (!sessionId) {
		error(400, 'Session ID header missing')
	}

	// Simulated session lookup. Replace this with your actual session store.
	if (sessionId !== 'valid-session-token-example') {
		error(401, 'Session not found or expired')
	}

	const user: UserRecord = {
		id: 'user-1',
		email: 'alex@example.com',
		displayName: 'Alex Kim',
		role: 'editor',
		avatarUrl: '/avatars/user-1.jpg'
	}

	return json(user)
}

El valor user devuelto desde el load del layout queda disponible para cada página a través de la prop data. Las páginas que requieren autenticación inspeccionan data.user y redirigen cuando es null.

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

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

export const load: PageServerLoad = async ({ parent }) => {
	// Calling parent() gives this load function access to the layout
	// data without re-reading the cookie or re-validating the session.
	const { user } = await parent()

	if (!user) {
		// Redirect to the login page. The 303 status is correct for
		// a redirect after a GET request in SvelteKit's redirect helper.
		redirect(303, '/login')
	}

	// Fetch dashboard-specific data now that we know who the user is.
	// The user ID is known from the session, not from the URL.
	// This prevents users from accessing other users' dashboards
	// by changing a route parameter.
	const response = await fetch(`/api/users/${user.id}/dashboard`)

	if (!response.ok) {
		return { stats: null, recentActivity: [] }
	}

	const dashboardData = await response.json()
	return { stats: dashboardData.stats, recentActivity: dashboardData.recentActivity }
}

Llamar a parent() es como un page server load accede a los datos resueltos del layout server load. Esta es la clave del patrón de lectura única: el layout raíz lee la cookie una vez por solicitud, resuelve la sesión una vez, y cada función de load hijo hereda ese resultado.

Paso 2: Reglas de Reenvío de Cookies

Cuando una función de server load llama a event.fetch con una URL del mismo origen, SvelteKit reenvía las cookies de la solicitud entrante original a esa llamada fetch. Este es el Superpoder Dos del artículo anterior. Pero mismo origen significa exactamente lo que dice: el mismo esquema, host y puerto.

Considera una aplicación desplegada en app.example.com que tiene un servidor de API en api.example.com. Estos son orígenes diferentes aunque comparten un dominio raíz. Las cookies establecidas con Domain=example.com son enviadas por el navegador a ambos, pero el event.fetch de SvelteKit solo reenvía cookies automáticamente a solicitudes que coincidan exactamente con el origen de la solicitud entrante.

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

import type { PageServerLoad } from './$types'
import { INTERNAL_API_SECRET } from '$env/static/private'

export const load: PageServerLoad = async ({ cookies, fetch }) => {
	// Same-origin fetch to /api/reports. Cookies forwarded automatically.
	// No special handling needed.
	const internalResponse = await fetch('/api/reports/summary')

	// Cross-origin fetch to api.example.com. No automatic cookie forwarding.
	// The session cookie value is read explicitly and forwarded as a header.
	const sessionId = cookies.get('session_id')

	const externalResponse = await fetch('https://api.example.com/reports/detailed', {
		headers: {
			// Using a custom header is more explicit and intentional than
			// forwarding the cookie string directly in a Cookie header.
			// The API on api.example.com is configured to read this header.
			'X-Session-Id': sessionId ?? '',
			// Internal service-to-service authentication, separate from
			// the user session. Never expose this to the browser.
			Authorization: `Bearer ${INTERNAL_API_SECRET}`
		}
	})

	if (!internalResponse.ok || !externalResponse.ok) {
		return { summary: null, detailed: null }
	}

	const [summary, detailed] = await Promise.all([internalResponse.json(), externalResponse.json()])

	return { summary, detailed }
}

La regla a aplicar consistentemente: para rutas internas del mismo origen, confía en el reenvío automático. Para solicitudes de origen cruzado, reenvía las credenciales de forma explícita y deliberada. Esto obliga a que el flujo de datos sea visible en el código en lugar de estar implícito.

La función setHeaders acepta un objeto de headers de respuesta. Se usa para cosas como Cache-Control, Vary, X-Frame-Options, y cualquier header personalizado que tu aplicación necesite enviar. Pero explícitamente no acepta Set-Cookie.

Intentar establecer una cookie a través de setHeaders lanzará un error en tiempo de ejecución:

// Wrong: SvelteKit throws an error if you attempt this.
export const load: PageServerLoad = async ({ setHeaders }) => {
	setHeaders({
		// This throws: "Use the 'cookies.set()' API instead"
		'set-cookie': 'session=abc; Path=/; HttpOnly'
	})
	return {}
}

La razón de esta restricción no es arbitraria. Establecer cookies a través de cadenas de header sin procesar significa omitir el rastreo del estado interno de cookies de SvelteKit. Si el load del layout establece una cookie y el load de página la lee, SvelteKit necesita saber cuál es el valor actual de la cookie en cada punto del ciclo de vida de la solicitud. Eso solo es posible si todas las mutaciones de cookies pasan por el objeto cookies.

También hay una consideración de seguridad. Los atributos de cookie como HttpOnly, Secure, SameSite y Path existen para proteger las cookies de ser leídas por JavaScript, enviadas a través de conexiones inseguras o accedidas desde rutas inesperadas. La API cookies.set() aplica una configuración predeterminada que toma decisiones seguras a menos que explícitamente optes por no hacerlo. El enfoque de cadena sin procesar requiere que recuerdes cada atributo cada vez.

// src/routes/+layout.server.ts
// Demonstrating a session refresh pattern.

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

export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	const sessionId = cookies.get('session_id')

	if (!sessionId) {
		return { user: null }
	}

	const response = await fetch('/api/session/validate', {
		headers: { 'X-Session-Id': sessionId }
	})

	if (!response.ok) {
		// Session is invalid. Delete the stale cookie so the browser
		// stops sending it on future requests.
		cookies.delete('session_id', { path: '/' })
		return { user: null }
	}

	const { user, refreshedSessionId } = await response.json()

	// If the API issued a new session ID (rolling session pattern),
	// update the cookie with the refreshed value.
	if (refreshedSessionId && refreshedSessionId !== sessionId) {
		cookies.set('session_id', refreshedSessionId, {
			// HttpOnly prevents JavaScript from reading the cookie value.
			// This is critical: session tokens should never be accessible
			// to client-side code because that exposes them to XSS attacks.
			httpOnly: true,

			// Secure ensures the cookie is only sent over HTTPS.
			// In development this can be false, but always true in production.
			secure: true,

			// Strict prevents the cookie from being sent on cross-site requests.
			// This protects against CSRF for most common attack vectors.
			sameSite: 'strict',

			// The path controls which routes the cookie is sent with.
			// '/' means all routes on this domain receive the cookie.
			path: '/',

			// maxAge sets the cookie lifetime in seconds.
			// 7 days expressed in seconds.
			maxAge: 60 * 60 * 24 * 7
		})
	}

	return { user }
}

La API cookies.set() requiere que especifiques path explícitamente. Esto es intencional. Sin un path, el comportamiento de la cookie se define relativo a la URL que estableció la cookie, lo que produce un comportamiento sorpresivo cuando una cookie se establece profundamente en la jerarquía de rutas pero se espera que sea legible en todas partes. Siempre pasa path: '/' a menos que tengas una razón específica para restringir la cookie a un subárbol.

Paso 4: Establecer Headers de Respuesta con setHeaders

La función setHeaders es para cada header de respuesta que no sea Set-Cookie. Su uso más común en las funciones de load es el control de caché, que comunica al navegador y a cualquier CDN o proxy inverso que esté frente a tu aplicación cuánto tiempo se puede reutilizar una respuesta.

// src/routes/articles/[slug]/+page.server.ts

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

export const load: PageServerLoad = async ({ params, setHeaders, fetch }) => {
	const response = await fetch(`/api/articles/${params.slug}`)

	if (!response.ok) {
		error(404, 'Article not found')
	}

	const article = await response.json()

	// This page's content changes rarely. Tell the browser and any CDN
	// that the response can be cached for one hour.
	// 'public' means intermediate caches (CDNs, proxies) can also store it.
	// 'max-age' is the lifetime in seconds: 3600 = one hour.
	// 's-maxage' overrides max-age for shared caches like CDNs.
	setHeaders({
		'cache-control': 'public, max-age=3600, s-maxage=86400'
	})

	return { article }
}

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

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

export const load: PageServerLoad = async ({ parent, setHeaders, fetch }) => {
	const { user } = await parent()

	if (!user) {
		redirect(303, '/login')
	}

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

	// Dashboard content is user-specific and must not be cached by
	// shared caches. 'private' restricts caching to the browser only.
	// 'no-store' prevents even the browser from caching it.
	// Use this for any page containing sensitive user data.
	setHeaders({
		'cache-control': 'private, no-store'
	})

	return dashboardData
}

La elección entre public y private no se trata de control de acceso en el sentido de SvelteKit. Es una instrucción de caché. Una respuesta public le dice a los intermediarios que pueden almacenarla en caché y servirla a cualquier usuario. Una respuesta private les dice que la mantengan solo para el navegador individual que la solicitó. Si una página contiene datos específicos del usuario, debe ser private.

Paso 5: Qué Hace setHeaders Durante SSR vs Navegación del Cliente

Esta es la parte de setHeaders que sorprende a los desarrolladores. Su efecto es asimétrico dependiendo de cuándo se ejecuta la función de load.

Durante una solicitud SSR, setHeaders establece headers en la respuesta HTTP real enviada al navegador. Un header Cache-Control: public, max-age=3600 significa que el navegador y cualquier CDN entre el usuario y el servidor almacenarán en caché el HTML renderizado. La próxima vez que se solicite la misma URL, puede servirse desde el caché sin que el servidor ejecute ninguna función de load en absoluto.

Durante una navegación del lado del cliente (cuando el usuario hace clic en un enlace en una aplicación SvelteKit en ejecución), no hay respuesta HTTP. El navegador ya está ejecutando JavaScript y SvelteKit maneja la navegación internamente. La función de load se ejecuta en el navegador, obtiene datos y actualiza la página. setHeaders se llama en este contexto, pero no tiene una respuesta HTTP a la que adjuntar headers. SvelteKit ignora la llamada silenciosamente. Los headers de control de caché que estableces no tienen efecto en las navegaciones del cliente.

La implicación práctica es que los headers de control de caché establecidos en las funciones de load se aplican al renderizado de página completa en la primera visita. No afectan cómo SvelteKit gestiona las navegaciones posteriores del lado del cliente a la misma ruta. Esas navegaciones usan el propio modelo de navegación e invalidación de SvelteKit, que es independiente del caché HTTP.

Esto también significa que no puedes usar setHeaders en una función de load universal (+page.ts) con la expectativa de que controlará el caché del navegador en todas las navegaciones. Un load universal se ejecuta tanto en el servidor como en el navegador, pero setHeaders solo hace algo en el lado del servidor. Si necesitas comportamiento de caché para la carga inicial de la página, setHeaders es la herramienta correcta. Si necesitas controlar cuándo SvelteKit vuelve a ejecutar una función de load después del renderizado inicial, eso se maneja con invalidate y depends, que es un mecanismo diferente cubierto en un artículo posterior de esta serie.

Ejemplo Práctico: Cargar una Sesión de Usuario

El siguiente es un ejemplo completo e integrado que reúne todos los conceptos: un layout raíz que lee una cookie de sesión, la valida, opcionalmente la actualiza, establece headers de control de caché apropiados y hace que el usuario resuelto esté disponible para cada página.

Los tipos de sesión

// src/lib/types/session.ts

export interface SessionUser {
	id: string
	email: string
	displayName: string
	role: 'admin' | 'editor' | 'viewer'
	avatarUrl: string | null
}

export interface SessionValidationResult {
	user: SessionUser
	// The API may issue a new session ID when it extends a session.
	// If null, the existing session ID is still valid and unchanged.
	refreshedSessionId: string | null
}

El server load del layout raíz

// src/routes/+layout.server.ts

import type { LayoutServerLoad } from './$types'
import type { SessionValidationResult } from '$lib/types/session'

const SESSION_COOKIE = 'sid'

export const load: LayoutServerLoad = async ({ cookies, url, setHeaders, fetch }) => {
	const sessionId = cookies.get(SESSION_COOKIE)

	// No session cookie present. User is not authenticated.
	// Return null without making any network requests.
	if (!sessionId) {
		return { user: null }
	}

	const response = await fetch('/api/session/validate', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({ sessionId })
	})

	// Invalid or expired session. Remove the stale cookie to prevent
	// it from being sent on every subsequent request unnecessarily.
	if (!response.ok) {
		cookies.delete(SESSION_COOKIE, { path: '/' })
		return { user: null }
	}

	const result: SessionValidationResult = await response.json()

	// Rolling session: if the server issued a new session ID, replace
	// the old one. This extends the session lifetime on active use.
	if (result.refreshedSessionId) {
		cookies.set(SESSION_COOKIE, result.refreshedSessionId, {
			httpOnly: true,
			secure: true,
			sameSite: 'strict',
			path: '/',
			maxAge: 60 * 60 * 24 * 7
		})
	}

	// The layout response itself is not publicly cacheable because it
	// varies by user session. The SSR output for this request contains
	// user-specific data embedded in the page.
	setHeaders({
		'cache-control': 'private, no-cache'
	})

	return { user: result.user }
}

La ruta de API de validación de sesión

// src/routes/api/session/validate/+server.ts

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

interface ValidateRequestBody {
	sessionId: string
}

// A real session store. Here simulated with a static map.
// In production, this would query Redis, a database table, or verify a JWT.
const SESSION_STORE = new Map<string, { user: SessionUser; createdAt: number }>([
	[
		'valid-session-token-example',
		{
			user: {
				id: 'user-1',
				email: 'alex@example.com',
				displayName: 'Alex Kim',
				role: 'editor',
				avatarUrl: '/avatars/user-1.jpg'
			},
			createdAt: Date.now()
		}
	]
])

const SESSION_LIFETIME_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
const SESSION_REFRESH_THRESHOLD_MS = 24 * 60 * 60 * 1000 // refresh if less than 1 day left

export const POST: RequestHandler = async ({ request }) => {
	let body: ValidateRequestBody

	try {
		body = await request.json()
	} catch {
		error(400, 'Invalid request body')
	}

	const record = SESSION_STORE.get(body.sessionId)

	if (!record) {
		error(401, 'Session not found')
	}

	const age = Date.now() - record.createdAt

	if (age > SESSION_LIFETIME_MS) {
		SESSION_STORE.delete(body.sessionId)
		error(401, 'Session expired')
	}

	// Issue a new session ID if the session is approaching expiry.
	let refreshedSessionId: string | null = null

	if (age > SESSION_LIFETIME_MS - SESSION_REFRESH_THRESHOLD_MS) {
		refreshedSessionId = crypto.randomUUID()
		SESSION_STORE.set(refreshedSessionId, {
			user: record.user,
			createdAt: Date.now()
		})
		SESSION_STORE.delete(body.sessionId)
	}

	const result: SessionValidationResult = {
		user: record.user,
		refreshedSessionId
	}

	return json(result)
}

El load de página protegida

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

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

export const load: PageServerLoad = async ({ parent, setHeaders, fetch }) => {
	// parent() reads the already-resolved layout data.
	// This does not re-validate the session. The cookie was read once
	// by the layout and the result is reused here.
	const { user } = await parent()

	if (!user) {
		redirect(303, '/login?returnTo=/account')
	}

	const response = await fetch(`/api/users/${user.id}/account`)

	if (!response.ok) {
		error(500, 'Failed to load account data')
	}

	const account = await response.json()

	// Account data is personal. Prevent all caching.
	setHeaders({
		'cache-control': 'private, no-store'
	})

	return { account }
}

El componente del layout raíz

<!-- src/routes/+layout.svelte -->

<script lang="ts">
	import type { LayoutData } from './$types'

	let { data, children }: { data: LayoutData; children: import('svelte').Snippet } = $props()

	// data.user is null when not logged in, or a SessionUser when authenticated.
	// $derived makes the boolean reactive so the nav updates if the user
	// state changes within the same page session (e.g., after login).
	const isAuthenticated = $derived(data.user !== null)
</script>

<header>
	<nav>
		<a href="/">Home</a>
		<a href="/articles">Articles</a>

		{#if isAuthenticated}
			<a href="/account">{data.user?.displayName}</a>
			<form method="POST" action="/api/auth/logout">
				<button type="submit">Log out</button>
			</form>
		{:else}
			<a href="/login">Log in</a>
		{/if}
	</nav>
</header>

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

El componente usa $derived para calcular isAuthenticated a partir del valor data.user. Esto mantiene la reactividad limpia: si los datos del usuario alguna vez cambian en la misma sesión de aplicación (por ejemplo, después de que una acción de inicio o cierre de sesión del lado del cliente active invalidate), el valor derivado se actualiza y la navegación refleja el nuevo estado sin ninguna actualización imperativa explícita.

Errores Comunes y Anti-Patrones

Leyendo cookies en una función de carga universal

// Wrong: cookies is not available in +page.ts
// This file can run in the browser where the cookies object does not exist.
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ cookies }) => {
	// TypeScript will catch this: 'cookies' does not exist on PageLoadEvent.
	// But even if it did, the browser has no equivalent API here.
	const sessionId = cookies.get('session_id')
	return {}
}

// Correct: use +page.server.ts for any cookie access.
// The .server suffix guarantees the file never runs in the browser.
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ cookies }) => {
	const sessionId = cookies.get('session_id')
	return {}
}

TypeScript detectará este error en tiempo de compilación porque el tipo del evento de carga en +page.ts no incluye una propiedad cookies. Pero la razón que hay que entender es que las funciones de carga universales están diseñadas para ejecutarse tanto en el servidor como en el cliente, y no existe una API de cookies unificada que funcione de manera idéntica en ambos entornos.

Intentar establecer cookies con setHeaders

// Wrong: setHeaders does not accept Set-Cookie.
// SvelteKit throws a runtime error.
export const load: PageServerLoad = async ({ setHeaders }) => {
	setHeaders({
		'set-cookie': 'session_id=abc; HttpOnly; Secure; SameSite=Strict; Path=/'
	})
	return {}
}

// Correct: all cookie mutations go through cookies.set().
export const load: PageServerLoad = async ({ cookies }) => {
	cookies.set('session_id', 'abc', {
		httpOnly: true,
		secure: true,
		sameSite: 'strict',
		path: '/'
	})
	return {}
}

Más allá del error en tiempo de ejecución, el enfoque de usar una cadena de encabezado sin procesar omite el seguimiento interno del estado de cookies de SvelteKit. Cualquier llamada posterior a cookies.get('session_id') dentro del mismo ciclo de vida de la solicitud no vería el nuevo valor porque el objeto cookies nunca fue notificado del cambio.

Establecer encabezados conflictivos entre las funciones de carga de layout y página

// src/routes/+layout.server.ts
export const load: LayoutServerLoad = async ({ setHeaders }) => {
	// Layout sets one cache directive.
	setHeaders({ 'cache-control': 'public, max-age=3600' })
	return {}
}

// src/routes/blog/[slug]/+page.server.ts
export const load: PageServerLoad = async ({ setHeaders }) => {
	// Page tries to set a different cache directive.
	// SvelteKit throws: "conflicting values for header 'cache-control'"
	setHeaders({ 'cache-control': 'private, no-store' })
	return {}
}

Cuando las funciones de carga de layout y página se ejecutan para la misma solicitud, SvelteKit combina sus llamadas a setHeaders. Si ambas intentan establecer el mismo encabezado con valores diferentes, SvelteKit lanza un error. La solución es establecer cache-control solo en la función de carga más específica para una ruta determinada: la carga del servidor de la página. El layout no debería establecer encabezados de caché si las páginas individuales necesitan controlarlos de forma independiente.

// Correct: only the page load sets cache-control.
// The layout does not touch it.
export const load: PageServerLoad = async ({ setHeaders, parent }) => {
	const { user } = await parent()
	setHeaders({
		'cache-control': user ? 'private, no-store' : 'public, max-age=300'
	})
	return {}
}

// Wrong: cookies.delete requires a path option.
// Without it, SvelteKit throws an error.
export const load: PageServerLoad = async ({ cookies }) => {
	cookies.delete('session_id')
	return { user: null }
}

// Correct: always provide path when calling cookies.delete().
// The path must match the path used when the cookie was set.
export const load: PageServerLoad = async ({ cookies }) => {
	cookies.delete('session_id', { path: '/' })
	return { user: null }
}

La opción path es requerida por la API de SvelteKit para evitar ambigüedades. Una cookie establecida con Path=/ y una cookie establecida con Path=/admin son cookies distintas aunque compartan el mismo nombre. Especificar el path de forma explícita garantiza que estás eliminando la correcta.

Consideraciones de rendimiento y escalabilidad

La carga del servidor del layout raíz se ejecuta en cada solicitud renderizada en el servidor. En una aplicación autenticada, eso significa que la solicitud de validación de sesión se ejecuta en cada primera visita a cada página. Mantener este camino rápido es una de las optimizaciones de mayor impacto disponibles.

La ruta de validación de sesión debe ser lo más liviana posible. Una búsqueda por ID de sesión en un almacén en memoria como Redis es una operación de menos de un milisegundo. Una consulta a base de datos sin índice puede tomar decenas de milisegundos. La diferencia es insignificante por sí sola, pero se acumula a lo largo de miles de usuarios concurrentes y se convierte en el factor limitante en el rendimiento de tu servidor.

Para aplicaciones donde la mayoría de las páginas son de acceso público, la verificación condicional al inicio de la carga del layout es importante:

export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	const sessionId = cookies.get('session_id')

	// Exit immediately if there is no session to validate.
	// Unauthenticated users pay zero API cost on the layout load.
	if (!sessionId) {
		return { user: null }
	}

	// Only users with a session cookie reach this fetch call.
	const response = await fetch('/api/session/validate', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({ sessionId })
	})

	// ...rest of validation
}

Para páginas que pueden almacenarse en caché públicamente, setHeaders con directivas Cache-Control y Vary apropiadas permite que los CDN sirvan la página sin llegar a tu servidor de origen en absoluto. Una página de artículo de blog, una página de documentación o una página de destino de marketing puede almacenarse en caché en el edge con un TTL razonable, y la función de carga del origen se ejecuta una vez por entrada de caché en lugar de una vez por visita de usuario.

// src/routes/docs/[...path]/+page.server.ts

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

export const load: PageServerLoad = async ({ params, setHeaders, fetch }) => {
	const path = params.path.join('/')
	const response = await fetch(`/api/docs?path=${encodeURIComponent(path)}`)

	if (!response.ok) {
		error(404, 'Documentation page not found')
	}

	const doc = await response.json()

	// Documentation pages are public and change infrequently.
	// CDNs can cache them for one hour (s-maxage).
	// Browsers revalidate after five minutes (max-age).
	// The Vary header tells caches that the response depends on
	// Accept-Encoding (for compression), which is standard practice.
	setHeaders({
		'cache-control': 'public, max-age=300, s-maxage=3600',
		vary: 'Accept-Encoding'
	})

	return { doc }
}

Cuándo NO usar este patrón

El patrón de sesión en el layout raíz descrito en este artículo es el enfoque correcto para aplicaciones donde la mayoría o todas las páginas comparten un concepto del usuario actual. Pero no todas las aplicaciones tienen esa estructura.

Sitios puramente públicos sin ningún tipo de autenticación no tienen uso para cookies de sesión en funciones de carga. Si tu blog, sitio de documentación o sitio de marketing no tiene inicio de sesión, no hay nada que leer ni cookies que gestionar.

Backends solo de API construidos exclusivamente con rutas +server.ts de SvelteKit no utilizan funciones de carga de página en absoluto. El manejo de cookies para esas rutas se realiza directamente en el manejador de solicitudes, no a través de las APIs de funciones de carga.

Layouts demasiado específicos para lecturas de sesión pueden crear un acoplamiento innecesario. Si tienes una sección autenticada de tu sitio en /app y una sección pública en / y las dos nunca comparten un layout autenticado común, leer la sesión en el layout raíz fuerza una lectura de cookie en cada página, incluidas las páginas puramente públicas donde la autenticación es irrelevante. En ese caso, un layout dedicado en src/routes/app/+layout.server.ts es más apropiado que colocar la lógica de sesión en la raíz.

Páginas de polling frecuente o en tiempo real no deben depender de funciones de carga para la actualización de datos. Las funciones de carga se ejecutan en la navegación, no en un temporizador. Si una página necesita datos que se actualizan cada pocos segundos, el componente gestiona la actualización con un $effect que establece un intervalo de polling o una conexión WebSocket. La función de carga proporciona la instantánea inicial y el componente la mantiene actualizada.

Conclusión

Las cookies y los encabezados de respuesta en las funciones de carga del servidor no son complicados, pero tienen reglas que importan. Las cookies pertenecen exclusivamente a +page.server.ts y +layout.server.ts porque esos son los únicos contextos que tienen garantía de ejecutarse en el servidor. El objeto cookies tiene estado dentro de una solicitud, y todas las mutaciones de cookies deben pasar por él porque SvelteKit rastrea ese estado internamente. Establecer una cookie a través de setHeaders omite ese seguimiento y lanza un error por diseño.

La función setHeaders establece encabezados de respuesta HTTP para la respuesta SSR. Los encabezados Cache-Control establecidos allí instruyen a los navegadores y CDN sobre cómo almacenar en caché la página renderizada. Durante las navegaciones del lado del cliente, esos encabezados no tienen efecto porque no hay una respuesta HTTP a la que adjuntarlos.

El patrón de sesión en el layout raíz —leer la cookie de sesión una vez y poner el usuario resuelto a disposición de todas las páginas a través de la combinación de datos de SvelteKit— es la base arquitectónica correcta para la autenticación. Mantiene las lecturas de cookies en un solo lugar, evita la validación redundante y hace que la identidad del usuario esté disponible sin necesidad de pasar props a través de cada layout y página en la jerarquía.

Puntos clave

Puntos clave:

Las cookies son accesibles solo en +page.server.ts y +layout.server.ts. Las funciones de carga universales no pueden acceder a ellas.
Todas las mutaciones de cookies, incluyendo establecer y eliminar, deben pasar por el objeto cookies. Usar setHeaders para Set-Cookie lanza un error en tiempo de ejecución.
cookies.set() requiere una opción path explícita. Usa siempre path: '/' a menos que tengas una razón para restringir la cookie a un subárbol.
El event.fetch de SvelteKit reenvía las cookies automáticamente a las solicitudes del mismo origen. Las solicitudes de origen cruzado requieren el reenvío explícito de credenciales.
setHeaders establece encabezados de respuesta HTTP para la respuesta SSR. No tiene efecto durante las navegaciones del lado del cliente.
Usa Cache-Control: private, no-store para páginas que contienen datos específicos del usuario y public, max-age=N para páginas que pueden almacenarse en caché públicamente.
Establecer el mismo encabezado tanto en la carga del servidor del layout como en la de la página lanza un error de conflicto. Asigna la responsabilidad del control de caché a la función de carga más específica para cada ruta.
Lee la cookie de sesión en la carga del servidor del layout raíz exactamente una vez por solicitud y usa parent() en las cargas de página para acceder al usuario resuelto sin volver a leer la cookie.

Qué sigue

Las cookies y los encabezados te dan acceso a los metadatos de solicitud y respuesta dentro de las funciones de carga del servidor. Pero hay una pregunta más amplia: ¿dónde vive realmente un dato con alcance de solicitud, como una sesión validada, antes de llegar a una función de carga, y cómo se coloca allí en primer lugar? La respuesta es event.locals, poblado por hooks.server.ts. El próximo artículo, locals y el ciclo de vida de los Hooks, cubre cómo funciona el hook handle, cómo tipar y poblar locals, y cómo esos datos fluyen hacia cada función de carga del servidor en tu aplicación.

Lectura adicional

Documentación de Cookies de SvelteKit — referencia oficial de la API de cookies en el evento de carga
Documentación de carga de SvelteKit — referencia oficial de cookies y setHeaders en funciones de carga