Por Qué Existen las Funciones Load

Toda aplicación web eventualmente necesita obtener datos antes de poder renderizar algo significativo para el usuario. Una página de producto necesita el producto. Un dashboard necesita las métricas. Un perfil de usuario necesita los detalles de la cuenta. La pregunta no es si vas a obtener datos — sino dónde y cuándo lo harás, y qué sucede mientras esperas.

SvelteKit tiene una respuesta específica y bien razonada a esa pregunta: la función load. Antes de que se renderice un componente de página, SvelteKit te brinda un lugar dedicado para obtener todo lo que esa página necesita, y garantiza que los datos estarán listos antes de que cualquier marcado aparezca en pantalla. Esto no es un middleware agregado a último momento ni un hook de ciclo de vida que tienes que recordar llamar — es una parte fundamental de cómo funcionan las rutas en SvelteKit.

Este artículo cubre qué son las funciones load, por qué el framework fue diseñado en torno a ellas y cómo escribir una correctamente desde el principio. Al final tendrás un entendimiento completo de las convenciones de archivos involucradas, cómo fluyen los datos desde una función load hacia tu componente de página, y cómo los tipos de TypeScript generados por SvelteKit hacen que todo sea completamente type-safe sin ningún esfuerzo manual.

Una decisión deliberada aplica a todos los artículos de esta serie: no aparecen ORMs, query builders ni bibliotecas cliente de bases de datos en ningún ejemplo de código. Todo acceso a datos se expresa mediante llamadas fetch de SvelteKit a endpoints de API.

Esto mantiene cada ejemplo independiente de la base de datos — los patrones funcionan de manera idéntica ya sea que tu backend use PostgreSQL, SQLite, MongoDB, una API REST de terceros o cualquier otra cosa. El enfoque está en cómo funcionan las funciones load de SvelteKit, no en ninguna capa de datos en particular que esté detrás de ellas.

Si usas Prisma, Drizzle o una herramienta similar en tu propia aplicación, la estructura de la función load es idéntica; la única diferencia es lo que va dentro del cuerpo de la función.

El Problema

Para apreciar lo que resuelven las funciones load, conviene pensar en las alternativas.

El enfoque más obvio, y al que suelen recurrir primero los desarrolladores que vienen de frameworks del lado del cliente, es obtener datos dentro del propio componente. Defines algún estado reactivo, inicias una solicitud fetch cuando el componente se monta y actualizas el estado cuando llegan los datos. Mientras tanto, renderizas un spinner de carga o una pantalla skeleton.

<!-- src/routes/articles/[slug]/+page.svelte -->
<!-- This pattern works, but it has real costs. -->

<script lang="ts">
	import { onMount } from 'svelte'

	let article = $state<Article | null>(null)
	let loading = $state(true)
	let error = $state<string | null>(null)

	onMount(async () => {
		try {
			const res = await fetch(`/api/articles/${slug}`)
			article = await res.json()
		} catch (e) {
			error = 'Failed to load article'
		} finally {
			loading = false
		}
	})
</script>

