Dos Archivos, Dos Entornos

Los dos artículos anteriores usaron +page.ts y +layout.ts para todas las funciones de carga, lo cual es el punto de partida correcto para entender cómo funciona el sistema. Pero SvelteKit en realidad provee dos tipos distintos de funciones de carga, y el archivo en el que las colocas determina algo fundamental sobre cómo y dónde se ejecutan.

El primer tipo, el que has visto hasta ahora, es la función de carga universal. Vive en +page.ts o +layout.ts. El segundo tipo es la función de carga de servidor. Vive en +page.server.ts o +layout.server.ts. Los nombres sugieren la diferencia, pero las implicaciones van más allá de simplemente "una se ejecuta en el servidor." Ambos tipos pueden ejecutarse en el servidor. Lo que los separa es a qué tienen acceso, qué pueden retornar y dónde se ejecutan durante la navegación del lado del cliente después de la carga inicial de la página.

Entender correctamente esta distinción es una de las decisiones arquitectónicas más importantes en una aplicación SvelteKit. Pon lógica privada de base de datos en una función de carga universal y podrías accidentalmente exponerla en el bundle del navegador. Pon una función que necesita retornar un constructor de componente Svelte en una función de carga de servidor y descubrirás que no puede ser serializada para enviarse por la red. Entender por qué existe cada tipo, no solo qué archivo usar, es lo que te permite tomar la decisión correcta con confianza en cada ocasión.

Por Qué Existen Dos Tipos de Archivos

Para entender por qué existen dos tipos, primero necesitas comprender qué está haciendo SvelteKit cuando un usuario visita una página.

Cuando un usuario navega directamente a una URL (escribiéndola en la barra de direcciones o siguiendo un enlace desde otro sitio), SvelteKit renderiza la página en el servidor y envía HTML completamente formado al navegador. La función de carga se ejecuta en el servidor, el componente se renderiza a una cadena de texto, y el navegador recibe un documento completo. Esto es renderizado del lado del servidor (SSR).

Cuando ese mismo usuario luego hace clic en un enlace dentro de la aplicación (navegando de una página a otra sin una recarga completa de página), SvelteKit maneja esa navegación completamente en el navegador. Llama a la función de carga nuevamente, pero esta vez en el navegador, obtiene solo los nuevos datos y actualiza la página sin un viaje de ida y vuelta al servidor para obtener HTML. Esto es navegación del lado del cliente.

Una función de carga universal participa en ambos escenarios. Se ejecuta en el servidor para la primera visita y en el navegador para las navegaciones subsiguientes. Esta ejecución en doble entorno es lo que significa "universal"; la misma función se ejecuta en ambos contextos.

Una función de carga de servidor, en cambio, siempre se ejecuta en el servidor. Se ejecuta en el servidor para la primera visita y también se ejecuta en el servidor para la navegación del lado del cliente; SvelteKit realiza una solicitud de red a un endpoint interno especial para llamarla, serializa el resultado y lo envía por la red al navegador. El navegador recibe los datos pero nunca ejecuta la función en sí.

Esta distinción tiene consecuencias profundas. El código de una función de carga universal se empaqueta para el navegador, lo que significa que nunca debe contener nada que no pueda existir de forma segura en el navegador: sin conexiones directas a bases de datos, sin variables de entorno secretas, sin APIs de Node.js. El código de una función de carga de servidor nunca llega al navegador, por lo que puede hacer todas esas cosas de forma segura.

El Modelo de Límite de Confianza

Piensa en los dos tipos de funciones de carga como ocupando diferentes límites de confianza.

Funciones de Carga Universales

El límite de confianza en una función de carga universal está en el límite de confianza pública. Es visible para cualquiera que pueda acceder al bundle de JavaScript de la página, lo cual es esencialmente cualquiera que pueda cargar la página. Esto significa que cualquier código en una función de carga universal debe ser seguro para ejecutarse en el navegador y no debe contener secretos ni acceso privilegiado. Es apropiada para lógica que no tiene secretos, sin acceso privilegiado y sin dependencias exclusivas del servidor, como obtener datos de una API pública, transformar datos ya públicos y leer variables de entorno que están explícitamente marcadas como públicas.

Una función de carga universal se ejecuta en ambos entornos. Durante SSR, se ejecuta en el servidor y su valor de retorno se inserta en el HTML enviado al navegador. Durante la navegación del lado del cliente, se ejecuta en el navegador y puede obtener datos directamente de APIs públicas sin involucrar al servidor. Debido a que se ejecuta en el navegador, puede retornar valores no serializables como constructores de componentes Svelte, instancias de clase, o Maps y Sets que quieras usar directamente en el componente. La función de carga de servidor no puede hacer esto porque su valor de retorno debe ser serializado para enviarse por la red.

