Qué Es el Objeto page

Los dos artículos anteriores establecieron que las funciones load retornan datos antes de que una página se renderice, y que las funciones load de layout comparten esos datos a través de todas las rutas hijas en un segmento. Lo que dejaron abierto fue una pregunta práctica que surge de inmediato en aplicaciones reales: una vez que una página está renderizada, ¿cómo lee un componente que no es el componente de página la ruta actual, la URL actual o el usuario actual?

SvelteKit responde esto con el objeto page, exportado desde $app/state. Es un store reactivo que refleja el estado actual de la navegación de la aplicación en todo momento. Cualquier componente en el árbol puede importarlo y leer de él, sin prop-drilling y sin suscribirse a un store personalizado. Cuando el usuario navega a una ruta diferente, cada valor en el objeto page se actualiza automáticamente, y cualquier componente que lea esos valores se vuelve a renderizar en consecuencia.

Entender el objeto page no es conocimiento opcional. Aparece en componentes de navegación que resaltan el enlace activo, en layouts raíz que establecen el título del documento dinámicamente, en límites de error que leen page.status, y en formularios que leen page.form para resultados de acciones del lado del servidor. Este artículo es una referencia completa de lo que contiene, cómo funciona su modelo de reactividad, y las situaciones en las que cada propiedad es útil.

Por Qué Existe el Objeto page

Considera una barra de navegación estándar. Se renderiza a nivel del layout raíz, envolviendo cada página de la aplicación. Cada enlace del nav debería aparecer resaltado cuando el usuario está en su ruta correspondiente. El componente nav no recibe ninguna prop; no tiene un canal natural para saber qué ruta está activa actualmente.

Sin page, las opciones son limitadas. Podrías pasar la URL actual hacia abajo como prop desde el layout raíz, lo que significa pasarla a través de cada componente intermedio. Podrías crear un contexto de Svelte que el layout raíz escribe y el nav lee, que es el patrón correcto para algunos casos de uso pero agrega código repetitivo para algo que el framework ya conoce. Podrías derivar la ruta activa del objeto location del navegador, pero eso no funciona durante SSR porque no hay un location del navegador en el servidor.

El objeto page resuelve los tres problemas a la vez. Está disponible en todas partes, funciona en el servidor durante SSR con valores realistas derivados de la solicitud HTTP entrante, y se actualiza reactivamente cada vez que cambia la ruta.

<!-- src/lib/components/Nav.svelte -->
<!-- This works everywhere: SSR, client-side navigation, any component -->

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

	const links = [
		{ href: '/', label: 'Home' },
		{ href: '/blog', label: 'Blog' },
		{ href: '/about', label: 'About' }
	]
</script>