{#if loading}
	<p>Loading...</p>
{:else if error}
	<p>{error}</p>
{:else}
	<h1>{article?.title}</h1>
{/if}

Este patrón funciona, pero tiene costos reales en una aplicación renderizada en el servidor. onMount nunca se ejecuta durante el SSR, solo se ejecuta en el navegador. Esto significa que el servidor inicialmente devuelve HTML sin el contenido del artículo, el cliente renderiza un estado de carga y solo después de la hidratación ocurre el fetch y la página finalmente se completa.

El resultado es una peor experiencia para los usuarios (una transición visible de "vacío → cargando → contenido") y peores resultados para el SEO y las vistas previas en redes sociales (el HTML inicial carece del contenido significativo). También pagas latencia adicional porque los datos se recuperan después de que la página ya fue entregada.

Un "siguiente paso" común es introducir endpoints +server.ts y hacer fetch desde el componente. Eso puede ser apropiado cuando realmente necesitas una API pública, pero como estrategia predeterminada de carga de datos suele ser una sobrecarga innecesaria: estás construyendo y manteniendo un endpoint HTTP principalmente para que tu propio frontend pueda llamar de vuelta a tu propio backend. En otras palabras, has creado un salto extra como navegador → tu servidor → fuente de datos original, aunque el servidor podría haber cargado los datos antes de renderizar.

Ambos enfoques comparten el mismo problema subyacente: los datos se obtienen reactivamente (después de que el componente se ha montado) en lugar de declarativamente (como requisito previo para el renderizado).

reactivamente: El componente se renderiza primero, luego obtiene los datos y se actualiza cuando llegan. Este es el patrón predeterminado en frameworks del lado del cliente y funciona bien para aplicaciones puramente renderizadas en el cliente, pero puede sentirse lento y brusco, especialmente en conexiones más lentas. También significa que el HTML inicial enviado por el servidor está incompleto, lo que perjudica el SEO y las vistas previas en redes sociales.

declarativamente: El componente declara qué datos necesita, y el framework garantiza que esos datos estén disponibles antes de que el componente se renderice. Este es el patrón que SvelteKit fomenta con las funciones load. Conduce a un rendimiento percibido más rápido, mejor SEO y una experiencia de usuario más fluida.

Las funciones load de SvelteKit obtienen lo que la ruta necesita de antemano y luego renderizan la página con datos completos desde el inicio.

Principios

SvelteKit organiza tu aplicación en rutas, y cada ruta es un directorio dentro de src/routes. Un directorio de ruta puede contener varios archivos especiales que SvelteKit trata con un significado específico. Probablemente ya estás familiarizado con +page.svelte, que contiene el componente que se renderiza para esa ruta.

La idea clave es que +page.svelte no es el único archivo que puede tener una ruta. SvelteKit admite un archivo complementario llamado +page.js (o +page.ts para TypeScript) que reside junto a él. Este archivo tiene una sola tarea: exportar una función load que obtiene o deriva los datos que la página necesita. SvelteKit llamará a esa función antes de renderizar el componente, esperará a que se resuelva y luego pasará su valor de retorno al componente como una prop data.

El flujo se ve así:

No hay conexión manual. No llamas a la función load tú mismo, no te suscribes a ningún store ni pasas datos a través de props entre límites de componentes. SvelteKit gestiona la conexión entre la función load y el componente de forma automática, usando la convención de nomenclatura de archivos como contrato.

Este modelo tiene una consecuencia importante para el renderizado en el servidor. Cuando un usuario carga una página por primera vez, la función load se ejecuta en el servidor. El componente recibe los datos completamente resueltos y renderiza HTML completo. Cuando el usuario navega a otra página dentro de la app, la función load se ejecuta en el navegador en su lugar, obteniendo solo los datos necesarios para esa nueva ruta sin recargar la página completa. Escribes la función una vez, y SvelteKit decide dónde ejecutarla según el contexto.

Implementación

Paso 1: Crear la Estructura de Rutas

La convención de emparejamiento de archivos es lo que hace que todo funcione, por lo que vale la pena ser preciso al respecto. Para una ruta en /articles/[slug], necesitas dos archivos en el mismo directorio:

src/
└── routes/
    └── articles/
        └── [slug]/
            ├── +page.ts       ← the load function lives here
            └── +page.svelte   ← the component renders here

La relación entre los dos archivos es simple: +page.ts se ejecuta primero y le pasa sus datos a +page.svelte. SvelteKit los conecta automáticamente mediante la nomenclatura de archivos — sin importación, sin llamada explícita, sin suscripción a un store.

El nombre del directorio [slug] es un segmento dinámico. SvelteKit capturará lo que aparezca en esa posición en la URL y lo pondrá a disposición dentro de tu función load a través del objeto params. Si la URL es /articles/building-with-sveltekit, entonces params.slug será 'building-with-sveltekit'.

Paso 2: Escribir la Función Load

Una función load es una exportación nombrada del archivo +page.ts. Recibe un único argumento que SvelteKit completa con información de contexto sobre la solicitud actual, y retorna un objeto plano que contiene los datos que la página necesita.

Aquí hay un primer ejemplo realista de cómo obtener un artículo desde una API de CMS:

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

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

export const load: PageLoad = async ({ params, fetch }) => {
	const response = await fetch(`https://cms.example.com/api/articles/${params.slug}`)

	if (!response.ok) {
		// We will cover proper error handling in a later article.
		// error() signals a controlled failure and renders the nearest +error.svelte.
		error(response.status, `Failed to fetch article: ${response.status}`)
	}

	const article = await response.json()

	return {
		article
	}
}

Hay varias cosas que vale la pena examinar con detenimiento en este código.

params

El objeto params está tipado en función de los segmentos dinámicos de tu ruta. Para esta ruta, TypeScript te indicará que params.slug es un string. Si tuvieras una ruta como /shop/[category]/[productId], tanto params.category como params.productId estarían disponibles y tipados.

El valor de retorno es un objeto plano. Todo lo que pongas aquí estará disponible en el componente de página. No estás limitado a una sola clave; devolver múltiples valores es común y se recomienda sobre crear múltiples funciones load separadas.

fetch

El fetch usado aquí no es el fetch nativo del navegador. Es una versión especial que SvelteKit provee a través del argumento del evento load. Siempre deberías usar este en lugar de llamar al fetch global directamente.

La versión de SvelteKit puede hacer solicitudes relativas en el servidor (el fetch nativo no puede), hereda las cookies del usuario actual para que las solicitudes con credenciales funcionen correctamente y, durante el renderizado en el servidor, captura la respuesta y la incorpora directamente en el HTML para que el navegador no tenga que hacer la misma solicitud nuevamente durante la hidratación.

Usar el fetch global en lugar del que provee SvelteKit es un error común en código SvelteKit temprano, y rompe la consistencia de la hidratación de formas que pueden ser sutiles de depurar.

Paso 3: Acceder a los Datos en el Componente de Página

Una vez que la función load retorna, SvelteKit hace que su valor de retorno esté disponible en +page.svelte a través de una prop llamada data. Accedes a ella usando $props(), que es la runa de Svelte 5 para declarar props.

<!-- src/routes/articles/[slug]/+page.svelte -->

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

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

<article>
	<h1>{data.article.title}</h1>
	<p class="meta">Published {data.article.publishedAt}</p>
	<div class="content">
		<!-- data.article.content is sanitised server-side before storage -->
		{@html data.article.content}
	</div>
</article>

El tipo PageProps es generado automáticamente por SvelteKit a partir de tu archivo +page.ts. Sabe exactamente qué forma tiene data porque puede ver qué retorna tu función load. Esto significa que data.article está completamente tipado — obtienes autocompletado, verificación de tipos y soporte de refactorización para toda la cadena desde la función load hasta la plantilla, todo sin escribir manualmente ni una sola interfaz para la forma de los datos.

Esta generación de tipos ocurre a través de la importación ./$types, que apunta a un archivo en el directorio oculto .svelte-kit/types de SvelteKit. Nunca necesitas ver ni editar este archivo. SvelteKit lo regenera cada vez que guardas, y tu IDE lo lee automáticamente.

Paso 4: Entender el Sistema de Tipos

SvelteKit genera varios alias de tipo para cada ruta, y vale la pena tomarse un momento para saber cuál usar en cada caso.

PageLoad

PageLoad es el tipo de la función load en sí. Lo usas para tipar la exportación load en +page.ts. Garantiza que los argumentos que SvelteKit pasa — params, fetch, url y los demás — estén todos correctamente tipados para tu ruta específica.

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

// PageLoad types the load function and its arguments
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params }) => {
	// params.slug is typed as string because of the [slug] route segment
	return { slug: params.slug }
}