Funciones de Carga de Servidor

El límite de confianza en una función de carga de servidor está en el límite de confianza privada. Nunca se envía al navegador y solo puede ser leída por desarrolladores con acceso al código del servidor. Esto significa que cualquier código en una función de carga de servidor puede contener de forma segura secretos y acceso privilegiado, como consultas a bases de datos, variables de entorno privadas y APIs internas que requieren autenticación. Es apropiada para cualquier cosa que deba permanecer confidencial o que tenga requisitos exclusivos del servidor, como consultar una base de datos, leer variables $env/static/private, inspeccionar cookies HTTP o llamar a un servicio interno con una clave de API privada.

Es apropiada para cualquier cosa que deba permanecer confidencial o que tenga requisitos exclusivos del servidor, como consultar una base de datos, leer variables $env/static/private, inspeccionar cookies HTTP o llamar a un servicio interno con una clave de API privada.

El límite es impuesto estructuralmente por el sistema de módulos de SvelteKit. Cualquier importación dentro de +page.server.ts que provenga de $lib/server/ o use $env/static/private es bloqueada automáticamente si alguna vez intenta ejecutarse en el contexto del navegador. No tienes que asegurar esta separación manualmente, porque la convención de nomenclatura de archivos es el mecanismo de cumplimiento.

El Patrón Combinado

Hay un tercer escenario que la documentación oficial cubre pero que es fácil pasar por alto: puedes usar ambos archivos para la misma ruta simultáneamente. Cuando tanto +page.server.ts como +page.ts existen, SvelteKit ejecuta primero la carga del servidor y pasa su valor de retorno como la propiedad data del argumento de evento de la carga universal. La carga universal puede entonces combinar esos datos del servidor con procesamiento adicional del lado del cliente antes de pasar el resultado final al componente. Esto es territorio avanzado que se cubre más adelante en este artículo, pero vale la pena saber que la capacidad existe.

Implementación

Paso 1: La Función de Carga Universal

Una función de carga universal en +page.ts se ejecuta en ambos entornos. Su caso de uso más apropiado es obtener datos de una API externa donde no se necesitan credenciales y donde el navegador podría teóricamente hacer la misma solicitud por sí mismo.

// src/routes/products/[id]/+page.ts

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

export const load: PageLoad = async ({ params, fetch }) => {
	// This is a public API; no secret credentials required.
	// The browser could call this URL directly. We are just doing it
	// earlier, in the load function, so the page renders with data ready.
	const response = await fetch(`https://api.storefront.example.com/products/${params.id}`)

	if (!response.ok) {
		error(response.status, `Product not found: ${params.id}`)
	}

	const product = await response.json()

	return { product }
}

<!-- src/routes/products/[id]/+page.svelte -->

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

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

<h1>{data.product.name}</h1>
<p class="price">${data.product.price}</p>
<p>{data.product.description}</p>

No hay nada secreto aquí. La URL de la API, el ID del producto y la respuesta serían visibles para cualquiera que abriera el panel de red del navegador. Usar una función de carga universal para este caso es correcto y eficiente: durante SSR, SvelteKit llama a la API en el servidor e inserta la respuesta en el HTML; durante la navegación del lado del cliente, el navegador llama a la misma URL y actualiza la página directamente. No se necesita ningún salto intermedio al servidor.

La función de carga universal también tiene acceso a capacidades que las funciones de carga de servidor no tienen. Más notablemente, puede retornar valores que no son serializables, como constructores de componentes Svelte, instancias de clase, o Maps y Sets que quieras usar directamente en el componente. Debido a que la carga universal se ejecuta en el mismo entorno JavaScript que el componente, puede pasar valores ricos sin serialización.

Paso 2: La Función de Carga de Servidor

Una función de carga de servidor en +page.server.ts siempre se ejecuta en el servidor. Es la elección correcta cuando la función de carga necesita acceso privilegiado o debe trabajar con recursos exclusivos del servidor.

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

