Las Tres Entradas de URL

Una función de carga que siempre devuelve los mismos datos independientemente del contexto no es particularmente útil. Las aplicaciones reales necesitan responder a la URL actual: qué entrada de blog se está leyendo, qué página de un listado de productos está activa, qué categoría está seleccionada, qué consulta de búsqueda se ingresó. Toda esa información ya está presente en la URL — el trabajo de SvelteKit es entregársela a tu función de carga en una forma estructurada y tipada.

Cada función load recibe varias APIs de solicitud/evento (como fetch, parent, depends y untrack) además de tres entradas específicas de URL. Este artículo se enfoca en esas entradas específicas de URL porque cada una responde una pregunta diferente:

qué recurso se está solicitando
cómo quiere el usuario verlo
qué tipo de ruta está activa actualmente

Entender las tres, y saber cuál usar en cada situación, es lo que distingue las funciones de carga que simplemente funcionan de las que funcionan de manera eficiente y correcta bajo todas las condiciones de navegación.

Para las APIs de carga que no son de URL, consulta Fetch en Funciones de Carga, Usando Datos del Padre en Funciones de Carga, Cookies y Headers en la Carga del Servidor, y Reejecutando Funciones de Carga y Seguimiento de Dependencias.

Este artículo presenta cada entrada, explica una restricción sutil pero importante en torno a los fragmentos hash que sorprende a los desarrolladores, y une todo en un listado de productos completo con filtrado por categoría y paginación. Verás por qué el estado controlado por URL es preferible a la memoria del componente para todo lo que debe ser compartible, guardable como marcador o renderizado en el servidor.

La URL como Entrada

Imagina construir una página de listado de productos donde los usuarios pueden filtrar por categoría y navegar por los resultados. La pregunta no es si usar estado reactivo para rastrear la selección de filtro actual, por supuesto que lo harás. La pregunta es dónde vive ese estado.

El estado reactivo a nivel de componente es el hogar adecuado para las interacciones de UI efímeras y locales a la sesión: si un menú desplegable está abierto, qué panel de acordeón está expandido, lo que el usuario ha escrito pero aún no ha enviado. Este tipo de estado no tiene significado fuera de la sesión actual y no hay razón para que exista en una URL.

Las selecciones de filtros y las posiciones de paginación son una categoría de estado completamente diferente. Definen una vista específica y significativa de tus datos que debería sobrevivir una recarga de página, que un colega debería poder abrir directamente desde un enlace compartido, que el botón de retroceso del navegador debería poder restaurar, y que los motores de búsqueda deberían poder indexar como una URL distinta.

Cuando un estado como este vive solo en la memoria del componente, falla todos esos requisitos en silencio. El usuario recarga: el filtro desaparece. Comparte la URL: el receptor ve la vista predeterminada. Presiona atrás: la paginación se reinicia. Los bots rastrean: solo se descubre la primera página sin filtrar.

La solución es codificar el estado que define la vista en la URL desde el principio, y luego leerlo de vuelta en la función de carga en cada navegación. Una URL como /products?category=tools&page=2 es guardable como marcador, compartible, visible para rastreadores y consciente del historial sin ningún costo adicional. Esas propiedades vienen gratis del manejo de URLs del navegador, no de ninguna magia del framework.

El único trabajo requerido es saber cómo leer los parámetros de consulta correctamente dentro de una función de carga, que es exactamente lo que cubre este artículo.

Las Tres Entradas

Cada función de carga recibe tres entradas relacionadas con la URL, todas derivadas de la misma fuente, la URL de solicitud actual, pero cada una exponiendo una parte diferente de ella.

params

params responde la pregunta: ¿qué recurso específico se está solicitando?

Contiene los valores resueltos de cada segmento dinámico en la ruta. Cuando una ruta se define como src/routes/blog/[slug] y el usuario visita /blog/my-first-post, SvelteKit extrae slug de la URL y lo coloca en params como params.slug = 'my-first-post'. El tipo de params se genera automáticamente a partir de los nombres de los directorios de la ruta, por lo que TypeScript sabe exactamente qué claves son válidas para cualquier ruta dada.

url

url responde la pregunta: ¿cómo quiere el usuario verlo?

Es una instancia estándar de URL de la web, la URL completa ya parseada, con propiedades tipadas para pathname, origin, hostname y parámetros de búsqueda. Nunca tienes que dividir strings ni llamar a new URL() manualmente; llega lista para leer. La propiedad más importante para la carga de datos es url.searchParams, que da acceso estructurado al string de consulta.

