Carga de Datos de Layout Exclusiva del Servidor

El archivo +layout.server.js (o +layout.server.ts) proporciona carga de datos exclusiva del servidor para los layouts. Esta es la opción más común para el layout raíz porque es donde típicamente se maneja la autenticación — verificar si un usuario ha iniciado sesión y poner esa información disponible en toda la aplicación.

Entender por qué este archivo es tan central requiere comprender el pipeline de solicitudes de SvelteKit. Cada solicitud HTTP pasa por hooks.server.ts antes de llegar a cualquier ruta. Los hooks pueden leer cookies de sesión, validar tokens y almacenar el resultado en event.locals — un objeto con alcance de solicitud que viaja con la solicitud desde los hooks hasta las funciones de carga. El +layout.server.js raíz es entonces el lugar ideal para leer desde locals y transmitir el objeto de usuario a cada página de la aplicación.

Este pipeline de tres etapas es lo que hace que la autenticación se sienta natural en SvelteKit:

hooks.server.ts   →  validates the session cookie  →  sets event.locals.user
+layout.server.ts →  reads event.locals.user        →  returns { user } to all pages
+layout.svelte    →  receives data.user             →  renders login/logout UI

El +layout.server.js raíz se ejecuta en cada solicitud, lo que lo convierte en el lugar perfecto para verificaciones de autenticación, carga de feature flags y establecimiento del contexto de usuario. Configura bien este archivo y la autenticación fluirá de manera natural a través de toda la aplicación sin necesidad de código repetitivo en cada página.

El Patrón de Autenticación

El caso de uso más importante para +layout.server.js es la autenticación. Al cargar los datos del usuario en el layout raíz, cada página de la aplicación tiene acceso al usuario actual.

// src/routes/+layout.server.ts
import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ cookies, locals }) => {
	// `locals` is typically populated by hooks.server.ts
	// It contains data like the authenticated user

	return {
		user: locals.user ?? null
	}
}

Ahora cada página y layout de la aplicación puede acceder a data.user:

<!-- src/routes/+layout.svelte -->
<script lang="ts">
	import type { LayoutProps } from './$types'

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

<header>
	{#if data.user}
		<span>Welcome, {data.user.name}</span>
		<a href="/dashboard">Dashboard</a>
		<form method="POST" action="/logout">
			<button>Logout</button>
		</form>
	{:else}
		<a href="/login">Login</a>
		<a href="/signup">Sign Up</a>
	{/if}
</header>

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

Trabajando con Hooks

Recorramos el pipeline completo para que las piezas encajen. El objeto locals se completa en el archivo hooks.server.ts antes de que se ejecute cualquier función de carga:

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit'
import { db } from '$lib/server/database'

export const handle: Handle = async ({ event, resolve }) => {
	// Read session cookie
	const sessionId = event.cookies.get('session')

	if (sessionId) {
		// Validate session and get user
		const session = await db.sessions.findUnique({
			where: { id: sessionId },
			include: { user: true }
		})

		if (session && session.expiresAt > new Date()) {
			event.locals.user = {
				id: session.user.id,
				name: session.user.name,
				email: session.user.email,
				role: session.user.role
			}
		}
	}

	return resolve(event)
}

// src/routes/+layout.server.ts
import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ locals }) => {
	// User is already validated in hooks
	return {
		user: locals.user ?? null
	}
}

Parámetros Exclusivos del Servidor

Al igual que +page.server.js, la función de carga del layout del servidor tiene acceso a parámetros exclusivos del servidor:

export const load: LayoutServerLoad = async ({
	cookies, // Read and write cookies
	locals, // Data from hooks.server.ts
	request, // The original Request object
	url, // The URL object
	fetch, // Server-side fetch
	platform, // Platform-specific context
	setHeaders // Set response headers
}) => {
	// Your server-only logic
}

Lectura Directa de Cookies

A veces es necesario leer cookies directamente en el layout:

// src/routes/+layout.server.ts
import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ cookies }) => {
	const theme = cookies.get('theme') ?? 'light'
	const locale = cookies.get('locale') ?? 'en'

	return {
		preferences: {
			theme,
			locale
		}
	}
}

Carga de Datos Globales de la Aplicación

El layout raíz es perfecto para cargar datos que se necesitan en todas partes:

// src/routes/+layout.server.ts
import type { LayoutServerLoad } from './$types'
import { db } from '$lib/server/database'
import { ANALYTICS_KEY } from '$env/static/private'

export const load: LayoutServerLoad = async ({ locals, cookies }) => {
	// Get user from hooks
	const user = locals.user

	// Load user-specific data if logged in
	let notifications = []
	let unreadCount = 0

	if (user) {
		const result = await db.notifications.findMany({
			where: { userId: user.id },
			orderBy: { createdAt: 'desc' },
			take: 5
		})
		notifications = result
		unreadCount = await db.notifications.count({
			where: { userId: user.id, read: false }
		})
	}

	// Load site-wide settings
	const settings = await db.settings.findFirst()

	return {
		user,
		notifications,
		unreadCount,
		settings: {
			siteName: settings?.siteName ?? 'My App',
			maintenanceMode: settings?.maintenanceMode ?? false
		}
	}
}

Patrón de Rutas Protegidas

Usa los datos del layout del servidor para proteger secciones completas de la aplicación:

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

export const load: LayoutServerLoad = async ({ locals, url }) => {
	if (!locals.user) {
		// Redirect to login with return URL
		const returnTo = encodeURIComponent(url.pathname)
		redirect(303, `/login?returnTo=${returnTo}`)
	}

	return {
		user: locals.user
	}
}

