Por Qué el Evento Load Proporciona Su Propio fetch

Cada función load de SvelteKit recibe un objeto event, y entre sus propiedades hay una que parece demasiado familiar como para merecer una segunda mirada: fetch. Es una función que realiza solicitudes HTTP. Ya sabes cómo usarla. ¿Qué podría haber que explicar?

Bastante, resulta ser.

El fetch proporcionado por el evento load no es el fetch nativo del navegador. Es una versión especializada construida por SvelteKit que incorpora cinco capacidades distintas que no están presentes en la versión global. Usar el fetch global dentro de una función load no es solo un error estilístico. En algunos escenarios produce un comportamiento incorrecto. En otros, socava silenciosamente lo mismo que SvelteKit intenta hacer por ti: entregar una página completamente renderizada en la primera solicitud sin actividad de red redundante.

Este artículo construye una comprensión precisa de por qué SvelteKit reemplaza fetch, qué hace cada una de esas cinco capacidades, y cómo interactúan en una aplicación real. También cubre la distinción entre obtener datos de APIs externas y de tus propias rutas internas +server.ts, porque esos dos escenarios tienen características diferentes que vale la pena entender. Al final tendrás un modelo mental claro de lo que le sucede a una llamada fetch desde el momento en que una función load se ejecuta en el servidor hasta el momento en que la misma página se vuelve interactiva en el navegador.

Lo Que el fetch Global No Puede Hacer

Para entender por qué SvelteKit necesita su propio fetch, considera lo que sucede cuando un usuario navega a una página que carga datos.

En el servidor, SvelteKit ejecuta tu función load, llama a cualquier solicitud fetch dentro de ella, ensambla los datos resultantes, renderiza el árbol de componentes a HTML y envía el resultado al navegador. El navegador recibe una página completamente formada y la muestra de inmediato. Esa es la promesa del SSR: primera pintura rápida, contenido visible antes de que JavaScript se ejecute.

Luego llega el paquete de JavaScript. SvelteKit necesita hidratar la página, convirtiendo el HTML estático en una aplicación Svelte viva e interactiva. La hidratación requiere que el árbol de componentes del lado del cliente coincida exactamente con el HTML renderizado en el servidor. Si los datos usados durante la hidratación difieren de los datos usados durante el renderizado del servidor, obtienes un desajuste.

Ahora considera qué sucede si tu función load usa el fetch global nativo durante el SSR. El servidor obtiene los datos, renderiza el HTML con ellos y envía ese HTML al navegador. Cuando el paquete del cliente se ejecuta e intenta hidratar, necesita esos mismos datos. Si vuelve a ejecutar la función load para obtenerlos, eso significa otra solicitud de red desde el navegador. Dos solicitudes para los mismos datos: una en el servidor, otra en el cliente. Ese es el problema de la doble solicitud.

Incluso ignorando la hidratación, el fetch nativo en el servidor no sabe nada sobre el enrutamiento interno de SvelteKit. Una URL relativa como /api/products no significa nada en Node.js, donde no existe el concepto de un origen actual. Tendrías que codificar de forma fija una URL absoluta, lo cual es frágil en desarrollo o requiere inyectar variables de entorno para el host actual. Y si ese endpoint /api/products es uno de tus propios archivos +server.ts, estarías haciendo una solicitud HTTP real a ti mismo cuando SvelteKit podría simplemente llamar al manejador directamente sin tocar jamás la red.

Estos son los problemas que resuelve el fetch de SvelteKit. Cada uno corresponde a una capacidad distinta.

Cómo Funciona

Antes de recorrer cada capacidad, ayuda entender dónde se encuentra fetch en el ciclo de vida de la función load.

Una función load es fundamentalmente una función de adquisición de datos. SvelteKit la llama en el momento correcto, en el contexto correcto, con las herramientas correctas. El objeto event de la función load agrupa todo lo que la función necesita: parámetros de ruta, información de URL, cookies, los datos del layout padre, el entorno de la plataforma y fetch. No importas fetch ni lo instancias. Lo desestructuras del event.