route

route responde la pregunta: ¿qué tipo de página es esta?

Contiene información sobre la estructura de la ruta en sí, independientemente de los valores específicos en la URL actual. Su propiedad route.id es el patrón de ruta relativo a src/routes, con los nombres de segmentos dinámicos en su forma original entre corchetes. Para la misma URL anterior, route.id sería /blog/[slug], mientras que params.slug sería 'my-first-post'. La distinción importa cuando necesitas razonar sobre qué tipo de página está activa — para análisis, registro o lógica condicional — en lugar de qué recurso específico.

Juntando esos tres, una URL como /shop/tools?page=2&q=hammer#featured se mapea a las entradas de esta manera:

/shop/tools?page=2&q=hammer#featured
      │      │             │
      │      │             └── url.hash → "#featured"
      │      │                 (empty string on server — browser only)
      │      └── url.searchParams.get('page') → "2"
      │          url.searchParams.get('q')    → "hammer"
      └── params.category → "tools"
          (from route pattern /shop/[category])

url.pathname  → "/shop/tools"
route.id      → "/shop/[category]"   (the pattern, not the value)

Algo que hay que notar de inmediato: url.hash está anotado como vacío en el servidor. Los fragmentos hash, es decir todo lo que está después del # en una URL, son eliminados por el navegador antes de que se envíe la solicitud HTTP. El servidor simplemente nunca los recibe. Dado que las funciones de carga se ejecutan en el servidor durante el SSR, url.hash siempre será un string vacío en ese contexto. Esto no es una limitación de SvelteKit; así es como funciona el protocolo web. Las implicaciones prácticas y la solución correcta se tratan en el Paso 4 de la sección de implementación.

Antes de los pasos de implementación, una orientación rápida sobre qué entrada usar:

Implementación

Paso 1: Leyendo Segmentos de Ruta Dinámicos con params

El uso más común de datos de URL en una función de carga es leer los parámetros de ruta. Cualquier nombre de directorio en src/routes rodeado por corchetes define un segmento dinámico, y su valor actual está disponible en params bajo el mismo nombre.

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

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

export const load: PageServerLoad = async ({ params, fetch }) => {
	// params.slug is typed as string because the route directory
	// is named [slug]. SvelteKit generates this type for you from
	// the route structure; no manual type annotation is needed.
	const response = await fetch(`/api/posts/${params.slug}`)

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

	const post = await response.json()

	return { post }
}

El tipo TypeScript de params es generado por SvelteKit en base a los nombres de los directorios de la ruta. Para src/routes/blog/[slug], es { slug: string }. Para src/routes/shop/[category]/[productId], es { category: string; productId: string }. Esta seguridad de tipos está disponible de inmediato a través de la importación de ./$types y no requiere ningún trabajo manual de tu parte.

SvelteKit también admite parámetros rest para rutas que necesitan capturar múltiples segmentos de ruta como un único valor. Un directorio llamado [...path] coincidirá con cualquier número de segmentos después de ese punto en la URL y los recopilará como un único string.

// src/routes/docs/[...path]/+page.server.ts

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

export const load: PageServerLoad = async ({ params, fetch }) => {
	// For the URL /docs/sveltekit/routing/overview,
	// params.path would be 'sveltekit/routing/overview'.
	// Splitting on '/' gives the individual segments.
	const segments = params.path.split('/')

	// The path is passed as a query string so the API endpoint
	// can handle variable-depth routes without its own routing logic.
	const response = await fetch(`/api/docs?path=${encodeURIComponent(params.path)}`)

	if (!response.ok) {
		error(404, `Documentation page not found: ${params.path}`)
	}

	const page = await response.json()

	return {
		page,
		// Pass the segments back so the component can render breadcrumbs.
		breadcrumbs: segments
	}
}

Los parámetros rest son particularmente útiles para sistemas de documentación, exploradores de archivos y cualquier ruta donde la profundidad de la jerarquía de URL es variable en lugar de fija.

Paso 2: Leyendo Parámetros de Consulta con url.searchParams

Donde params representa la identidad del recurso que se solicita, los parámetros de consulta representan la configuración opcional de cómo quieres verlo. Los filtros, órdenes de clasificación, números de página y términos de búsqueda son todos candidatos naturales para los parámetros de consulta.