import type { PageServerLoad } from './$types'
import { METRICS_API_URL, METRICS_API_KEY } from '$env/static/private'
import { error, redirect } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ locals, fetch }) => {
	// locals.user is populated by the authentication hook in src/hooks.server.ts.
	// Only server load functions can read locals — universal load functions cannot.
	if (!locals.user) {
		redirect(307, '/login')
	}

	// Calling a private internal service using a secret environment variable.
	// METRICS_API_KEY never reaches the browser — it is server-only.
	const metricsRes = await fetch(`${METRICS_API_URL}/users/${locals.user.id}`, {
		headers: { Authorization: `Bearer ${METRICS_API_KEY}` }
	})

	if (!metricsRes.ok) {
		error(502, 'Metrics service unavailable')
	}

	return {
		user: {
			id: locals.user.id,
			name: locals.user.name,
			email: locals.user.email,
			plan: locals.user.plan
		},
		metrics: await metricsRes.json()
	}
}

Varias capacidades usadas aquí son exclusivas de las funciones de carga de servidor. locals solo está disponible en +page.server.ts y +layout.server.ts; las funciones de carga universales no pueden leerlo. $env/static/private solo puede importarse en contextos exclusivos del servidor — el empaquetador lo hace cumplir en tiempo de compilación. Ninguno de este código toca el navegador.

locals es un objeto tipado que SvelteKit popula mediante hooks del servidor en src/hooks.server.ts. El hook se ejecuta en cada solicitud antes de cualquier función de carga, autentica la sesión y adjunta el usuario resuelto a locals. Las funciones de carga de servidor luego leen locals.user directamente — sin necesidad de una solicitud secundaria. Este es el patrón estándar de SvelteKit para autenticación: los hooks manejan la resolución de identidad, las funciones de carga de servidor consumen el resultado.

El valor de retorno de una función de carga de servidor debe ser serializable usando la biblioteca devalue, que es un superconjunto de JSON que también maneja Date, Map, Set, BigInt, RegExp y referencias circulares. Las instancias de clase con métodos, los constructores de componentes Svelte y las funciones arbitrarias no pueden serializarse y por lo tanto no pueden retornarse desde una función de carga de servidor. Si necesitas retornar algo no serializable, esa es una señal de que una función de carga universal, posiblemente combinada con una función de carga de servidor, es la arquitectura correcta.

Paso 3: Reconocer Qué No Puedes Hacer en Cada Contexto

La forma práctica de internalizar la distinción es entender qué fallará en cada contexto. Las funciones de carga universales fallarán si intentan importar módulos exclusivos del servidor. Las funciones de carga de servidor fallarán si intentan retornar valores no serializables. Estos fallos se manifiestan como errores de TypeScript o errores en tiempo de ejecución que SvelteKit hace explícitos, lo que los hace más fáciles de detectar que los errores lógicos silenciosos.

Aquí hay una tabla de las capacidades clave y qué tipo de carga las soporta:

Capacidad	Universal (`+page.ts`)	Servidor (`+page.server.ts`)
Se ejecuta en servidor (SSR)	Sí	Sí
Se ejecuta en navegador (navegación)	Sí	No (datos obtenidos vía API interna)
Acceso a `cookies`	No	Sí
Acceso a `locals`	No	Sí
Acceso a `$env/static/private`	No	Sí
Módulos de `$lib/server/`	No	Sí
Retornar valores no serializables	Sí	No
El código aparece en el bundle del navegador	Sí	No

Si una función de carga no necesita nada de la columna derecha, una carga universal en +page.ts está bien. Si necesita algo de la columna derecha, debe ir en +page.server.ts.

Paso 4: Combinar Ambos en la Misma Ruta

Hay situaciones en las que ningún tipo por sí solo es suficiente. El caso más común es una ruta que necesita datos exclusivos del servidor (por ejemplo, un objeto de usuario de la base de datos) y también necesita retornar algo no serializable (por ejemplo, un componente Svelte seleccionado dinámicamente según el rol del usuario).

SvelteKit admite esto al permitir que tanto +page.server.ts como +page.ts coexistan para la misma ruta. Cuando ambos existen, SvelteKit ejecuta primero la carga del servidor, luego pasa su valor de retorno como data en el argumento de evento de la carga universal. La carga universal combina los datos del servidor con cualquier procesamiento del lado del cliente que necesite y retorna el resultado final al componente.

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

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

export const load: PageServerLoad = async ({ locals }) => {
	// locals.user is set by the auth hook — only readable in server load functions.
	if (!locals.user) redirect(307, '/login')

	return {
		userId: locals.user.id,
		role: locals.user.role as 'admin' | 'editor' | 'viewer',
		displayName: locals.user.displayName
	}
}

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