// The fetch you use comes from the event, not from the global scope.
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/articles/${params.slug}`)
	const article = await response.json()
	return { article }
}

Esto es intencional. SvelteKit controla el tiempo de vida de esa instancia de fetch. Sabe cuándo se llamó a la función load, si se está ejecutando en el servidor o en el cliente, y qué solicitudes ya se han realizado. Ese contexto es lo que habilita las cinco capacidades.

Cuando el navegador recibe la página, los datos serializados ya están integrados en el HTML. El runtime de SvelteKit del lado del cliente lee esos datos de la página en lugar de volver a solicitarlos. Las funciones load se ejecutan solo una vez para la solicitud inicial.

Los Cinco Superpoderes de event.fetch

Los cinco superpoderes son lo suficientemente distintos como para que cada uno merezca su propia sección, pero ayuda verlos juntos primero antes de profundizar en cada uno.

SP1: Las URLs Relativas Se Resuelven Correctamente

En el servidor, no existe el concepto de un origen de página actual. Node.js no sabe en qué hostname se está ejecutando tu aplicación. Si usas fetch nativo con una URL relativa dentro de una función load durante el SSR, obtienes un error porque el fetch integrado de Node requiere URLs absolutas.

El fetch de SvelteKit resuelve automáticamente las URLs relativas contra el origen de la solicitud actual. La URL /api/products se convierte en http://localhost:5173/api/products en desarrollo y en https://yourdomain.com/api/products en producción, sin ninguna configuración de tu parte.

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

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

export const load: PageServerLoad = async ({ fetch }) => {
	// This works on the server. SvelteKit resolves it against
	// the current request origin. Native fetch would throw here
	// because '/api/products' is not a valid absolute URL in Node.
	const response = await fetch('/api/products')

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

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

Esto significa que escribes la misma URL en desarrollo y en producción. Nunca concatenas process.env.ORIGIN con una ruta. La URL que escribes en la función load es la misma URL que un navegador usaría para llegar al mismo endpoint, lo cual es un modelo mental natural y consistente.

SP2: Las Credenciales Fluyen Automáticamente

La autenticación en SvelteKit típicamente involucra una cookie de sesión. El navegador envía esta cookie con cada solicitud automáticamente, pero en el servidor, cuando realizas una llamada fetch dentro de una función load, esa cookie no está presente en la llamada fetch a menos que la reenvíes explícitamente.

El fetch de SvelteKit reenvía las cookies y los encabezados de autorización de la solicitud entrante a las llamadas fetch del mismo origen dentro de las funciones load. Esto significa que tus endpoints de API reciben el mismo contexto de autenticación que la solicitud de página original, sin necesidad de extracción manual de cookies ni reenvío de encabezados.

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

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

export const load: PageServerLoad = async ({ fetch }) => {
	// SvelteKit forwards the session cookie from the original
	// browser request to this fetch call automatically.
	// The /api/account endpoint can read it and verify the session.
	const response = await fetch('/api/account/profile')

	if (response.status === 401) {
		// Session missing or expired. Return null rather than throwing
		// here so the page can render a login prompt.
		return { profile: null }
	}

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

Este reenvío automático de credenciales solo aplica a las solicitudes del mismo origen. Cuando haces fetch desde una API externa en un dominio diferente, no se reenvían cookies ni encabezados de autorización. Ese es el comportamiento correcto: no querrías que tus cookies de sesión se enviaran a un servicio de terceros.

Si necesitas autenticar una solicitud de origen cruzado, proporcionas las credenciales explícitamente en la llamada fetch, exactamente como lo harías con el fetch nativo.

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

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

export const load: PageServerLoad = async ({ params, fetch }) => {
	// Cross-origin request to an external API.
	// No cookies are forwarded. Credentials are supplied explicitly.
	const weatherUrl = new URL('https://api.openweathermap.org/data/2.5/weather')
	weatherUrl.searchParams.set('q', params.city)
	weatherUrl.searchParams.set('appid', WEATHER_API_KEY)

	const response = await fetch(weatherUrl.toString())

	if (!response.ok) {
		return { weather: null }
	}

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

SP3: Las Rutas Internas Se Omiten

Cuando haces fetch a una URL que coincide con uno de tus propios endpoints +server.ts de SvelteKit, SvelteKit no realiza una solicitud HTTP real. Llama a la función del manejador de rutas directamente, en proceso, sin tocar la red.

Esto importa de dos maneras. Primero, elimina un viaje de red innecesario: la serialización, transmisión y deserialización de datos que ya estaban en memoria. Segundo, significa que tus endpoints de API internos pueden usar importaciones exclusivas del servidor como $env/static/private y utilidades internas, y esas importaciones permanecen seguras incluso cuando la llamada fetch parece una solicitud de red desde el exterior.

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

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

export const GET: RequestHandler = async ({ params }) => {
	// This handler is called directly when fetched from within the app.
	// It is also callable as a real HTTP endpoint from external clients.
	const response = await fetch(`https://cms.example.com/api/articles/${params.slug}`, {
		headers: { Authorization: `Bearer ${CMS_TOKEN}` }
	})

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

	const article = await response.json()
	return json(article)
}

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

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