SvelteKit los expone a través de url.searchParams, que es una instancia estándar de URLSearchParams. El método clave es .get(name), que devuelve el valor string de ese parámetro o null si está ausente de la URL.

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

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

export const load: PageServerLoad = async ({ url, fetch }) => {
	// .get() returns string | null. Use nullish coalescing to supply
	// a safe default when the parameter is not present in the URL.
	const category = url.searchParams.get('category')
	const search = url.searchParams.get('q')
	const page = parseInt(url.searchParams.get('page') ?? '1', 10)
	const pageSize = 24

	// Forward the validated query parameters to the API endpoint.
	// The API is responsible for filtering, pagination, and counting.
	const apiParams = new URLSearchParams()
	if (category) apiParams.set('category', category)
	if (search) apiParams.set('q', search)
	apiParams.set('page', String(page))
	apiParams.set('pageSize', String(pageSize))

	const response = await fetch(`/api/products?${apiParams}`)
	const { products, totalCount } = await response.json()

	return {
		products,
		pagination: {
			page,
			pageSize,
			totalCount,
			totalPages: Math.ceil(totalCount / pageSize)
		},
		// Return the active filter values so the component can reflect
		// them in its UI without re-parsing the URL on the client side.
		activeFilters: { category, search }
	}
}

Hay un matiz importante en cómo SvelteKit rastrea el acceso a los parámetros de consulta para su sistema de re-ejecución de funciones de carga. Cuando tu función de carga llama a url.searchParams.get('category'), SvelteKit registra una dependencia en ese parámetro específico. Si el usuario cambia la categoría y navega a una nueva URL, SvelteKit sabe que debe re-ejecutar esta función de carga porque algo de lo que depende cambió. Si el usuario cambia un parámetro no relacionado que esta función de carga nunca lee, SvelteKit no la re-ejecutará innecesariamente.

Esta precisión solo es posible cuando usas searchParams.get(), searchParams.getAll() o searchParams.has() para parámetros individuales. Si en cambio lees url.search como un string sin procesar y lo parseas manualmente, SvelteKit crea una dependencia amplia en todo el string de consulta, lo que significa que cualquier cambio en un parámetro de consulta desencadena una re-ejecución incluso para los que esta función no usa. Siempre usa searchParams.get() para parámetros individuales; es más legible y más eficiente.

Paso 3: Usando route.id para Análisis y Lógica Condicional

El objeto route contiene información sobre la estructura de la ruta en lugar de los valores específicos de la URL. Su propiedad route.id es la ruta de la ruta relativa a src/routes, expresada con los nombres de segmentos dinámicos en su forma original entre corchetes.

// src/routes/admin/[section]/[itemId]/+page.server.ts

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

export const load: PageServerLoad = async ({ route, params }) => {
	// For the URL /admin/users/42:
	// route.id is '/admin/[section]/[itemId]'
	// params.section is 'users'
	// params.itemId is '42'
	console.log(route.id) // '/admin/[section]/[itemId]'
	console.log(params.section) // 'users'
	console.log(params.itemId) // '42'

	return {}
}

El valor práctico de route.id está en las utilidades compartidas que necesitan identificar qué ruta está activa sin importarle los valores específicos en esa ruta. Los análisis y el registro son los ejemplos más claros. Cuando registras vistas de página, típicamente quieres dos datos: la ruta estructural (que te indica el tipo de página visitada, como una entrada de blog o una página de producto) y el recurso específico (que te indica exactamente qué entrada o producto). Agregar por route.id te permite responder "cuántas veces se visitó la vista de entrada de blog en total" porque cada entrada de blog comparte el mismo route.id de /blog/[slug], aunque cada una tenga un params.slug diferente.

// src/lib/server/analytics.ts

// A thin wrapper that posts view events to an internal analytics endpoint.
// Keeping this in $lib/server/ ensures it is never bundled for the browser.
export async function trackView(
	fetch: typeof globalThis.fetch,
	routeId: string | null,
	params: Record<string, string>
): Promise<void> {
	// routeId identifies the type of page: '/blog/[slug]', '/products/[id]', etc.
	// params records which specific resource was viewed.
	await fetch('/api/analytics/views', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({
			route: routeId ?? 'unknown',
			params,
			visitedAt: new Date().toISOString()
		})
	})
}

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

import type { PageServerLoad } from './$types'
import { trackView } from '$lib/server/analytics'
import { error } from '@sveltejs/kit'