import type { PageLoad } from './$types'
// These are Svelte component constructors; non-serialisable.
// They can only be passed through a universal load function.
import AdminDashboard from '$lib/components/AdminDashboard.svelte'
import EditorDashboard from '$lib/components/EditorDashboard.svelte'
import ViewerDashboard from '$lib/components/ViewerDashboard.svelte'

const DASHBOARD_COMPONENTS = {
	admin: AdminDashboard,
	editor: EditorDashboard,
	viewer: ViewerDashboard
}

export const load: PageLoad = async ({ data }) => {
	// `data` here is the return value of +page.server.ts.
	// The universal load receives it and can extend or transform it.
	const DashboardComponent = DASHBOARD_COMPONENTS[data.role]

	return {
		// Spread the server data through so the component receives it all.
		...data,
		// Add the component constructor (something the server load cannot return).
		DashboardComponent
	}
}

<!-- src/routes/dashboard/+page.svelte -->

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

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

<h1>Welcome, {data.displayName}</h1>

<!-- Dynamically render whichever dashboard component the user's role requires. -->
{@const DashboardComponent = data.DashboardComponent}
<DashboardComponent userId={data.userId} />

Este patrón mantiene limpio el límite de privilegios: la carga del servidor maneja todo lo que necesita acceso exclusivo al servidor, la carga universal maneja todo lo que necesita valores no serializables, y el componente recibe un resultado fusionado limpio de ambos. El valor de retorno de la carga del servidor es la propiedad data del evento de la carga universal; fluye a través de la carga universal pero no se pasa automáticamente al componente. La carga universal es responsable de incluir en su propio valor de retorno cualquier dato del servidor que el componente necesite, típicamente mediante la expansión ...data.

Errores Comunes y Anti-Patrones

Usar Importaciones Exclusivas del Servidor en una Función de Carga Universal

Este es el error más peligroso en esta área. No siempre falla de inmediato; puede funcionar en desarrollo, luego exponer credenciales privadas en el bundle del navegador en producción, o fallar cuando el código exclusivo de Node.js se ejecuta en un contexto de navegador.

// src/routes/profile/+page.ts

// AVOID: Importing a private environment variable in a universal load function.
// This file is bundled for the browser. PRIVATE_API_KEY would be visible
// to anyone who inspects the JavaScript bundle.
import { PRIVATE_API_KEY } from '$env/static/private'
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/users/${params.id}`, {
		headers: { Authorization: `Bearer ${PRIVATE_API_KEY}` } // key exposed!
	})
	return { user: await res.json() }
}

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

// PREFERRED: Private credentials belong in a server load function.
// This file never reaches the browser bundle.
import type { PageServerLoad } from './$types'
import { PRIVATE_API_KEY } from '$env/static/private'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/users/${params.id}`, {
		headers: { Authorization: `Bearer ${PRIVATE_API_KEY}` } // safe, server-only
	})
	if (!res.ok) error(404, 'User not found')
	return { user: await res.json() }
}

SvelteKit lanza un error en tiempo de compilación si importas $env/static/private o cualquier cosa de $lib/server/ en una función de carga universal — el empaquetador reconoce esos como módulos exclusivos del servidor y se niega a incluirlos en el bundle del cliente. La protección se basa en la convención de rutas: cualquier archivo bajo $lib/server/ es tratado como exclusivo del servidor automáticamente. Mantén toda la lógica privilegiada allí para que las herramientas puedan hacer cumplir el límite en tu nombre.

Intentar Retornar una Instancia de Clase desde una Función de Carga de Servidor

Cuando una función de carga de servidor retorna datos, SvelteKit los serializa usando devalue antes de enviarlos por la red al navegador. Las instancias de clase con métodos, cadenas de prototipos y propiedades no enumerables no sobreviven la serialización. Lo que llega al navegador es un objeto simple con las mismas claves enumerables; los métodos y el prototipo han desaparecido.

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

class ShoppingCart {
	items: CartItem[]
	constructor(items: CartItem[]) {
		this.items = items
	}
	get total() {
		return this.items.reduce((sum, item) => sum + item.price, 0)
	}
	addItem(item: CartItem) {
		/* ... */
	}
}

// AVOID: The ShoppingCart class instance cannot be serialised.
// The browser will receive { items: [...] } with no methods.
export const load: PageServerLoad = async ({ locals, fetch }) => {
	if (!locals.user) redirect(307, '/login')
	const res = await fetch(`/api/cart/${locals.user.id}`)
	const items: CartItem[] = await res.json()
	return { cart: new ShoppingCart(items) }
}