export const load: PageServerLoad = async ({ params, fetch }) => {
	// SvelteKit calls the +server.ts handler directly.
	// No HTTP request is made. The handler runs as a function call.
	const response = await fetch(`/api/articles/${params.slug}`)

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

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

Este diseño te permite construir tus propias rutas de API como endpoints HTTP reales y llamables que los clientes externos o las aplicaciones móviles pueden usar, mientras también los usas internamente desde las funciones load sin ninguna penalización de rendimiento. Obtienes una superficie de API limpia y acceso eficiente a los datos internos desde el mismo archivo de manejador de rutas.

SP4: Las Respuestas Se Capturan para la Hidratación

Esta es la capacidad que previene el problema de la doble solicitud.

Cuando una función load se ejecuta durante el SSR y llama a event.fetch, SvelteKit captura la respuesta. Serializa los datos de esa respuesta y los integra en la página HTML enviada al navegador, dentro de un bloque script que SvelteKit lee durante la hidratación.

Cuando el navegador carga la página y el paquete de JavaScript se ejecuta, el runtime del lado del cliente de SvelteKit intercepta cualquier llamada a event.fetch que reproduciría una solicitud ya realizada en el servidor. En lugar de hacer una solicitud de red real, lee la respuesta capturada de los datos de página integrados.

La consecuencia práctica es que el código de tu función load es el mismo en ambos entornos. No escribes rutas separadas de obtención de datos del lado del servidor y del lado del cliente. Escribes una función load, y SvelteKit maneja la diferencia de forma transparente.

// src/routes/blog/[slug]/+page.ts
// This is a universal load function (no .server). It runs on the server
// for the initial request and on the client during subsequent navigations.

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

export const load: PageLoad = async ({ params, fetch }) => {
	// During SSR: SvelteKit makes the request and captures the response.
	// During client navigation: SvelteKit makes the request from the browser.
	// During hydration of an SSR page: SvelteKit uses the captured response.
	// The code here is identical in all three scenarios.
	const response = await fetch(`/api/articles/${params.slug}`)

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

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

Si usas el fetch global aquí en lugar de event.fetch, la intercepción de hidratación no ocurrirá. El cliente haría una solicitud de red real, la página se volvería a renderizar momentáneamente con los datos recién obtenidos y, si esos datos difieren de lo que se renderizó en el servidor, obtienes un desajuste de hidratación. El fetch global omite todo el mecanismo de captura del SSR.

SP5: Fetch Es Consciente del Entorno

La quinta capacidad es menos dramática pero vale la pena nombrarla explícitamente: el fetch de SvelteKit funciona correctamente en todos los entornos donde se ejecutan las funciones load, sin ninguna modificación.

En Node.js ejecutando un servidor de producción, maneja la ausencia de un fetch global nativo. En el navegador, delega al fetch nativo del navegador pero con la capa de intercepción para la hidratación. En Vitest o pruebas de Playwright, puede ser simulado o interceptado de forma uniforme. En Cloudflare Workers u otros entornos edge, respeta la implementación de fetch de la plataforma.

No necesitas detectar el entorno, importar polyfills ni escribir lógica condicional. La misma llamada a event.fetch funciona en todos los lugares donde se ejecuta tu función load.

Obtener Datos de APIs Externas vs Rutas Internas

La distinción entre obtener datos de una API externa y obtener datos de tus propias rutas de SvelteKit merece atención explícita porque los dos escenarios tienen características diferentes.

Las APIs externas son endpoints HTTP reales en diferentes servidores. El stack de red completo está involucrado: resolución DNS, conexiones TCP, handshakes TLS, serialización de solicitudes, transmisión, deserialización de respuestas. Para las llamadas a API externas, gestionas la autenticación con encabezados explícitos, manejas la limitación de velocidad, lidias con errores de red y analizas el formato de respuesta que el propietario de la API define.

Las rutas internas son tus propios manejadores +server.ts. Como se describió anteriormente en SP3, SvelteKit omite la red para estas. La función del manejador se llama directamente. Los objetos de solicitud y respuesta se construyen en memoria. La única serialización involucrada es la codificación y decodificación JSON que realizas en el propio manejador.

Una consecuencia práctica de esta distinción: cuando necesitas datos de un servicio externo, colocar una ruta +server.ts frente a él crea una capa útil donde puedes normalizar la respuesta, manejar errores de forma uniforme, inyectar autenticación sin exponer claves de API al cliente y almacenar resultados en caché.

// src/routes/api/github/repos/+server.ts
// Acts as a thin adapter between external GitHub API and internal consumers.

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

interface GitHubRepo {
	id: number
	name: string
	full_name: string
	description: string | null
	stargazers_count: number
	language: string | null
	html_url: string
}

interface NormalizedRepo {
	id: number
	name: string
	description: string
	stars: number
	language: string
	url: string
}

export const GET: RequestHandler = async ({ url }) => {
	const username = url.searchParams.get('username')

	if (!username) {
		error(400, 'username query parameter is required')
	}

	const response = await fetch(
		`https://api.github.com/users/${username}/repos?per_page=10&sort=stars`,
		{
			headers: {
				Authorization: `Bearer ${GITHUB_TOKEN}`,
				Accept: 'application/vnd.github.v3+json'
			}
		}
	)

	if (!response.ok) {
		error(response.status, `GitHub API error: ${response.statusText}`)
	}

	const repos: GitHubRepo[] = await response.json()

	// Normalize to a stable internal shape. If GitHub changes their API,
	// only this file needs to change.
	const normalized: NormalizedRepo[] = repos.map((repo) => ({
		id: repo.id,
		name: repo.name,
		description: repo.description ?? 'No description provided',
		stars: repo.stargazers_count,
		language: repo.language ?? 'Unknown',
		url: repo.html_url
	}))

	return json(normalized)
}

// src/routes/profile/[username]/+page.server.ts

import type { PageServerLoad } from './$types'
import type { NormalizedRepo } from '$lib/types'

export const load: PageServerLoad = async ({ params, fetch }) => {
	// Fetches from our internal adapter route, not directly from GitHub.
	// GITHUB_TOKEN never reaches this file or the browser.
	// The response is the NormalizedRepo shape we control.
	const response = await fetch(`/api/github/repos?username=${params.username}`)

	if (!response.ok) {
		return { repos: [] as NormalizedRepo[] }
	}

	const repos: NormalizedRepo[] = await response.json()
	return { repos }
}

Este patrón mantiene las claves de API exclusivas del servidor, te da un único lugar para actualizar cuando la API externa cambia, y permite que la función load trabaje con una forma que tú diseñaste en lugar de una forma impuesta por un tercero.

Ejemplo Práctico: Obtener Datos de una API JSON Tipada

El siguiente es un ejemplo completo y funcional que combina las cinco capacidades. Modela una página de listado de productos que obtiene datos de una ruta interna, tipifica la respuesta correctamente usando TypeScript, maneja los errores con elegancia y funciona correctamente a través del SSR, la hidratación y la navegación del cliente.

Definiendo los tipos compartidos

// src/lib/types/product.ts

export interface Product {
	id: string
	name: string
	price: number
	category: string
	inStock: boolean
	imageUrl: string
}

export interface ProductListResponse {
	products: Product[]
	total: number
	page: number
	pageSize: number
}

La ruta de API interna

// src/routes/api/products/+server.ts

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

// Simulates a data source. In a real application this would query
// whatever data store your application uses.
const PRODUCTS: Product[] = [
	{
		id: '1',
		name: 'Mechanical Keyboard',
		price: 149,
		category: 'peripherals',
		inStock: true,
		imageUrl: '/images/keyboard.jpg'
	},
	{
		id: '2',
		name: 'Curved Monitor',
		price: 549,
		category: 'displays',
		inStock: true,
		imageUrl: '/images/monitor.jpg'
	},
	{
		id: '3',
		name: 'Ergonomic Chair',
		price: 399,
		category: 'furniture',
		inStock: false,
		imageUrl: '/images/chair.jpg'
	},
	{
		id: '4',
		name: 'USB-C Hub',
		price: 79,
		category: 'peripherals',
		inStock: true,
		imageUrl: '/images/hub.jpg'
	},
	{
		id: '5',
		name: 'Webcam 4K',
		price: 199,
		category: 'peripherals',
		inStock: true,
		imageUrl: '/images/webcam.jpg'
	},
	{
		id: '6',
		name: 'Standing Desk',
		price: 699,
		category: 'furniture',
		inStock: true,
		imageUrl: '/images/desk.jpg'
	}
]

const PAGE_SIZE = 3

export const GET: RequestHandler = async ({ url }) => {
	const category = url.searchParams.get('category')
	const pageParam = url.searchParams.get('page')
	const page = Math.max(1, parseInt(pageParam ?? '1', 10) || 1)

	let filtered = category ? PRODUCTS.filter((p) => p.category === category) : PRODUCTS

	const total = filtered.length
	const start = (page - 1) * PAGE_SIZE
	const products = filtered.slice(start, start + PAGE_SIZE)

	if (page > 1 && products.length === 0) {
		error(404, 'No products found for this page')
	}

	const result: ProductListResponse = {
		products,
		total,
		page,
		pageSize: PAGE_SIZE
	}

	return json(result)
}

La función load

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

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

export const load: PageServerLoad = async ({ url, fetch }) => {
	const category = url.searchParams.get('category')
	const page = url.searchParams.get('page') ?? '1'

	// Build the internal API URL, forwarding the same query parameters
	// the user supplied to the page URL.
	const apiUrl = new URL('/api/products', url.origin)
	if (category) apiUrl.searchParams.set('category', category)
	apiUrl.searchParams.set('page', page)

	const response = await fetch(apiUrl.toString())

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

	const data: ProductListResponse = await response.json()

	return {
		products: data.products,
		total: data.total,
		page: data.page,
		pageSize: data.pageSize,
		selectedCategory: category
	}
}

El componente de página

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

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

	let { data }: PageProps = $props()

	const categories = ['peripherals', 'displays', 'furniture']

	const totalPages = $derived(Math.ceil(data.total / data.pageSize))

	function buildPageUrl(page: number): string {
		const params = new URLSearchParams()
		if (data.selectedCategory) params.set('category', data.selectedCategory)
		params.set('page', String(page))
		return `/shop?${params.toString()}`
	}

	function buildCategoryUrl(category: string | null): string {
		if (!category) return '/shop'
		return `/shop?category=${category}`
	}
</script>

<section class="shop">
	<h1>Shop</h1>

	<nav class="category-filter" aria-label="Filter by category">
		<a href={buildCategoryUrl(null)} class:active={!data.selectedCategory}>All</a>
		{#each categories as category (category)}
			<a href={buildCategoryUrl(category)} class:active={data.selectedCategory === category}>
				{category}
			</a>
		{/each}
	</nav>

	<p class="result-count">
		Showing {data.products.length} of {data.total} products
		{#if data.selectedCategory}in {data.selectedCategory}{/if}
	</p>

	<ul class="product-grid">
		{#each data.products as product (product.id)}
			<li class="product-card">
				<img src={product.imageUrl} alt={product.name} />
				<h2>{product.name}</h2>
				<p class="price">${product.price}</p>
				{#if !product.inStock}
					<span class="badge out-of-stock">Out of stock</span>
				{/if}
			</li>
		{/each}
	</ul>

	{#if totalPages > 1}
		<nav class="pagination" aria-label="Page navigation">
			{#if data.page > 1}
				<a href={buildPageUrl(data.page - 1)}>Previous</a>
			{/if}

			<span>Page {data.page} of {totalPages}</span>

			{#if data.page < totalPages}
				<a href={buildPageUrl(data.page + 1)}>Next</a>
			{/if}
		</nav>
	{/if}
</section>

Observa que en la ruta shop el componente +page.svelte no tiene llamadas fetch ni gestión de estado de carga. Los datos llegan a través de $props() como un objeto completo y tipado.

La runa $derived calcula el total de páginas de forma reactiva a partir de los datos sin ninguna lógica manual de recomputación.

La navegación entre páginas y categorías usa enlaces ancla simples, que activan la navegación del lado del cliente de SvelteKit y vuelven a ejecutar la función load en el cliente usando event.fetch, con los cinco superpoderes todavía en efecto.

Errores Comunes y Anti-Patrones

Usar el fetch global en lugar de event.fetch

// Avoid
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params }) => {
	// This uses the global fetch, not SvelteKit's enhanced version.
	// During SSR it may fail with relative URLs. During hydration
	// it bypasses the captured response and makes a second network request.
	const response = await fetch(`/api/articles/${params.slug}`)
	return { article: await response.json() }
}

// Preferred
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch }) => {
	// Destructure fetch from the event. This is SvelteKit's enhanced version.
	const response = await fetch(`/api/articles/${params.slug}`)
	return { article: await response.json() }
}

El fetch global no tiene conocimiento del ciclo de vida de SvelteKit. No puede resolver URLs relativas en el servidor, no reenvía credenciales, no llama directamente a los manejadores de rutas internas y no participa en la captura de respuestas SSR. La solución siempre es desestructurar fetch del evento de carga en lugar de llamar al global.

Ignorar el estado de la respuesta

// Wrong
export const load: PageServerLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/products/${params.id}`)
	// If the API returns 404 or 500, response.json() may throw or return
	// an error object. The page renders with garbage data or crashes silently.
	const product = await response.json()
	return { product }
}

// Correct
import { error } from '@sveltejs/kit'

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

	if (!response.ok) {
		// Throw a SvelteKit error. This renders the nearest +error.svelte
		// boundary with the appropriate HTTP status code.
		error(response.status, `Product ${params.id} could not be loaded`)
	}

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

response.ok es verdadero para códigos de estado 2xx. Cualquier otro estado significa que algo salió mal. Llamar a error() desde @sveltejs/kit termina la carga y renderiza el límite de error, que es el comportamiento correcto cuando los datos necesarios para renderizar la página no están disponibles.

Construir URLs mediante concatenación de cadenas

// Wrong: fragile and injection-prone
export const load: PageServerLoad = async ({ url, fetch }) => {
	const search = url.searchParams.get('q')
	// String concatenation does not encode special characters.
	// A search query containing '&' or '?' will corrupt the URL.
	const response = await fetch(`/api/search?q=${search}&page=1`)
	return { results: await response.json() }
}

// Correct: use the URL constructor for safe parameter encoding
export const load: PageServerLoad = async ({ url, fetch }) => {
	const search = url.searchParams.get('q') ?? ''

	const apiUrl = new URL('/api/search', url.origin)
	apiUrl.searchParams.set('q', search)
	apiUrl.searchParams.set('page', '1')

	const response = await fetch(apiUrl.toString())
	return { results: await response.json() }
}

El constructor URL y URLSearchParams manejan la codificación automáticamente. Los caracteres especiales en consultas de búsqueda, slugs con unicode y cualquier valor proporcionado por el usuario se manejan correctamente sin necesidad de codificación manual.

Consideraciones de Rendimiento y Escalabilidad

El mecanismo de captura de respuesta SSR funciona por solicitud. Cada solicitud entrante a tu aplicación SvelteKit activa su propio conjunto de funciones de carga, cada una con su propia instancia de fetch. Las respuestas capturadas no se comparten entre solicitudes ni se almacenan en caché más allá de la vida útil de una sola solicitud.

Si una función de carga obtiene datos que son costosos de calcular e idénticos para todos los usuarios, como una lista de categorías de productos o una configuración global del sitio, obtenerlos en cada solicitud SSR es un desperdicio. La solución es almacenar en caché en la capa de API, no en la función de carga. Tu manejador de ruta +server.ts puede implementar una caché en memoria o usar cabeceras de caché HTTP para permitir que los intermediarios almacenen la respuesta.

// src/routes/api/categories/+server.ts

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

// In-memory cache shared across requests to the same server instance.
// This is appropriate for data that changes rarely and is identical for all users.
let categoriesCache: string[] | null = null
let cacheSetAt = 0
const CACHE_TTL_MS = 60 * 1000 // one minute

export const GET: RequestHandler = async () => {
	const now = Date.now()

	if (categoriesCache && now - cacheSetAt < CACHE_TTL_MS) {
		return json(categoriesCache)
	}

	const response = await fetch('https://api.example.com/categories')
	const categories: string[] = await response.json()

	categoriesCache = categories
	cacheSetAt = now

	return json(categories)
}

Para datos específicos de usuario, el almacenamiento en caché a nivel de servidor no es apropiado ya que la respuesta de cada usuario es diferente. El mecanismo de captura SSR ya evita la doble obtención para la carga de página de cualquier usuario dado, por lo que no se necesita ninguna optimización adicional en ese caso.

Cuando múltiples funciones de carga en una jerarquía de rutas obtienen datos independientes, SvelteKit ejecuta las funciones de carga de layout y página con concurrencia cuando es posible. No necesitas paralelizar manualmente las solicitudes entre distintos archivos de carga. Dentro de una sola función de carga, si necesitas múltiples solicitudes independientes, usa Promise.all para evitar la obtención secuencial.

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

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

export const load: PageServerLoad = async ({ fetch }) => {
	// These requests are independent. Running them in parallel
	// reduces total load time to the duration of the slowest request
	// rather than the sum of all requests.
	const [statsResponse, activityResponse] = await Promise.all([
		fetch('/api/dashboard/stats'),
		fetch('/api/dashboard/activity')
	])

	if (!statsResponse.ok || !activityResponse.ok) {
		return { stats: null, activity: [] }
	}

	const [stats, activity] = await Promise.all([statsResponse.json(), activityResponse.json()])

	return { stats, activity }
}

Cuándo NO Usar Este Patrón

El patrón event.fetch es la herramienta adecuada para cargar datos que una página necesita antes de poder renderizarse. No es la herramienta adecuada para todo.

Las interacciones solo del cliente no pertenecen a las funciones de carga. Si una acción del usuario desencadena una actualización de datos, como hacer clic en un botón de actualización o enviar un formulario de búsqueda, esa interacción es manejada por el componente usando fetch estándar, acciones de formulario o la función invalidate de SvelteKit. La función de carga proporciona los datos iniciales; las actualizaciones iniciadas por el usuario son una preocupación separada.

Los datos en tiempo real, como las conexiones WebSocket o los eventos enviados por el servidor, no pueden modelarse como una sola llamada fetch en una función de carga. Las funciones de carga se ejecutan una vez por navegación. Para funcionalidades en tiempo real, establece la conexión en un $effect dentro del componente y gestiona el ciclo de vida de la conexión allí.

Los conjuntos de datos muy grandes no deben obtenerse completamente en una función de carga si solo se mostrará una parte. Usa paginación desde el principio, como se demostró en el ejemplo práctico, y obtén solo los datos que requiere la vista actual.

Los datos opcionales o secundarios que una página puede renderizar sin ellos no deberían bloquear el renderizado inicial al ser obtenidos en una función de carga. SvelteKit admite datos diferidos en streaming usando promesas, lo que permite que una página se renderice con datos críticos de inmediato mientras los datos secundarios se cargan en segundo plano. Ese patrón se cubre en un artículo dedicado de esta serie.

Conclusión

El event.fetch de SvelteKit se parece a una función familiar, pero posee cinco capacidades que cambian fundamentalmente cómo funciona la carga de datos en SSR, hidratación y navegación del cliente. Las URLs relativas se resuelven correctamente en Node.js. Las credenciales se reenvían automáticamente a los endpoints del mismo origen. Los manejadores de rutas internas se llaman directamente sin un viaje de red de ida y vuelta. Las respuestas se capturan y se integran en el payload de la página, eliminando el problema de doble obtención durante la hidratación. Y todo el mecanismo es consciente del entorno, funcionando correctamente en Node, el navegador y los entornos de ejecución edge.

Usar el fetch global en una función de carga omite todas estas capacidades. No es una elección estilística. Es un error categorial: usar una herramienta diseñada para un contexto diferente. El evento de carga te proporciona fetch por una razón, y esa razón es todo el comportamiento de red de tu aplicación SvelteKit.

Las implicaciones prácticas son sencillas: siempre desestructura fetch del evento de carga, verifica response.ok antes de parsear, usa el constructor URL para construir URLs parametrizadas, coloca las llamadas a APIs de otros orígenes detrás de rutas internas +server.ts para mantener las credenciales solo en el servidor, y confía en Promise.all para solicitudes paralelas independientes dentro de una sola función de carga.

Puntos Clave

Puntos clave:

Siempre desestructura fetch del objeto de evento de carga. El fetch global no tiene ninguna de las cinco capacidades de SvelteKit.
Las URLs relativas funcionan en las funciones de carga porque SvelteKit las resuelve automáticamente contra el origen de la solicitud actual.
Las solicitudes al mismo origen reenvían cookies y cabeceras de autorización de la solicitud entrante del navegador sin ningún reenvío manual.
Obtener una ruta interna +server.ts omite completamente la red. La función manejadora se llama directamente.
La captura de respuesta SSR evita el problema de doble obtención. Los datos obtenidos en el servidor se integran en la página y se reutilizan en el cliente durante la hidratación.
event.fetch funciona de manera idéntica en Node, el navegador y los entornos de ejecución edge. No se necesita detección de entorno ni polyfills.
Siempre verifica response.ok y usa error() de @sveltejs/kit para manejar correctamente las respuestas fallidas.

Lecturas Adicionales

Documentación de Enrutamiento de SvelteKit — referencia oficial para los manejadores de ruta +server.ts
Documentación de Carga de SvelteKit — referencia oficial para las propiedades del evento de función de carga, incluyendo fetch