export const load: PageServerLoad = async ({ route, params, fetch }) => {
	// Run analytics tracking and the post query concurrently.
	// Neither depends on the result of the other, so there is no
	// reason to wait for one before starting the other.
	const [postResponse] = await Promise.all([
		fetch(`/api/posts/${params.slug}`),
		trackView(fetch, route.id, params)
	])

	if (!postResponse.ok) {
		error(404, 'Post not found')
	}

	const post = await postResponse.json()

	return { post }
}

Ejecutar el seguimiento de análisis en paralelo con la obtención de datos principal mantiene el tiempo de carga de la página sin verse afectado por la escritura de análisis. La consulta del post y la inserción de análisis comienzan al mismo tiempo y la función de carga espera a que ambas se completen antes de devolver.

Paso 4: Por Qué url.hash No Está Disponible en el Servidor

Antes de construir el ejemplo completo, vale la pena entender explícitamente la restricción del hash en lugar de descubrirla a través de un bug desconcertante.

Cuando un navegador realiza una solicitud HTTP, la porción hash de la URL, todo lo que está después del carácter #, se elimina intencionalmente antes de enviar la solicitud. Este es un comportamiento especificado que data del diseño original de HTTP. El servidor nunca recibe el hash; solo existe en el navegador. El propósito original de los hashes era apuntar a elementos ancla dentro de un documento ya cargado, por lo que no había necesidad de enviarlos al servidor en absoluto.

Dado que las funciones de carga de SvelteKit se ejecutan en el servidor durante el SSR, url.hash siempre será un string vacío en ese contexto. Se popula correctamente cuando la función de carga se ejecuta en el navegador durante la navegación del lado del cliente, pero no puedes depender de él durante el primer renderizado.

// AVOID: This will silently return '' during SSR.
// The tab will appear correct after client-side hydration but not
// during the initial server render, causing a hydration mismatch.

export const load: PageLoad = async ({ url }) => {
	const activeTab = url.hash.replace('#', '') || 'overview'
	return { activeTab }
}

El enfoque correcto es convertir el estado basado en hash a un parámetro de consulta (que el servidor puede ver), o manejar el hash en el componente después del montaje usando $app/state.

<!-- PREFERRED: Read hash state in the component using $app/state.
     page.url.hash is reactive and updates on client-side navigation.
     It will be empty during SSR, so provide a sensible default. -->

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

	let { data }: PageProps = $props()

	// $derived keeps activeTab in sync with navigation changes.
	// On the server and on first render it defaults to 'overview'.
	let activeTab = $derived(page.url.hash.replace('#', '') || 'overview')
</script>

<div class="tabs">
	<a href="#overview" class:active={activeTab === 'overview'}>Overview</a>
	<a href="#reviews" class:active={activeTab === 'reviews'}>Reviews</a>
	<a href="#specs" class:active={activeTab === 'specs'}>Specs</a>
</div>

Si la selección de pestañas controla qué datos se cargan desde el servidor en lugar de solo qué sección del contenido ya cargado se muestra, entonces usa un parámetro de consulta (?tab=reviews) en lugar de un hash, para que el servidor pueda leerlo durante el SSR.

Paso 5: Un Listado de Productos Filtrable Completo

Con las tres entradas comprendidas, aquí hay un ejemplo completo que las une. La ruta es /products, y admite filtrado por categoría y navegación a través de resultados paginados. Todo el estado vive en la URL para que cada vista sea compartible y cada navegación sea rastreada por el sistema de dependencias de SvelteKit.

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

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

// Validation helpers keep the load function readable and
// protect against arbitrary user input reaching the API.
const VALID_SORT_FIELDS = ['name', 'price', 'rating'] as const
type SortField = (typeof VALID_SORT_FIELDS)[number]

function parseSortField(value: string | null): SortField {
	if (value && (VALID_SORT_FIELDS as readonly string[]).includes(value)) {
		return value as SortField
	}
	return 'name'
}

function parsePage(value: string | null): number {
	const parsed = parseInt(value ?? '1', 10)
	// Guard against NaN, zero, and negative page numbers
	// that could arise from malformed or manipulated URLs.
	return Number.isFinite(parsed) && parsed > 0 ? parsed : 1
}

const PAGE_SIZE = 24