Ahora cualquier página dentro de (protected)/ requiere autenticación:

src/routes/
├── (protected)/
│   ├── +layout.server.ts    → Requires auth
│   ├── dashboard/
│   │   └── +page.svelte     → Protected
│   ├── settings/
│   │   └── +page.svelte     → Protected
│   └── profile/
│       └── +page.svelte     → Protected
├── login/
│   └── +page.svelte         → Public
└── +layout.server.ts        → Root (loads user if present)

Control de Acceso Basado en Roles

Extiende el patrón para permisos basados en roles:

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

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

	if (locals.user.role !== 'admin') {
		error(403, {
			message: 'Access Denied',
			hint: 'You need admin privileges to access this area.'
		})
	}

	return {
		user: locals.user
	}
}

Herencia de Datos

Los datos de los layouts padre están disponibles para los layouts e páginas hijo:

// src/routes/+layout.server.ts (root)
export const load: LayoutServerLoad = async ({ locals }) => {
	return {
		user: locals.user,
		appVersion: '2.1.0'
	}
}

// src/routes/dashboard/+layout.server.ts
export const load: LayoutServerLoad = async ({ locals, parent }) => {
	// Get parent data
	const parentData = await parent()

	// Load dashboard-specific data
	const stats = await getDashboardStats(locals.user.id)

	return {
		// Parent data is automatically included
		stats
	}
}

<!-- src/routes/dashboard/+page.svelte -->
<script lang="ts">
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()

	// Has access to:
	// - data.user (from root layout)
	// - data.appVersion (from root layout)
	// - data.stats (from dashboard layout)
</script>

Buenas Prácticas de Seguridad

No Expongas Datos Sensibles

// AVOID: Exposing all user data
export const load: LayoutServerLoad = async ({ locals }) => {
	return {
		user: locals.user // Might include passwordHash!
	}
}

// PREFERRED: Only expose what's needed
export const load: LayoutServerLoad = async ({ locals }) => {
	if (!locals.user) return { user: null }

	return {
		user: {
			id: locals.user.id,
			name: locals.user.name,
			email: locals.user.email,
			avatar: locals.user.avatar,
			role: locals.user.role
		}
	}
}

Valida en Cada Solicitud

export const load: LayoutServerLoad = async ({ locals, cookies }) => {
	// Even if locals.user exists, verify the session is still valid
	const sessionId = cookies.get('session')

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

	// Verify session hasn't been revoked
	const session = await db.sessions.findUnique({
		where: { id: sessionId }
	})

	if (!session || session.revokedAt) {
		cookies.delete('session', { path: '/' })
		return { user: null }
	}

	return { user: locals.user }
}

Conclusión

El archivo +layout.server.js representa la contraparte del lado del servidor para la carga universal de datos de layout, proporcionando una base segura para la autenticación, autorización y acceso a datos sensibles. Al ejecutarse exclusivamente en el servidor, permite el acceso directo a bases de datos, claves de API privadas y gestión de sesiones sin exponer detalles de implementación ni credenciales de seguridad al navegador. Se utiliza más comúnmente en layouts raíz para establecer el contexto de autenticación del usuario, transformando la seguridad de una preocupación por página en infraestructura de toda la aplicación.

Dominar +layout.server.js implica entender su relación con +layout.js para estrategias de datos híbridos, reconocer cuándo los datos deben ser exclusivos del servidor versus universales, e implementar una sanitización adecuada de los datos antes de enviarlos a los clientes.

Combinado con grupos de layouts para secciones de rutas protegidas y el objeto locals para datos con alcance de solicitud, proporciona la base para construir aplicaciones seguras y listas para producción donde la autenticación fluye de manera natural desde la raíz a través de toda la jerarquía de rutas.

Puntos Clave

+layout.server.js proporciona datos de layout exclusivos del servidor que nunca se ejecutan en el navegador, ideal para autenticación, consultas a bases de datos y operaciones sensibles que utilizan credenciales privadas
Se usa más comúnmente en el layout raíz (src/routes/+layout.server.js) para establecer un contexto de autenticación de usuario a nivel de toda la app que fluye hacia todas las páginas automáticamente
Accede a funcionalidades exclusivas del servidor incluyendo cookies para gestión de sesiones, locals para datos con ámbito de solicitud y platform para detalles del entorno de despliegue
Los datos fluyen hacia todos los descendientes - los layouts y páginas hijas reciben los datos del layout del servidor a través del prop data sin necesidad de pasarlos explícitamente
Combina con grupos de layout para secciones protegidas - usa grupos (authenticated) con +layout.server.js para aplicar requisitos de autenticación a subárboles de rutas completos
Siempre sanitiza los datos antes de exponerlos al cliente - filtra campos sensibles como hashes de contraseñas, IDs internos o flags de administrador antes de retornar los datos
Puede coexistir con +layout.js para estrategias híbridas - el servidor carga datos de autenticación/sensibles, el universal carga datos públicos como navegación o categorías
Los datos retornados deben ser serializables - sin funciones, clases ni referencias circulares, solo estructuras de datos compatibles con JSON

Ver También

Documentación Oficial de SvelteKit - +layout.server.js
Cookies - Gestión de sesiones y autenticación
Contexto de la Función Load - Entendiendo locals, cookies, platform
Grupos de Layout - Organización de rutas protegidas
Patrones de Autenticación - Construcción de flujos de autenticación seguros