Carga Universal de Datos en SvelteKit

Las páginas estáticas son útiles, pero las aplicaciones reales necesitan datos. El archivo +page.js (o +page.ts para TypeScript) es donde cargas los datos para tus páginas. Esto se llama carga de datos universal porque el mismo código se ejecuta tanto en el servidor como en el navegador — y entender por qué esto importa es la clave para usarlo bien.

Cuando un usuario visita tu aplicación por primera vez (escribiendo una URL o actualizando la página), la página se renderiza en el servidor. En ese momento, Node.js ejecuta tu función load para obtener datos antes de enviar el HTML al navegador. Pero cuando el usuario hace clic en un enlace hacia otra página, no hay un viaje de ida y vuelta al servidor — SvelteKit ejecuta la misma función load directamente en el navegador. Una función, dos entornos, comportamiento consistente. Ese es el contrato que ofrece +page.js.

La restricción que viene con este poder: tu código debe funcionar en ambos entornos. Sin window, sin document, sin acceso directo a bases de datos, sin claves de API privadas. Si necesitas alguna de esas cosas, usa +page.server.js en su lugar.

La naturaleza "universal" de +page.js es tanto su fortaleza como su restricción. Permite una navegación del lado del cliente instantánea (no se necesita un viaje al servidor en visitas posteriores a la página), pero significa que solo puedes usar código que funcione tanto en Node.js como en el navegador. Elige sabiamente según si tus datos son públicos o sensibles.

Tu Primera Función Load

Vamos a crear una página de blog que muestre una lista de publicaciones. Primero, crea un archivo +page.ts dentro del directorio src/routes/blog/:

// src/routes/blog/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async () => {
	// In a real app, this might come from an API or database
	const posts = [
		{
			slug: 'hello-world',
			title: 'Hello World',
			excerpt: 'My first blog post ever!',
			date: '2025-01-15'
		},
		{
			slug: 'learning-svelte',
			title: 'Learning Svelte',
			excerpt: 'Why Svelte is my new favorite framework.',
			date: '2025-01-14'
		},
		{
			slug: 'routing-deep-dive',
			title: 'SvelteKit Routing Deep Dive',
			excerpt: 'Everything you need to know about routing.',
			date: '2025-01-13'
		}
	]

	return {
		posts
	}
}

Esta función load se ejecuta cada vez que un usuario visita la página /blog. Obtiene una lista de publicaciones del blog (aquí codificadas de forma estática para mayor claridad) y las retorna como un objeto. Lo que retornes estará disponible como data en el +page.svelte correspondiente — no se requiere ninguna configuración adicional; SvelteKit los conecta automáticamente.

Conectando los Datos a la Página

El objeto que retornas desde tu función load estará disponible en tu componente de página como la prop data.

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

	// The $props() rune receives the data from the load function
	let { data }: PageProps = $props()
</script>

<h1>Blog</h1>