<nav>
	{#each links as link}
		<a href={link.href} class:active={page.url.pathname === link.href}>
			{link.label}
		</a>
	{/each}
</nav>

<style>
	.active {
		font-weight: 600;
		border-bottom: 2px solid currentColor;
	}
</style>

La directiva class:active se re-evalúa cada vez que page.url.pathname cambia. Sin suscripción, sin limpieza, sin manejo manual de stores. La reactividad es implícita, exactamente como lo es con $state en el código de componentes de Svelte 5.

Cómo Funciona la Reactividad de page

El objeto page de $app/state es un objeto reactivo simple respaldado por el sistema de reactividad de grano fino de Svelte 5. Leer cualquier propiedad de él durante el renderizado de un componente crea una dependencia en esa propiedad. Cuando ocurre la navegación y SvelteKit actualiza los valores dentro de page, solo los componentes que leen las propiedades cambiadas se vuelven a renderizar.

Esto es distinto de $app/stores, la API más antigua de Svelte 4, que exponía page como un store de Svelte que requería suscripción explícita con $page. La versión de $app/state funciona sin ninguna sintaxis de suscripción porque está construida sobre runes. Si estás leyendo documentación o código que usa $page con un prefijo de signo de dólar e importa desde $app/stores, ese es el patrón más antiguo. Esta serie usa $app/state exclusivamente.

Durante el renderizado del lado del servidor, el objeto page se rellena a partir de la solicitud HTTP entrante. page.url refleja la URL de la solicitud, page.params refleja los parámetros de ruta resueltos, y page.data refleja la salida combinada de todas las funciones load que se ejecutaron para esa solicitud. El componente se renderiza una vez, usando esa instantánea del estado, y el resultado se envía como HTML. Cuando el navegador toma el control e hidrata la página, el objeto page se inicializa con los mismos valores y el comportamiento del componente permanece consistente.

Durante la navegación del lado del cliente, SvelteKit actualiza el objeto page antes de volver a renderizar los componentes afectados. La secuencia es: navegación disparada, funciones load se ejecutan para la nueva ruta, page actualizado con nuevos valores, componentes afectados se vuelven a renderizar. Los componentes no reciben notificación explícita de que ocurrió la navegación; simplemente leen de page y el sistema de reactividad de Svelte maneja el resto.

Cada Propiedad Explicada

page.url

page.url es un objeto URL estándar de la Web API que representa la URL completa de la página actual. Expone todas las propiedades que esperarías de una URL: pathname, search, searchParams, hash, origin, href, y el resto.

<!-- src/lib/components/Breadcrumb.svelte -->

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

	let segments = $derived(
		page.url.pathname
			.split('/')
			.filter(Boolean)
			.map((segment, i, arr) => ({
				label: segment,
				href: '/' + arr.slice(0, i + 1).join('/')
			}))
	)
</script>

<nav aria-label="Breadcrumb">
	<a href="/">Home</a>
	{#each segments as segment}
		<span aria-hidden="true"> / </span>
		<a href={segment.href}>{segment.label}</a>
	{/each}
</nav>

Una advertencia importante del lado del servidor: page.url.hash siempre es una cadena vacía durante SSR. El navegador elimina el fragmento hash antes de enviar la solicitud HTTP, por lo que el servidor nunca lo ve. Cualquier lógica que dependa del hash debe ejecutarse solo en el navegador. El patrón correcto es verificar page.url.hash dentro de $effect() o dentro de un manejador de eventos, nunca durante la inicialización del componente que se ejecuta durante SSR.

page.url.searchParams es una instancia de URLSearchParams. Es de solo lectura a través de page.url; para cambiar los parámetros de búsqueda, navegas programáticamente usando la función goto() de SvelteKit desde $app/navigation. Leerlo en un $derived crea una dependencia que hace que el valor derivado se actualice cada vez que cambien los parámetros de búsqueda, que es el patrón correcto para cosas como una UI de filtrado reactiva.

page.params

page.params es un objeto simple cuyos claves corresponden a los segmentos dinámicos en el nombre del directorio de la ruta activa. Para una ruta en src/routes/shop/[category]/[productId]/+page.svelte, el objeto tendrá category y productId como claves tipadas como string.

<!-- src/routes/shop/[category]/[productId]/+page.svelte -->

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

	let { data }: PageProps = $props()

	// page.params mirrors what was available in the load function
	let breadcrumb = $derived(`${page.params.category} / ${page.params.productId}`)
</script>

<p>Viewing: {breadcrumb}</p><h1>{data.product.name}</h1>

En la mayoría de los casos, page.params y data de la función load son los lugares correctos para obtener esta información, y contienen los mismos valores de parámetros. La diferencia es que data requiere que exista una función load y que retorne algo, mientras que page.params siempre está disponible independientemente de si existe una función load.

page.route

page.route es un objeto con una sola propiedad: id. El id es el patrón de la ruta como una cadena en la notación entre corchetes que refleja la estructura de directorios, por ejemplo /blog/[slug] o /shop/[category]/[productId]. De manera crucial, es el patrón en lugar del valor resuelto. Dos URLs diferentes como /blog/introduction-to-svelte y /blog/advanced-runes ambas producen un route.id de /blog/[slug].

Esto hace que page.route.id sea útil para lógica que necesita saber qué plantilla de ruta está activa, independientemente de los valores específicos. El código de analíticas que rastrea eventos de vistas de página por tipo de ruta, el renderizado condicional que difiere entre rutas en una sección, y el middleware de logging que clasifica solicitudes se benefician del patrón de ruta en lugar de la URL resuelta.

<!-- src/lib/components/Nav.svelte -->

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

	// Highlight the Blog section for any route under /blog
	let inBlogSection = $derived(page.route.id?.startsWith('/blog') ?? false)
</script>

<nav>
	<a href="/" class:active={page.route.id === '/'}>Home</a>
	<a href="/blog" class:active={inBlogSection}>Blog</a>
	<a href="/about" class:active={page.route.id === '/about'}>About</a>
</nav>

page.data

page.data es la salida combinada de todas las funciones load activas para la ruta actual. Incluye datos del load del layout raíz, cualquier load de layout intermedio, y el load de la página en sí. Es el mismo objeto que +page.svelte recibe a través de su prop data, pero accesible desde cualquier lugar, incluso desde layouts padre que necesitan leer datos de una página hija que están envolviendo.

El caso de uso canónico es un layout raíz que establece el <title> del documento dinámicamente basándose en lo que retornó la función load de la página actual:

<!-- src/routes/+layout.svelte -->

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

	let { children } = $props()
</script>

<svelte:head>
	<title>{page.data.title ? `${page.data.title} | My Site` : 'My Site'}</title>
	<meta name="description" content={page.data.description ?? 'A great website.'} />
</svelte:head>

{@render children()}

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

export const load: PageServerLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/posts/${params.slug}`)
	const post = await res.json()

	return {
		post,
		title: post.title,
		description: post.excerpt
	}
}

El layout raíz no tiene forma de recibir title y description a través de la prop de datos normal, porque los datos fluyen hacia abajo y los layouts solo ven el valor de retorno de su propia función load combinado con sus ancestros. page.data es la forma limpia y soportada por el framework para hacer fluir información hacia arriba desde una página a un layout padre.

El tipo TypeScript para page.data está determinado por App.PageData en las declaraciones de tipo de tu aplicación. SvelteKit no infiere automáticamente esto como una unión de todas las posibles formas de datos de página, porque en tiempo de ejecución el layout raíz simplemente no sabe qué página está activa. Típicamente declaras App.PageData con propiedades opcionales que cualquier página podría proporcionar, y manejas su ausencia con coalescencia de nulos como se muestra arriba.

page.status

page.status es el código de estado HTTP de la respuesta actual como un número. Para una página renderizada normalmente es 200. Para una página renderizada porque una función load llamó a error(404, 'Not found'), es 404. Para una redirección, la página en el destino de la redirección tendrá un estado 200; la respuesta de redirección en sí no es un renderizado de página.

page.status es más útil en el componente +error.svelte, donde te permite renderizar condicionalmente diferentes mensajes para diferentes tipos de error sin duplicar la página de error en múltiples archivos:

<!-- src/routes/+error.svelte -->

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

{#if page.status === 404}
	<h1>Page not found</h1>
	<p>The page you were looking for does not exist.</p>
	<a href="/">Back to home</a>
{:else if page.status === 403}
	<h1>Access denied</h1>
	<p>You do not have permission to view this page.</p>
{:else}
	<h1>Something went wrong</h1>
	<p>An unexpected error occurred. Please try again later.</p>
	<p class="code">Error {page.status}</p>
{/if}

También puedes leer page.status desde componentes de página y layouts regulares, lo cual es menos común pero ocasionalmente útil para UI que debería comportarse de manera diferente en estados de error.

page.error

page.error se rellena cuando SvelteKit está renderizando una página de error debido a una llamada error() lanzada o una excepción inesperada. Es un objeto con una cadena message. Para errores esperados lanzados con error(status, message), tendrá el mensaje que proporcionaste. Para errores inesperados, contendrá el mensaje de tu hook handleError, o un fallback genérico.

<!-- src/routes/+error.svelte -->

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

<h1>Error {page.status}</h1><p>{page.error?.message}</p>

Fuera de las páginas de error, page.error es null. No es necesario protegerse contra él en componentes de página normales.

page.form

page.form es el resultado retornado por la acción de formulario ejecutada más recientemente. Se rellena después de que un formulario se envía a una función de acción de +page.server.ts y contiene lo que esa acción retornó. Cuando ninguna acción de formulario ha sido ejecutada, o cuando el usuario navega fuera y regresa, page.form es null.

Esta propiedad es la forma en que los formularios con mejora progresiva exponen resultados de validación del lado del servidor al componente sin recargar la página:

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

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

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

<form method="POST">
	<label>
		Name
		<input name="name" type="text" value={page.form?.name ?? ''} />
		{#if page.form?.errors?.name}
			<span class="error">{page.form.errors.name}</span>
		{/if}
	</label>

	<label>
		Email
		<input name="email" type="email" value={page.form?.email ?? ''} />
		{#if page.form?.errors?.email}
			<span class="error">{page.form.errors.email}</span>
		{/if}
	</label>

	<button type="submit">Send</button>

	{#if page.form?.success}
		<p class="success">Message sent successfully.</p>
	{/if}
</form>

// src/routes/contact/+page.server.ts
import type { Actions } from './$types'

export const actions: Actions = {
	default: async ({ request }) => {
		const data = await request.formData()
		const name = String(data.get('name') ?? '')
		const email = String(data.get('email') ?? '')

		const errors: Record<string, string> = {}
		if (!name.trim()) errors.name = 'Name is required'
		if (!email.includes('@')) errors.email = 'Valid email required'

		if (Object.keys(errors).length > 0) {
			return { success: false, name, email, errors }
		}

		// process the form...
		return { success: true }
	}
}

La acción retorna un objeto simple. SvelteKit hace que ese objeto esté disponible como page.form en el componente de página. Si el usuario actualiza la página, page.form se reinicia a null. Si JavaScript está deshabilitado, la misma acción se ejecuta y SvelteKit vuelve a renderizar la página en el servidor con el resultado de la acción, haciendo que aparezcan los mensajes de validación sin ningún JavaScript del lado del cliente.

page.state

page.state es el valor del objeto de estado de la entrada del historial actual, establecido usando pushState() o replaceState() de SvelteKit desde $app/navigation. Este es un mecanismo de enrutamiento superficial: te permite actualizar lo que renderiza un componente, y opcionalmente qué URL aparece en la barra de direcciones del navegador, sin desencadenar una navegación completa y sin ejecutar funciones load nuevamente.

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

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

	let { data }: PageProps = $props()

	function openModal(imageId: string) {
		pushState('', { selectedImageId: imageId })
	}

	function closeModal() {
		history.back()
	}
</script>

<div class="gallery">
	{#each data.images as image (image.id)}
		<button onclick={() => openModal(image.id)}>
			<img src={image.thumbnailUrl} alt={image.alt} />
		</button>
	{/each}
</div>

{#if page.state.selectedImageId}
	{@const selected = data.images.find((i) => i.id === page.state.selectedImageId)}
	{#if selected}
		<div class="modal" role="dialog">
			<button class="close" onclick={closeModal}>Close</button>
			<img src={selected.fullUrl} alt={selected.alt} />
		</div>
	{/if}
{/if}

Cuando se llama a pushState con un objeto de estado, SvelteKit actualiza page.state reactivamente. El modal aparece. Cuando el usuario hace clic en el botón Atrás del navegador, la entrada del historial cambia y page.state regresa a su valor anterior, por lo que el modal desaparece. Este patrón es la forma correcta de implementar modales, drawers y otros overlays que deberían poder cerrarse con el botón atrás del navegador, sin la sobrecarga de navegación completa de página.

Errores Comunes y Anti-Patrones

Importar desde $app/stores en Lugar de $app/state

Svelte 4 exponía el objeto page a través de $app/stores como un store de Svelte, requiriendo import { page } from '$app/stores' y $page (con el prefijo de auto-suscripción) para leer valores dentro de un componente.

<!-- AVOID: Svelte 4 pattern -->

<script lang="ts">
	import { page } from '$app/stores'
</script>

<p>Path: {$page.url.pathname}</p>

<!-- PREFERRED: Svelte 5 / $app/state pattern -->

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

<p>Path: {page.url.pathname}</p>

La API de $app/stores todavía funciona en SvelteKit por compatibilidad hacia atrás, pero requiere la sintaxis de suscripción a stores que es inconsistente con el modelo de runes de Svelte 5. Usa $app/state en todo el código nuevo.

Usar page.url.hash Durante SSR

page.url.hash siempre es una cadena vacía en el servidor porque las solicitudes HTTP no incluyen fragmentos hash. Leerlo durante SSR y esperar un valor significativo causa fallos silenciosos que solo son evidentes al probar en un navegador real.

<!-- AVOID: Assumes hash is available during SSR -->

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

	// This will always be '' on the server, causing a flash
	let activeSection = $state(page.url.hash.slice(1) || 'overview')
</script>

<!-- PREFERRED: Read hash only in the browser -->

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

	let activeSection = $state('overview')

	$effect(() => {
		if (page.url.hash) {
			activeSection = page.url.hash.slice(1)
		}
	})
</script>

El $effect se ejecuta solo en el navegador, por lo que el hash siempre está disponible cuando el código se ejecuta.

Comparar page.route.id Sin Verificar null

page.route.id puede ser null en páginas de error, porque los errores pueden ocurrir antes de que una ruta sea completamente emparejada. Siempre protege contra null al usarlo en lógica.

<!-- AVOID: Throws if route.id is null on an error page -->
<script lang="ts">
	import { page } from '$app/state'
	let inBlog = $derived(page.route.id.startsWith('/blog'))
</script>

<!-- PREFERRED: Safe null check -->
<script lang="ts">
	import { page } from '$app/state'
	let inBlog = $derived(page.route.id?.startsWith('/blog') ?? false)
</script>

Consideraciones de Rendimiento y Escalabilidad

Debido a que page es un objeto reactivo de grano fino, leer solo las propiedades que necesitas mantiene los componentes eficientes. Un componente de navegación que lee page.url.pathname solo se vuelve a renderizar cuando el pathname cambia. No se vuelve a renderizar cuando page.data cambia, ni cuando una acción de formulario llena page.form. Esta precisión es gratuita; el sistema de reactividad rastrea el acceso a propiedades automáticamente durante el renderizado.

page.data merece particular cuidado en los componentes de layout raíz. Debido a que page.data refleja los datos fusionados de cualquier página activa actualmente, leerlo ampliamente en un layout raíz crea una dependencia que hace que el layout se vuelva a renderizar cada vez que cualquier página en algún lugar de la aplicación cambie sus datos. Prefiere leer solo las claves específicas que necesitas: page.data.title en lugar de una desestructuración extendida del objeto completo.

Para page.form, ten en cuenta que el resultado de la acción de formulario se serializa y se envía como parte de la respuesta de navegación. Los objetos grandes devueltos por acciones de formulario forman parte del payload de datos de la página. Devuelve solo lo mínimo necesario para la UI del formulario, particularmente los valores de los campos y los mensajes de error; evita devolver conjuntos de datos grandes desde las acciones de formulario.

Cuándo NO Usar page

page de $app/state está diseñado para componentes que necesitan leer el estado de la ruta actual de forma reactiva. No es un sustituto de los datos de las funciones load.

Los datos que requieren procesamiento del lado del servidor, acceso a la base de datos, autenticación o transformación antes de que sea seguro exponerlos deben pasar por una función load y llegar como data a través de $props(). Hacer fetch dentro de un componente usando page.url como parámetro del fetch es el mismo anti-patrón que hacer fetch dentro de un componente en general: se ejecuta después de que el componente se monta, no se beneficia del SSR y crea un flash de carga.

Del mismo modo, page.params es útil para leer valores de parámetros en un componente que no es el componente de página en sí. Si estás dentro de +page.svelte y quieres los params, leerlos desde page.params y leerlos desde el retorno de la función load son igualmente correctos, pero usar la prop data tipada suele ser más limpio porque el tipo es preciso y el valor a menudo ya ha sido validado por la función load.

Conclusión

El objeto page de $app/state es el puente entre el sistema de rutas de SvelteKit y tu árbol de componentes. Cada componente de la aplicación puede leer la URL actual, el patrón de ruta actual, los datos de la página actual, el resultado de la acción de formulario actual y el estado HTTP actual desde él, sin props, sin stores y sin suscripciones manuales. Se actualiza de forma reactiva en cada navegación y se llena con valores significativos durante el SSR para que no haya inconsistencias de entorno.

Entender qué propiedad sirve para cada caso de uso ahorra una cantidad significativa de trabajo arquitectónico. page.url.pathname para la detección de enlaces activos. page.route.id para la lógica a nivel de sección. page.data para los datos que fluyen hacia arriba a los layouts padre. page.form para la mejora progresiva de formularios. page.state para el enrutamiento superficial con soporte del botón de retroceso.

Puntos Clave

page se importa desde $app/state y refleja el estado de navegación actual como un objeto reactivo de grano fino. En aplicaciones SvelteKit con Svelte 5, siempre usa $app/state en lugar de $app/stores.

page.url es un objeto URL. page.url.hash siempre está vacío en el servidor; léelo solo dentro de $effect. page.params refleja lo que recibe la función load. page.route.id es el patrón de ruta, no la URL resuelta; protégelo contra null en páginas de error.

page.data contiene la salida fusionada de todas las funciones load activas. Es la forma correcta de leer datos a nivel de página desde un layout padre, por ejemplo para establecer el <title> del documento. page.form contiene el resultado más reciente de la acción de formulario y se reinicia a null en la navegación. page.state refleja el estado de la entrada del historial establecido con pushState o replaceState.

Qué Sigue

Con el objeto page comprendido, tienes una imagen completa de cómo la salida de las funciones load llega a los componentes y cómo el estado de navegación de la aplicación se expone de forma reactiva. La próxima decisión importante en la arquitectura de SvelteKit es entender cuál de los dos tipos de archivos de funciones load usar para una situación dada. El siguiente artículo, Universal vs Server Load Functions, cubre la distinción en detalle: dónde se ejecuta cada una, a qué puede acceder cada una y cómo combinarlas cuando una ruta necesita ambas.

Lecturas Adicionales

Documentación de $app/state — referencia oficial para la API completa del objeto page, incluyendo todas las propiedades y sus tipos
Documentación oficial de Load de SvelteKit — cubre cómo las funciones load producen los datos que refleja page.data
Documentación de Form Actions de SvelteKit — cómo funcionan las acciones de formulario y producen el resultado que aparece en page.form
Shallow Routing de SvelteKit — pushState, replaceState y los patrones de page.state cubiertos en este artículo