PageProps

PageProps es el tipo de las props que recibe +page.svelte. Incluye una propiedad data cuyo tipo se infiere de lo que retorna tu función PageLoad. Lo usas para tipar las props desestructuradas en la llamada $props() de tu componente.

<!-- src/routes/articles/[slug]/+page.svelte -->

<script lang="ts">
	// PageProps types the component's incoming data prop
	import type { PageProps } from './$types'

	let { data }: PageProps = $props()
	// data.slug is typed as string — inferred from the load function's return
</script>

Si estás en una versión antigua de SvelteKit (anterior a la 2.16.0), PageProps no existía y tenías que tipar los datos por separado usando PageData. El patrón se veía así: let { data }: { data: PageData } = $props(). Si encuentras esto en código antiguo, es funcionalmente equivalente — solo más verboso.

Errores Comunes y Anti-Patrones

Usar el fetch Global en Lugar del fetch de la Función Load

Este es, con diferencia, el error más frecuente en código SvelteKit temprano. El fetch global y el fetch de load de SvelteKit se ven idénticos en el punto de llamada, lo que hace que el error sea fácil de pasar por alto.

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

// AVOID: Using the global fetch
export const load: PageLoad = async ({ params }) => {
	const res = await fetch(`/api/products/${params.id}`)
	return { product: await res.json() }
}

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