<ul class="post-list">
	{#each data.posts as post}
		<li>
			<article>
				<h2>
					<a href="/blog/{post.slug}">{post.title}</a>
				</h2>
				<time datetime={post.date}>{post.date}</time>
				<p>{post.excerpt}</p>
			</article>
		</li>
	{/each}
</ul>

<style>
	.post-list {
		list-style: none;
		padding: 0;
	}

	article {
		margin-bottom: 2rem;
		padding-bottom: 2rem;
		border-bottom: 1px solid #eee;
	}

	h2 {
		margin-bottom: 0.5rem;
	}

	time {
		color: #666;
		font-size: 0.875rem;
	}
</style>

Cómo Fluyen los Datos: El Modelo Mental

Entender este flujo de datos es la clave para dominar SvelteKit. Es una calle de sentido único y predecible, y lo importante de interiorizar es que el componente nunca espera los datos — para cuando tu componente se ejecuta, los datos ya están ahí.

El Disparador: Un usuario visita una página (por ejemplo, /blog)
El Cargador: SvelteKit busca un archivo +page.js y ejecuta la función load
La Espera: SvelteKit espera a que tu función load termine (incluyendo cualquier llamada con await)
La Entrega: El objeto retornado por load se pasa al componente de la página
El Renderizado: El componente +page.svelte se renderiza, recibiendo los datos a través de la prop data

flowchart
    A(User visits /blog) --> B[+page.ts - load function runs]
    B --> C{Fetch & Await}
    C --> G(Data Ready)
    G --> D(Return Data Object)
    D --> H(Pass to Component)
    H --> E(Render +page.svelte)
    E --> F([Display data.posts])

    style A fill:#ffffff, color:#000
    style F fill:#e8f5e9, color:#000
    style B fill:#fff3e0, color:#000
    style E fill:#f3e5f5, color:#000
	style C fill:#ffebee, color:#000
	style G fill:#a4fcb1, color:#000
	style D fill:#f9fbe7, color:#000
	style H fill:#e1f5fe, color:#000

La función load se ejecuta antes de que tu componente se renderice. Esto significa que no necesitas manejar "estados de carga" dentro de tu componente para los datos iniciales — sin banderas isLoading = true, sin renderizados condicionales que verifiquen si los datos existen. Para cuando +page.svelte se monta, se garantiza que los datos ya están ahí. Esto es fundamentalmente diferente a las SPAs donde los componentes obtienen datos por sí mismos después de montarse.

Obteniendo Datos de APIs

En aplicaciones reales, obtendrás datos de APIs. La función load de SvelteKit recibe una función fetch personalizada especial que funciona tanto en el servidor como en el navegador:

// src/routes/blog/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ fetch }) => {
	// This fetch works on server AND browser
	const response = await fetch('/api/posts')
	const posts = await response.json()

	return {
		posts
	}
}

¿Por Qué Usar el `fetch` Proporcionado?

Esta es una de las sutilezas más importantes de SvelteKit. Si usas el fetch global directamente, pierdes varias garantías que solo ofrece la versión proporcionada.

Durante el SSR, el fetch proporcionado puede llamar a tus propios endpoints +server.js como si fuera un cliente — conoce el enrutamiento interno de tu aplicación. El fetch global en Node.js necesitaría una URL absoluta y no sabría en qué puerto está corriendo tu aplicación.

Maneja rutas internas: Puede llamar a tus propios endpoints de API durante el SSR sin necesitar URLs absolutas
Deduplica solicitudes: Si múltiples funciones load obtienen la misma URL, solo se dispara una solicitud HTTP
Preserva las cookies: Reenvía las cookies del usuario automáticamente para solicitudes autenticadas
Funciona en todas partes: El mismo código se ejecuta en el servidor y el cliente sin modificaciones

Siempre desestructura fetch del parámetro de la función load en lugar de usar el global.

Los Parámetros de la Función Load

La función load recibe un objeto con varias propiedades útiles:

export const load: PageLoad = async ({
	fetch, // Special fetch that works server + client
	params, // Route parameters (e.g., { slug: 'my-post' })
	url, // URL object with pathname, searchParams, etc.
	route, // Information about the current route
	data // Data from parent layouts (if they exist)
}) => {
	// Your loading logic here
}

Puedes desestructurar solo las propiedades que necesitas:

export const load: PageLoad = async ({ params, url }) => {
	// Use what you need
}

Usando Parámetros de Ruta

Los parámetros de ruta son segmentos dinámicos en tu URL, definidos por corchetes en los nombres de tus archivos o carpetas (por ejemplo, [slug], [id]). Cuando un usuario visita una URL que coincide con una ruta dinámica, SvelteKit extrae el valor y lo hace disponible en el objeto params de tu función load.

Para rutas dinámicas como /blog/[slug], puedes acceder al parámetro:

// src/routes/blog/[slug]/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch }) => {
	// params.slug contains the value from the URL
	const response = await fetch(`/api/posts/${params.slug}`)
	const post = await response.json()

	return {
		post
	}
}

Para necesidades de enrutamiento más complejas y parámetros dinámicos, consulta nuestra guía de Enrutamiento Avanzado.

Usando Parámetros de Búsqueda en la URL