export const load: PageServerLoad = async ({ url, fetch }) => {
	// Read and validate all relevant parameters using get() for precise
	// dependency tracking on each individual parameter.
	const category = url.searchParams.get('category')
	const search = url.searchParams.get('q')
	const sortBy = parseSortField(url.searchParams.get('sort'))
	const page = parsePage(url.searchParams.get('page'))

	// Build the outgoing API params from the validated values only.
	// This means the API never receives raw, unvalidated user input.
	const apiParams = new URLSearchParams()
	if (category) apiParams.set('category', category)
	if (search && search.trim().length >= 2) apiParams.set('q', search.trim())
	apiParams.set('sort', sortBy)
	apiParams.set('page', String(page))
	apiParams.set('pageSize', String(PAGE_SIZE))

	// Fetch the product list and the category list for the filter UI
	// in parallel — neither depends on the other.
	const [productsRes, categoriesRes] = await Promise.all([
		fetch(`/api/products?${apiParams}`),
		fetch('/api/categories')
	])

	const { products, totalCount } = await productsRes.json()
	const categories = await categoriesRes.json()

	return {
		products,
		categories,
		pagination: {
			page,
			pageSize: PAGE_SIZE,
			totalCount,
			totalPages: Math.ceil(totalCount / PAGE_SIZE)
		},
		// Returning the parsed and validated filter values means the
		// component does not need to re-read or re-parse the URL itself.
		activeFilters: { category, search, sortBy }
	}
}

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

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

	let { data }: PageProps = $props()

	// Build a URL for a target page number while preserving the
	// current filter state. Because the function closes over
	// the reactive data prop, it always reflects the latest values.
	function buildPageUrl(targetPage: number): string {
		const params = new URLSearchParams()

		if (data.activeFilters.category) {
			params.set('category', data.activeFilters.category)
		}
		if (data.activeFilters.search) {
			params.set('q', data.activeFilters.search)
		}

		params.set('sort', data.activeFilters.sortBy)
		params.set('page', String(targetPage))

		return `/products?${params.toString()}`
	}
</script>