// PREFERRED: Using the fetch provided by the load event
export const load: PageLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/products/${params.id}`)
	return { product: await res.json() }
}

El fetch global tiene tres problemas en el contexto de una función load.

No puede hacer solicitudes con URL relativas en el servidor — tendrías que proporcionar el origen completo, lo cual es difícil de construir correctamente.
No hereda las cookies de sesión del usuario, por lo que cualquier solicitud autenticada fallará o devolverá datos para un usuario anónimo.
SvelteKit no puede interceptarlo para incorporar la respuesta en el HTML renderizado en el servidor, lo que significa que el navegador hará una segunda solicitud idéntica durante la hidratación. El fetch provisto maneja los tres casos correctamente sin configuración adicional.

Obtener Datos en el Componente en Lugar de en la Función Load

Es tentador hacer un fetch secundario pequeño dentro del componente, especialmente para datos que se sienten "menos importantes" como una barra lateral de artículos relacionados, un conteo de comentarios o una biografía del autor. El problema es que cualquier fetch dentro del componente se ejecuta después de que el componente se monta, lo que significa que un estado de carga es inevitable y los datos no están disponibles para el renderizado en el servidor.

<!-- AVOID: Fetching inside the component -->

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

	let { data }: PageProps = $props()

	// This will not render on the server and creates a loading flash
	let relatedArticles = $state<Article[]>([])
	onMount(async () => {
		const res = await fetch(`/api/articles/related/${data.article.id}`)
		relatedArticles = await res.json()
	})
</script>

// PREFERRED: Return everything from the load function

// src/routes/articles/[slug]/+page.ts
export const load: PageLoad = async ({ params, fetch }) => {
	const [articleRes, relatedRes] = await Promise.all([
		fetch(`https://cms.example.com/api/articles/${params.slug}`),
		fetch(`https://cms.example.com/api/articles/${params.slug}/related`)
	])

	return {
		article: await articleRes.json(),
		relatedArticles: await relatedRes.json()
	}
}

La versión correcta usa Promise.all para obtener ambos datos de forma concurrente, de modo que no hay penalización por cascada. Ambos conjuntos de datos están disponibles de inmediato cuando el componente se renderiza, incluso durante el renderizado en el servidor. Cubriremos los detalles más finos de la carga en paralelo en un artículo posterior.

Olvidar Usar $types para la Seguridad de Tipos

Es posible escribir una función de carga sin importar PageLoad en absoluto; TypeScript inferirá algunos tipos y el código funcionará. Pero se pierde la garantía de que el tipo de retorno de tu función de carga coincida con lo que el componente espera, y se pierde el tipado preciso en los argumentos del evento de carga como params.

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

// WEAK: No explicit typing — TypeScript will infer loosely
export async function load({ params, fetch }) {
	const res = await fetch(`/api/articles/${params.slug}`)
	return { article: await res.json() }
}

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