En Svelte 5, el parámetro url proporcionado a tu función load es un objeto URL, por lo que puedes usar url.searchParams.get('key') directamente. Esto facilita la lectura de cadenas de consulta para filtrado, búsqueda o paginación.

Accede a cadenas de consulta como /search?q=svelte:

// src/routes/search/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ url, fetch }) => {
	const query = url.searchParams.get('q') || ''

	const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`)
	const results = await response.json()

	return {
		query,
		results
	}
}

¿Cuándo se Ejecuta `load`?

Esto es importante entenderlo:

Escenario	Dónde se Ejecuta `load`
Primera visita a la página (escribir URL, actualizar)	Servidor
Hacer clic en un enlace hacia esta página	Navegador
Usar atrás/adelante del navegador	Navegador (generalmente en caché)

La misma función load funciona en ambos entornos. Esto es poderoso, pero significa que no puedes usar características exclusivas del servidor aquí (como acceso directo a bases de datos o claves de API privadas). Para esos casos, usa +page.server.js.

Retornando Diferentes Tipos de Datos

La función load puede retornar cualquier dato serializable. Esta flexibilidad te permite:

Retornar datos de múltiples fuentes
Incluir metadatos para la página
Pasar valores derivados/calculados
Proporcionar configuración de componentes

export const load: PageLoad = async ({ fetch }) => {
	const [postsRes, categoriesRes] = await Promise.all([
		fetch('/api/posts'),
		fetch('/api/categories')
	])

	return {
		posts: await postsRes.json(),
		categories: await categoriesRes.json(),
		metadata: {
			title: 'Blog',
			description: 'Read our latest posts'
		}
	}
}

Carga de Datos en Paralelo

Cuando tu página necesita datos de varias fuentes independientes, obtenerlos en paralelo significa que todas las solicitudes comienzan al mismo tiempo. Esto reduce drásticamente el tiempo total de carga — la página carga en el tiempo de la solicitud más lenta, no en la suma de todas las solicitudes.

Aquí está la distinción clave a entender: await dentro de código async es secuencial. Cada await pausa la ejecución hasta que esa promesa se resuelve antes de continuar. Promise.all, en cambio, dispara todas las promesas simultáneamente y espera a todas ellas juntas.

// PREFERRED: All three requests fire simultaneously
export const load: PageLoad = async ({ fetch }) => {
	const [posts, categories, featured] = await Promise.all([
		fetch('/api/posts').then((r) => r.json()),
		fetch('/api/categories').then((r) => r.json()),
		fetch('/api/featured').then((r) => r.json())
	])

	return { posts, categories, featured }
}

Evita las obtenciones secuenciales cuando las solicitudes son independientes. Este patrón agrega latencia proporcional al número de solicitudes:

// AVOID: Sequential — each request waits for the previous to complete
// If each call takes 100ms, this takes ~300ms total.
// The Promise.all above takes ~100ms regardless of request count.
export const load: PageLoad = async ({ fetch }) => {
	const posts = await fetch('/api/posts').then((r) => r.json())
	const categories = await fetch('/api/categories').then((r) => r.json())
	const featured = await fetch('/api/featured').then((r) => r.json())

	return { posts, categories, featured }
}

El patrón secuencial solo es apropiado cuando una solicitud depende genuinamente del resultado de otra — por ejemplo, obtener el ID de un usuario y luego obtener las publicaciones de ese usuario. Si las solicitudes son independientes, usa siempre Promise.all.

Usa Promise.all para fuentes de datos independientes. Tu página cargará tan rápido como la solicitud más lenta, no la suma de todas las solicitudes.

Manejo de Errores en las Funciones Load

El manejo adecuado de errores es esencial para una buena experiencia de usuario. Usa el helper error para activar el mecanismo de manejo de errores de SvelteKit:

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

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

	if (response.status === 404) {
		error(404, {
			message: 'Post not found',
			hint: 'The post may have been removed or renamed.'
		})
	}

	if (!response.ok) {
		error(response.status, 'Failed to load post')
	}

	return {
		post: await response.json()
	}
}

Para un análisis profundo de páginas de error personalizadas y manejo avanzado de errores, consulta +error.svelte.

Errores Comunes

#1: Usar APIs del Navegador

// AVOID:  localStorage doesn't exist on the server!
export const load: PageLoad = async () => {
	const theme = localStorage.getItem('theme')
	return { theme }
}

// PREFERRED: Check for browser environment
import { browser } from '$app/environment'

export const load: PageLoad = async () => {
	const theme = browser ? localStorage.getItem('theme') : 'light'
	return { theme }
}

#2: No Manejar Errores

// AVOID:  What if the API is down?
export const load: PageLoad = async ({ fetch }) => {
	const response = await fetch('/api/data')
	return await response.json()
}

// PREFERRED: Handle error cases
import { error } from '@sveltejs/kit'

export const load: PageLoad = async ({ fetch }) => {
	const response = await fetch('/api/data')

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

	return await response.json()
}

#3: Retornar Datos No Serializables

// AVOID:  Functions can't travel from server to browser
export const load: PageLoad = async () => {
	return {
		formatDate: (d: Date) => d.toLocaleDateString()
	}
}

// PREFERRED: Return data, handle formatting in component
export const load: PageLoad = async () => {
	return {
		date: new Date().toISOString()
	}
}

Conclusión

El archivo +page.js encarna la filosofía de JavaScript universal de SvelteKit—código que se ejecuta en cualquier lugar, proporcionando un comportamiento consistente ya sea durante el renderizado del lado del servidor o la navegación del lado del cliente. Al ejecutarse tanto en el servidor como en el cliente, permite experiencias de usuario óptimas: cargas iniciales rápidas con renderizado en el servidor, navegaciones posteriores instantáneas con obtención de datos del lado del cliente, y lógica de carga de datos compartida sin duplicación. Esta universalidad es el arma secreta de SvelteKit para construir aplicaciones que se sienten rápidas en todos lados mientras permanecen fundamentalmente basadas en la web.

Dominar +page.js significa entender las restricciones del código universal (sin window, sin document, sin APIs privadas), aprovechar el fetch mejorado para la deduplicación automática de solicitudes y credenciales, y usar el acceso a datos del padre para construir sobre el contexto proporcionado por los layouts. Combinado con la precarga estratégica y el seguimiento adecuado de dependencias con depends(), las funciones de carga universal crean aplicaciones donde los datos fluyen naturalmente desde las URLs hacia los componentes, la navegación se siente instantánea, y la línea entre servidor y cliente se convierte en un detalle de implementación en lugar de una carga arquitectónica.

Puntos Clave

+page.js se ejecuta de forma universal - se ejecuta durante SSR en el servidor y durante la navegación del lado del cliente en el navegador, proporcionando carga de datos consistente en todos lados
Debe usar código agnóstico a la plataforma - sin window, document, ni APIs específicas del navegador ya que se ejecuta tanto en el servidor como en el cliente
El fetch mejorado proporciona superpoderes - reenvío automático de cookies, deduplicación de solicitudes entre funciones de carga, y resolución de URLs relativas durante SSR
Accede a los datos del layout padre mediante await parent() - construye sobre el contexto de autenticación, categorías u otros datos proporcionados por el layout sin prop drilling
La precarga hace que la navegación sea instantánea - usa data-sveltekit-preload-data en los enlaces para obtener los datos de la página al pasar el cursor antes de navegar
Los datos retornados deben ser serializables - solo datos compatibles con JSON (sin funciones, clases, Dates, RegExp) para transferir del servidor al cliente
Usa depends() para la invalidación lógica - crea claves de invalidación personalizadas como depends('app:posts') para activar recargas mediante invalidate()
Promise.all permite la obtención en paralelo - combina múltiples operaciones asíncronas para cargar datos relacionados simultáneamente sin cascadas secuenciales

Ver También

Documentación Oficial de SvelteKit - +page.js
Carga Universal vs Servidor - Elegir el enfoque correcto
fetch en Funciones de Carga - Capacidades mejoradas de fetch
Precarga - Estrategias de precarga de enlaces
Invalidación - Revalidación manual de datos
Función parent() - Acceder a los datos del layout