<div class="products-page">
	<!--
		Using method="GET" means the browser navigates to a new URL
		when the form is submitted, updating the query string.
		SvelteKit intercepts this navigation, sees that the URL changed,
		and reruns the load function with the new searchParams values.
		No custom JavaScript is needed for the filter mechanism itself.
	-->
	<form method="GET" class="filters">
		<select name="category">
			<option value="">All Categories</option>
			{#each data.categories as cat (cat.slug)}
				<option value={cat.slug} selected={cat.slug === data.activeFilters.category}>
					{cat.name}
				</option>
			{/each}
		</select>

		<input
			type="search"
			name="q"
			placeholder="Search products..."
			value={data.activeFilters.search ?? ''}
		/>

		<select name="sort">
			<option value="name" selected={data.activeFilters.sortBy === 'name'}> Name </option>
			<option value="price" selected={data.activeFilters.sortBy === 'price'}> Price </option>
			<option value="rating" selected={data.activeFilters.sortBy === 'rating'}> Rating </option>
		</select>

		<button type="submit">Apply Filters</button>
	</form>

	<div class="product-grid">
		{#each data.products as product (product.id)}
			<a href="/products/{product.slug}" class="product-card">
				<img src={product.thumbnailUrl} alt={product.name} />
				<h2>{product.name}</h2>
				<p class="price">${product.price}</p>
				<p class="rating">{product.rating} stars</p>
			</a>
		{/each}

		{#if data.products.length === 0}
			<p class="empty-state">
				No products match your current filters. Try adjusting your search or category.
			</p>
		{/if}
	</div>

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

			<span>
				Page {data.pagination.page} of {data.pagination.totalPages}
				({data.pagination.totalCount} products)
			</span>

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

El formulario de filtro usa method="GET" para que al enviarlo se realice una navegación estándar del navegador a la misma ruta con parámetros de consulta actualizados. SvelteKit intercepta esa navegación, detecta que url.searchParams cambió y re-ejecuta la función de carga. La página se actualiza con nuevos datos sin una recarga completa de la página y sin ningún manejador de eventos JavaScript personalizado que gestione el estado del filtro.

Los enlaces de paginación funcionan de la misma manera: cada uno es un ancla simple que apunta a una URL que codifica los filtros actuales más el nuevo número de página, por lo que cada página de resultados es su propia URL distinta y navegable.

Errores Comunes y Anti-Patrones

Pasar Valores de URL Sin Procesar Directamente a la Base de Datos

Cualquier parámetro de consulta en la URL puede ser establecido a cualquier string arbitrario por cualquier usuario. Pasar esos valores sin validación directamente a una consulta de base de datos permite que entradas inesperadas lleguen a tu capa de datos.

// AVOID: sortBy could be anything the user puts in the URL.
// Forwarding it directly to the API without validation is unsafe —
// the server receiving it may trust the value implicitly.

export const load: PageServerLoad = async ({ url, fetch }) => {
	const sortBy = url.searchParams.get('sort')
	const res = await fetch(`/api/products?sort=${sortBy}`)
	return { products: await res.json() }
}

// PREFERRED: Validate against an explicit allowlist first.
// The API only ever receives one of three known-safe sort values.

const VALID_SORT_FIELDS = ['name', 'price', 'rating'] as const
type SortField = (typeof VALID_SORT_FIELDS)[number]

function parseSortField(value: string | null): SortField {
	if (value && (VALID_SORT_FIELDS as readonly string[]).includes(value)) {
		return value as SortField
	}
	return 'name'
}

export const load: PageServerLoad = async ({ url, fetch }) => {
	const sortBy = parseSortField(url.searchParams.get('sort'))
	const res = await fetch(`/api/products?sort=${sortBy}`)
	return { products: await res.json() }
}

Las pequeñas funciones de utilidad de validación como parseSortField y parsePage también hacen que las funciones de carga sean más fáciles de probar unitariamente, ya que la lógica de parseo está aislada y puede ejercitarse independientemente del resto de la función de carga.

Leer url.search en Lugar de url.searchParams.get()

Leer url.search como una cadena de texto sin procesar crea una dependencia en toda la cadena de consulta; usar url.searchParams.get('key') crea una dependencia únicamente en esa clave específica. En aplicaciones donde múltiples funciones de carga o componentes actualizan diferentes parámetros de consulta, las dependencias imprecisas hacen que las funciones de carga se vuelvan a ejecutar con más frecuencia de la necesaria.

// AVOID: Any query parameter change triggers a rerun of this
// load function, even parameters it never uses.

export const load: PageLoad = async ({ url }) => {
	const allParams = new URLSearchParams(url.search) // broad dependency
	const category = allParams.get('category')
	return { category }
}

// PREFERRED: Only a change to 'category' triggers a rerun.
// Changes to 'sort', 'page', or anything else are ignored.

export const load: PageLoad = async ({ url }) => {
	const category = url.searchParams.get('category') // precise dependency
	return { category }
}

Esperar que url.hash Funcione en una Función de Carga

Este error se manifiesta como una discrepancia sutil de SSR. La función de carga devuelve un valor predeterminado para el estado dependiente del hash en el servidor porque url.hash siempre está vacío allí; después de la hidratación, el cliente vuelve a ejecutar la función de carga y obtiene un valor diferente porque url.hash ahora está poblado. El resultado es un destello de contenido incorrecto y una advertencia de hidratación en la consola del navegador.

La solución es mover la lógica dependiente del hash completamente fuera de la función de carga y manejarla en el componente usando el objeto reactivo page de $app/state, o convertir el estado basado en hash a un parámetro de consulta que el servidor pueda leer.

Consideraciones de Rendimiento y Escalabilidad

El seguimiento de dependencias detallado de SvelteKit para url.searchParams es una de sus características de rendimiento más silenciosas pero más útiles. Dado que cada llamada a searchParams.get() registra una dependencia solo en esa clave específica, SvelteKit tiene información precisa sobre lo que le importa a cada función de carga. Durante la navegación del lado del cliente, puede comparar solo las partes relevantes de la URL para decidir si una función de carga necesita volver a ejecutarse, en lugar de comparar cadenas de URL completas.

Esto significa que en una página con varias funciones de carga independientes, cada una se volverá a ejecutar solo cuando los parámetros específicos que lee cambien realmente. Una función de carga de paginación que solo lee page no se volverá a ejecutar cuando el usuario cambie el término de búsqueda; una función de carga de filtro de categoría que solo lee category no se volverá a ejecutar cuando el usuario cambie el orden de clasificación. Para páginas complejas con múltiples dependencias de datos, esta precisión mantiene la navegación rápida y evita solicitudes redundantes al servidor.

El patrón Promise.all mostrado en el ejemplo completo vale la pena destacarlo como una consideración de rendimiento separada. Obtener productos, el conteo total y la lista de categorías en una sola llamada Promise.all envía las tres consultas a la base de datos simultáneamente en lugar de secuencialmente. El tiempo de espera total está determinado por la más lenta de las tres consultas en lugar de la suma de todas. Este patrón debería ser el predeterminado siempre que se necesiten múltiples solicitudes de datos independientes en una sola función de carga.

Cuándo NO Usar Este Patrón

El estado controlado por URL es la herramienta adecuada para los datos que definen una vista significativa y compartible: qué página, qué categoría, qué término de búsqueda. No es la herramienta adecuada para el estado efímero de la interfaz de usuario que solo importa para la sesión actual y no tiene significado para nadie más. Si un menú desplegable está abierto, si un panel acordeón está expandido, o qué texto ha escrito un usuario pero aún no ha enviado son ejemplos de estado que pertenece al componente como variables reactivas, no a la URL.

La prueba práctica es si una URL que contenga ese estado sería útil para otra persona. Una URL que codifica la página 3 de una búsqueda de productos filtrada es genuinamente útil para otro usuario. Una URL que codifica qué sección de acordeón tiene abierta un usuario es simplemente ruido.

Para las entradas de búsqueda en particular, desencadenar una navegación URL completa y volver a ejecutar la función de carga en cada pulsación de tecla produciría una experiencia discordante. La solución convencional es usar un formulario con method="GET" y un botón de envío, como en el ejemplo anterior, para que la navegación ocurra solo cuando el usuario aplica explícitamente su búsqueda. Alternativamente, aplique un rebote a la entrada para que la navegación solo se active después de una breve pausa al escribir.

Conclusión

Las entradas params, url y route le dan a las funciones de carga todo lo necesario para responder de manera inteligente a la URL actual. Los parámetros de ruta en params identifican el recurso específico que se está solicitando, tipados con precisión a partir de la estructura de directorios de la ruta. Los parámetros de consulta a través de url.searchParams llevan configuración de vista opcional como filtros y números de página, con un seguimiento de dependencias preciso por parámetro. La propiedad route.id en route expone el patrón de ruta estructural para análisis y lógica condicional que necesita razonar sobre qué tipo de página está activa en lugar de qué recurso específico.

La disciplina más importante es tratar todos los valores de URL como entradas de usuario no confiables y validarlos antes de que lleguen a la base de datos. Más allá de eso, usar searchParams.get() en lugar de leer url.search como una cadena de texto sin procesar es un pequeño hábito que mantiene el seguimiento de dependencias de SvelteKit preciso y la navegación eficiente.

Puntos Clave

params contiene los valores resueltos de los segmentos de ruta dinámicos, tipados con precisión a partir de la estructura de directorios de la ruta; es el lugar correcto para leer la identidad del recurso. url.searchParams.get() lee parámetros de consulta individuales y registra dependencias precisas por clave; leer url.search como una cadena de texto sin procesar crea una dependencia más amplia y debe evitarse. url.hash siempre es una cadena vacía durante el SSR porque los navegadores eliminan los fragmentos de hash antes de enviar solicitudes HTTP; la lógica dependiente del hash pertenece al componente, no a la función de carga. route.id expone el patrón de ruta en notación de corchetes, independientemente de los valores de URL específicos, y es útil para análisis y registro. Todos los valores que llegan desde la URL son entradas de usuario no confiables y deben validarse antes de llegar a las consultas de base de datos o la lógica de negocio.

Qué Sigue

Ahora que tiene una comprensión sólida de lo que las funciones de carga reciben como entrada, es momento de examinar detenidamente cómo realizan solicitudes salientes. El fetch proporcionado por el evento de carga no es el mismo que el fetch global del navegador; tiene mejoras significativas que resuelven problemas reales en aplicaciones renderizadas en el servidor, desde el reenvío de credenciales hasta la consistencia de hidratación. El siguiente artículo, Fetch en Funciones de Carga, cubre exactamente cuáles son esas mejoras y cómo usarlas correctamente.

Lectura Adicional

Enrutamiento Avanzado de SvelteKit — parámetros rest, parámetros opcionales y prioridad de coincidencia
URLSearchParams en MDN — la referencia completa de la API para el objeto searchParams
Documentación Oficial de Carga de SvelteKit — la referencia oficial para todas las entradas de funciones de carga