// PREFERRED: Explicit PageLoad type — params.slug is typed, return is tracked
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/articles/${params.slug}`)
	return { article: await res.json() }
}

Siempre importa desde ./$types. Se genera para tu ruta específica y proporciona el tipado más estricto posible. Omitirlo puede parecer un pequeño atajo, pero rompe la cadena de seguridad de tipos de extremo a extremo que hace que la refactorización y el mantenimiento sean significativamente más seguros en aplicaciones más grandes.

Consideraciones de Rendimiento y Escalabilidad

Las funciones de carga están diseñadas para el rendimiento desde el principio, pero hay algunos patrones a tener en cuenta a medida que tu aplicación crece.

SvelteKit rastrea a qué accede cada función de carga, específicamente qué propiedades de params y url lee, y usa esa información para decidir si la función necesita ejecutarse nuevamente durante la navegación del lado del cliente. Si navegas de una entrada de blog a otra, SvelteKit sabe que params.slug cambió, por lo que vuelve a ejecutar la función de carga de la página.

Pero si navegas entre diferentes secciones del sitio que comparten el mismo layout, la función de carga del layout solo se vuelve a ejecutar si los datos de los que depende han cambiado. Este rastreo de dependencias es automático y no requiere configuración, pero significa que debes acceder exactamente a las propiedades de params y url que necesitas. No desestructures todo desde url si solo necesitas url.pathname, ya que las lecturas innecesarias crean dependencias innecesarias.

Para las llamadas fetch en sí, SvelteKit desduplica las solicitudes durante el renderizado del lado del servidor. Si tu función de carga y la función de carga de un layout ambas hacen fetch a la misma URL, SvelteKit solo realizará la solicitud de red una vez. Esta desduplicación depende de que el fetch mejorado se use de manera consistente, lo que significa otra razón por la que el fetch global es problemático.

A medida que tus funciones de carga crecen en complejidad y retornan más datos, la inferencia de TypeScript a través del límite de $types sigue siendo rápida porque los tipos generados son tipos de objeto simples, no genéricos condicionales complejos. Incluso los objetos de retorno muy grandes verifican sus tipos de manera eficiente.

Cuándo NO Usar Este Patrón

Las funciones de carga son la herramienta correcta para los datos que la página necesita antes de poder renderizar su contenido principal. No siempre son la herramienta correcta para cada pieza de datos en una aplicación.

Los datos que cambian en tiempo real, como un ticker de acciones en vivo, un feed de mensajes de chat o un indicador de presencia, no pertenecen a una función de carga porque las funciones de carga se ejecutan una vez por navegación, no de manera continua. Este tipo de datos se maneja mejor mediante una conexión WebSocket o un flujo de Server-Sent Events administrado dentro del componente.

Los datos que dependen de la interacción del usuario en lugar de los parámetros de ruta también son una mala opción. Si el usuario está filtrando una lista haciendo clic en chips, aplicar ese filtro a través de una función de carga requeriría un evento de navegación por cada clic. Eso es demasiado pesado; el filtrado del lado del cliente de datos ya cargados, o una API de búsqueda llamada desde dentro del componente, maneja esto de manera más natural.

También existe una distinción significativa entre +page.ts y +page.server.ts que este artículo ha postergado intencionalmente. La función de carga que se muestra aquí se ejecuta tanto en el servidor como en el navegador, lo cual está bien para las APIs públicas que no requieren credenciales ni variables de entorno privadas. Si tu función de carga necesita acceder directamente a una base de datos, leer un secreto exclusivo del servidor o inspeccionar una cookie de sesión, pertenece a +page.server.ts. Esa distinción entre carga universal versus carga de servidor es el tema del próximo artículo de esta serie.

Conclusión

Las funciones de carga son la respuesta de SvelteKit a una pregunta que toda aplicación web debe responder: ¿cuándo y dónde se obtienen los datos? Al hacer que la función de carga sea un par del componente de página, con un contrato claro entre ellos y la generación automática de tipos que los conecta, SvelteKit convierte la obtención de datos de un efecto secundario imperativo en un prerequisito declarativo del renderizado.

El resultado práctico son páginas que llegan completamente renderizadas, sin destellos de carga en la primera visita, sin discrepancias de hidratación, y un sistema de tipos que valida todo el pipeline de datos desde el servidor hasta la plantilla sin ninguna escritura manual de tipos. La convención de archivos de +page.ts junto a +page.svelte hace que la relación sea visible de un vistazo en cualquier explorador de archivos.

Comprender esta base a fondo hace que cada tema más avanzado en el sistema de carga de datos de SvelteKit sea más fácil de razonar, porque todo se construye sobre el mismo modelo básico: funciones que se ejecutan antes de que la página se renderice, retornan objetos simples y entregan esos datos directamente al componente.

Puntos Clave

La función de carga es una exportación nombrada desde +page.ts (o +page.js) que SvelteKit llama automáticamente antes de renderizar el componente +page.svelte emparejado. Su valor de retorno se convierte en la prop data del componente, tipada de extremo a extremo por los tipos generados PageLoad y PageProps desde ./$types.

Siempre usa el fetch proporcionado por el argumento del evento de carga en lugar del fetch global. La versión proporcionada maneja URLs relativas en el servidor, hereda las cookies del usuario para solicitudes autenticadas, y se integra con el sistema de hidratación de SvelteKit para prevenir solicitudes de red duplicadas.

Las funciones de carga se ejecutan en el servidor durante el SSR y en el navegador durante la navegación del lado del cliente. Esta ejecución en doble entorno es lo que hace que el patrón funcione, lo que significa que el mismo código produce HTML renderizado en el servidor para las primeras visitas y actualizaciones rápidas de solo datos para la navegación posterior.

Qué Sigue

Ahora que entiendes cómo una sola página carga sus datos, la siguiente pregunta natural es sobre el alcance. ¿Qué sucede cuando múltiples páginas en una sección de tu aplicación necesitan los mismos datos, como un menú de navegación, un objeto de usuario, un conjunto de permisos? Eso es lo que resuelven las funciones de carga de layout, y siguen exactamente el mismo patrón que las funciones de carga de página con una diferencia importante en cómo se comparten sus datos. El próximo artículo de esta serie, Datos de Página vs Datos de Layout, cubre exactamente eso.

Lectura Adicional

Enrutamiento de SvelteKit — comprendiendo las convenciones de archivos de las que forman parte las funciones de carga
Documentación Oficial de Carga de SvelteKit — la referencia oficial para todas las opciones de funciones de carga