// PREFERRED option A: Return plain data from the server load.
// Reconstruct the class in the universal load if needed.

// +page.server.ts
export const load: PageServerLoad = async ({ locals, fetch }) => {
	if (!locals.user) redirect(307, '/login')
	const res = await fetch(`/api/cart/${locals.user.id}`)
	const cartItems: CartItem[] = await res.json()
	return { cartItems } // plain serialisable data
}

// +page.ts
export const load: PageLoad = async ({ data }) => {
	// Reconstruct the class in the universal load where it can survive.
	const cart = new ShoppingCart(data.cartItems)
	return { cart }
}

El patrón de archivos divididos existe precisamente para este escenario. La carga del servidor maneja la recuperación de datos privilegiados. La carga universal reconstruye objetos ricos que se benefician del comportamiento de clase. Cada uno hace para lo que es adecuado.

Confundir Cuál `data` es Cuál al Usar Ambos Archivos

Cuando tanto +page.server.ts como +page.ts existen para la misma ruta, hay dos cosas diferentes llamadas data en proximidad cercana: la propiedad data en el argumento de evento de la carga universal (que contiene el valor de retorno de la carga del servidor), y la prop data en el componente (que contiene el valor de retorno de la carga universal). Estas son distintas y pueden diferir si la carga universal no expande los datos del servidor.

// +page.server.ts
export const load: PageServerLoad = async () => {
	return { serverMessage: 'hello from server' }
}

// +page.ts (AVOID): Forgetting to include server data in the return value
export const load: PageLoad = async ({ data }) => {
	// data.serverMessage is available here, but we are not returning it.
	return { universalMessage: 'hello from universal' }
	// The component will only see universalMessage.
	// serverMessage is lost because the universal load did not pass it through.
}

// +page.ts (PREFERRED): Spread server data into the universal return value
export const load: PageLoad = async ({ data }) => {
	return {
		...data, // includes serverMessage
		universalMessage: 'hello from universal'
	}
	// The component now sees both serverMessage and universalMessage.
}

Este es un error puramente mecánico pero produce síntomas confusos; los tipos de TypeScript para data en el componente incluyen serverMessage (porque SvelteKit puede ver ambos tipos de retorno), pero el valor es undefined en tiempo de ejecución porque la carga universal nunca lo pasó. Siempre expande ...data cuando quieras que los datos de la carga del servidor lleguen al componente.

Consideraciones de Rendimiento y Escalabilidad

La elección entre funciones de carga universal y de servidor tiene implicaciones de rendimiento significativas que van más allá de la corrección.

Las funciones de carga universales permiten que SvelteKit potencialmente omita el servidor por completo durante la navegación del lado del cliente. Si tu carga universal obtiene datos de una API pública con caché en CDN, el navegador puede acceder a esa caché directamente en cada navegación sin tocar tu servidor. Las funciones de carga de servidor, en cambio, siempre implican un viaje de ida y vuelta a tu servidor durante la navegación del lado del cliente; SvelteKit realiza una solicitud a un endpoint interno, tu servidor ejecuta la función de carga y el resultado viaja de regreso por la red. Para aplicaciones de alto tráfico, las cargas universales que usan APIs públicas bien cacheadas pueden reducir significativamente la carga del servidor.

Las funciones de carga de servidor, sin embargo, tienen su propia ventaja de rendimiento: se ejecutan más cerca de tus datos. Una función de carga de servidor que consulta una base de datos local tiene una latencia de red medida en milisegundos. Una función de carga universal que llama a una API externa desde el navegador puede tener una latencia medida en cientos de milisegundos, más la sobrecarga de CORS y la transmisión de tokens de autenticación. Para datos que genuinamente requieren acceso del lado del servidor, la proximidad de la carga del servidor a la fuente de datos es una característica, no solo una restricción.

El patrón combinado (carga de servidor más carga universal) tiene la sobrecarga de ambos: la carga del servidor se ejecuta en el servidor, y luego la carga universal se ejecuta en el entorno apropiado, usando el resultado de la carga del servidor. Usa el patrón combinado solo cuando realmente necesites ambas capacidades; no lo uses por defecto por costumbre.

Cuándo NO Usar Este Patrón

El patrón combinado +page.server.ts más +page.ts es poderoso pero representa complejidad adicional. La mayoría de las rutas necesitan solo uno u otro. Si te encuentras recurriendo al patrón combinado con frecuencia, puede ser una señal de que tu ruta está haciendo demasiado; obtener datos privilegiados del servidor y construir objetos ricos del lado del cliente que estarían mejor separados en rutas o componentes distintos.

La función de carga universal no es apropiada como solución alternativa para hacer que los datos del servidor sean "más convenientes." Si los datos requieren acceso exclusivo del servidor, pertenecen a una función de carga de servidor, sin excepción. Usar una función de carga universal y luego proteger manualmente contra la ejecución en el navegador anula la seguridad estructural que proporciona la convención de nomenclatura de archivos.

Conclusión

Las funciones de carga universales y las de servidor ocupan entornos diferentes y tienen capacidades distintas. Las funciones de carga universales se ejecutan tanto en el servidor como en el navegador, pertenecen a +page.ts y son apropiadas para datos públicos y valores de retorno no serializables. Las funciones de carga de servidor siempre se ejecutan en el servidor, pertenecen a +page.server.ts y son el lugar correcto para todo lo que requiere acceso privilegiado, como consultas a bases de datos, variables de entorno privadas y cookies de sesión. La convención de nombres de archivo no es solo organizacional; es el mecanismo de aplicación de un límite de seguridad significativo.

Cuando entiendes no solo qué archivo usar sino por qué existe la distinción, la elección se vuelve sencilla: pregunta a qué necesita acceder la función de carga y deja que la respuesta te indique en qué archivo pertenece.

Una nota sobre hacia dónde se dirige el ecosistema

SvelteKit está desarrollando una función experimental llamada Remote Functions que aborda el límite cliente-servidor desde un ángulo diferente. En lugar de estructurar la lógica del servidor alrededor de archivos de ruta, las Remote Functions te permiten definir funciones del lado del servidor en archivos .remote.ts y llamarlas desde cualquier lugar del árbol de componentes, incluso directamente desde el marcado del componente usando la opción async del compilador de Svelte.

Las Remote Functions aún están bajo el indicador experimental al momento de escribir esto y la API ha cambiado significativamente con cada versión. No se cubren en esta serie porque enseñar una API que puede cambiar entre versiones menores de SvelteKit perjudicaría a los lectores. Cuando se estabilicen, merecerán su propia serie dedicada. Mientras tanto, los patrones de funciones de carga cubiertos aquí son la base lista para producción sobre la que las propias Remote Functions se construyen.

Puntos clave

Las funciones de carga universales (+page.ts) se ejecutan en el servidor durante el SSR y en el navegador durante la navegación del lado del cliente. Pueden devolver valores no serializables, pero nunca deben contener importaciones exclusivas del servidor ni credenciales privadas, porque su código se empaqueta para el navegador.

Las funciones de carga de servidor (+page.server.ts) siempre se ejecutan en el servidor. Tienen acceso exclusivo a cookies, locals, variables de entorno privadas y módulos exclusivos del servidor. Sus valores de retorno deben ser serializables porque viajan por la red hasta el navegador.

Cuando una ruta necesita tanto acceso privilegiado a datos como valores de retorno no serializables, ambos archivos pueden coexistir. La carga del servidor se ejecuta primero y su valor de retorno llega como data en el argumento event de la carga universal. La carga universal es responsable de incluir en su propio valor de retorno los datos del servidor que el componente necesite.

La convención de nombres de archivo es el límite de seguridad. Importar módulos de $lib/server/ en una función de carga universal es un error en tiempo de compilación. Devolver valores no serializables desde una función de carga de servidor es un error en tiempo de ejecución. Ambos fallos son explícitos por diseño.

¿Qué sigue?

Con una comprensión sólida de los dos tipos de funciones de carga, es momento de ver qué información puede utilizar una función de carga más allá de simplemente saber qué ruta está activa. La URL en sí contiene una gran cantidad de datos (parámetros de ruta, cadenas de consulta y el pathname completo), y SvelteKit le da a las funciones de carga acceso estructurado y tipado a todo ello. El próximo artículo, Usando datos de URL en funciones de carga, explica cómo usar esos datos de URL de manera efectiva tanto en funciones de carga universales como de servidor, y cómo mantener tu estructura de URL limpia e intuitiva a medida que crece tu aplicación.

Lecturas adicionales

Módulos exclusivos del servidor en SvelteKit (cómo se aplica el límite de $lib/server/)
Opciones de página en SvelteKit (control del SSR y el prerenderizado, lo que afecta cuándo se ejecutan las funciones de carga)
Documentación oficial de carga en SvelteKit (la referencia definitiva para todas las opciones y tipos de funciones de carga)