O que é o Objeto page

Os dois artigos anteriores estabeleceram que as funções load retornam dados antes de uma página ser renderizada, e que as funções load de layout compartilham esses dados com todas as rotas filhas de um segmento. O que ficou em aberto foi uma questão prática que surge imediatamente em aplicações reais: uma vez que a página é renderizada, como um componente que não é o componente da página em si pode ler a rota atual, a URL atual ou o usuário atual?

O SvelteKit responde a isso com o objeto page, exportado de $app/state. É uma store reativa que reflete o estado atual da navegação da aplicação a qualquer momento. Qualquer componente na árvore pode importá-lo e lê-lo, sem prop-drilling e sem precisar assinar uma store customizada. Quando o usuário navega para uma rota diferente, todos os valores do objeto page são atualizados automaticamente, e qualquer componente que leia esses valores é re-renderizado de acordo.

Compreender o objeto page não é um conhecimento opcional. Ele aparece em componentes de navegação que destacam o link ativo, em layouts raiz que definem o título do documento dinamicamente, em limites de erro que leem page.status, e em formulários que leem page.form para resultados de ações do servidor. Este artigo é uma referência completa para o que ele contém, como seu modelo de reatividade funciona, e as situações em que cada propriedade é útil.

Por que o Objeto page Existe

Considere uma barra de navegação padrão. Ela é renderizada no nível do layout raiz, envolvendo todas as páginas da aplicação. Cada link de navegação deve aparecer destacado quando o usuário estiver na rota correspondente. O componente de navegação não recebe nenhuma prop; ele não tem um canal natural para saber qual rota está atualmente ativa.

Sem page, as opções são limitadas. Você poderia passar a URL atual como prop a partir do layout raiz, o que significa passá-la por todos os componentes intermediários. Você poderia criar um contexto Svelte que o layout raiz escreve e o componente de navegação lê, o que é o padrão certo para alguns casos de uso, mas adiciona código boilerplate para algo que o framework já conhece. Você poderia derivar a rota ativa do objeto location do navegador, mas isso não funciona durante SSR porque não há location do navegador no servidor.

O objeto page resolve os três problemas de uma vez. Está disponível em qualquer lugar, funciona no servidor durante SSR com valores realistas derivados da requisição HTTP de entrada, e atualiza reativamente sempre que a rota muda.

<!-- 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>

A diretiva class:active é reavaliada toda vez que page.url.pathname muda. Sem assinatura, sem cleanup, sem manipulação manual de store. A reatividade é implícita, exatamente como é com $state no código de componentes do Svelte 5.

Como Funciona a Reatividade do page

O objeto page de $app/state é um objeto reativo simples apoiado pelo sistema de reatividade refinada do Svelte 5. Ler qualquer propriedade dele durante a renderização de um componente cria uma dependência nessa propriedade. Quando a navegação ocorre e o SvelteKit atualiza os valores dentro de page, apenas os componentes que leram as propriedades alteradas são re-renderizados.

Isso é diferente de $app/stores, a API mais antiga do Svelte 4, que expunha page como uma store Svelte que exigia assinatura explícita com $page. A versão de $app/state funciona sem nenhuma sintaxe de assinatura porque é construída sobre runes. Se você estiver lendo documentação ou código que usa $page com um prefixo de cifrão e importa de $app/stores, esse é o padrão mais antigo. Esta série usa $app/state exclusivamente.

Durante a renderização no servidor (SSR), o objeto page é populado a partir da requisição HTTP de entrada. page.url reflete a URL da requisição, page.params reflete os parâmetros de rota resolvidos, e page.data reflete a saída mesclada de todas as funções load que foram executadas para aquela requisição. O componente é renderizado uma vez, usando aquele snapshot de estado, e o resultado é enviado como HTML. Quando o navegador assume o controle e hidrata a página, o objeto page é inicializado com os mesmos valores e o comportamento do componente permanece consistente.

Durante a navegação no lado do cliente, o SvelteKit atualiza o objeto page antes de re-renderizar os componentes afetados. A sequência é: navegação acionada, funções load executadas para a nova rota, page atualizado com novos valores, componentes afetados re-renderizados. Os componentes não recebem notificação explícita de que a navegação ocorreu; eles simplesmente leem de page e o sistema de reatividade do Svelte cuida do resto.

Todas as Propriedades Explicadas

page.url

page.url é um objeto URL padrão da Web API que representa a URL completa da página atual. Ele expõe todas as propriedades que você esperaria de uma URL: pathname, search, searchParams, hash, origin, href, e o restante.

<!-- 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>

Uma ressalva importante no lado do servidor: page.url.hash é sempre uma string vazia durante o SSR. O navegador remove o fragmento hash antes de enviar a requisição HTTP, portanto o servidor nunca o vê. Qualquer lógica que dependa do hash deve ser executada apenas no navegador. O padrão correto é verificar page.url.hash dentro de $effect() ou dentro de um manipulador de eventos, nunca durante a inicialização do componente que é executada durante o SSR.

page.url.searchParams é uma instância de URLSearchParams. É somente leitura através de page.url; para alterar os parâmetros de busca, você navega programaticamente usando a função goto() do SvelteKit de $app/navigation. Lê-lo em um $derived cria uma dependência que faz com que o valor derivado seja atualizado sempre que os parâmetros de busca mudam, o que é o padrão correto para coisas como UI de filtragem reativa.

page.params

page.params é um objeto simples cujas chaves correspondem aos segmentos dinâmicos no nome do diretório da rota ativa. Para uma rota em src/routes/shop/[category]/[productId]/+page.svelte, o objeto terá category e productId como chaves do tipo 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>

Na maioria dos casos, page.params e data da função load são os lugares certos para obter essa informação, e eles contêm os mesmos valores de parâmetro. A diferença é que data requer que exista uma função load e que ela retorne algo, enquanto page.params está sempre disponível independentemente de haver uma função load.

page.route

page.route é um objeto com uma única propriedade: id. O id é o padrão da rota como uma string na notação entre colchetes que espelha a estrutura de diretórios, por exemplo /blog/[slug] ou /shop/[category]/[productId]. De forma crucial, é o padrão e não o valor resolvido. Duas URLs diferentes como /blog/introduction-to-svelte e /blog/advanced-runes produzem um route.id de /blog/[slug].

Isso torna page.route.id útil para lógica que precisa saber qual template de rota está ativo, independentemente dos valores específicos. Código de analytics que rastreia eventos de page-view por tipo de rota, renderização condicional que difere entre rotas de uma seção, e middleware de logging que classifica requisições, todos se beneficiam do padrão de rota em vez da URL resolvida.

<!-- 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 é a saída mesclada de todas as funções load ativas para a rota atual. Inclui dados do load do layout raiz, quaisquer loads de layout intermediários, e o load da página em si. É o mesmo objeto que +page.svelte recebe através de sua prop data, mas acessível de qualquer lugar, incluindo de layouts pai que precisam ler dados de uma página filha que estão envolvendo.

O caso de uso canônico é um layout raiz definindo o <title> do documento dinamicamente com base no que a função load da página atual retornou:

<!-- 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
	}
}

O layout raiz não tem como receber title e description através da prop de dados normal, porque os dados fluem para baixo e os layouts apenas veem o valor de retorno de sua própria função load mesclado com o de seus ancestrais. page.data é a forma limpa e suportada pelo framework para fluir informações para cima de uma página para um layout pai.

O tipo TypeScript para page.data é determinado por App.PageData nas declarações de tipo da sua aplicação. O SvelteKit não infere automaticamente isso como uma união de todos os formatos possíveis de dados de página, porque em tempo de execução o layout raiz simplesmente não sabe qual página está ativa. Normalmente você declara App.PageData com propriedades opcionais que qualquer página pode fornecer, e trata a ausência delas com coalescência nula conforme mostrado acima.

page.status

page.status é o código de status HTTP da resposta atual como um número. Para uma página renderizada normalmente, é 200. Para uma página renderizada porque uma função load chamou error(404, 'Not found'), é 404. Para um redirecionamento, a página no destino do redirecionamento terá um status 200; a resposta de redirecionamento em si não é uma renderização de página.

page.status é mais útil no componente +error.svelte, onde permite renderizar condicionalmente diferentes mensagens para diferentes tipos de erro sem duplicar a página de erro em múltiplos arquivos:

<!-- 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}

Você também pode ler page.status em componentes de página e layouts normais, o que é menos comum, mas ocasionalmente útil para UI que deve se comportar de forma diferente em estados de erro.

page.error

page.error é populado quando o SvelteKit está renderizando uma página de erro por causa de uma chamada error() lançada ou uma exceção inesperada. É um objeto com uma string message. Para erros esperados lançados com error(status, message), terá a mensagem que você forneceu. Para erros inesperados, conterá a mensagem do seu hook handleError, ou um 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>

Fora das páginas de erro, page.error é null. Não há necessidade de se proteger contra isso em componentes de página normais.

page.form

page.form é o resultado retornado pela ação de formulário executada mais recentemente. É populado após o envio de um formulário para uma função action em +page.server.ts e contém o que essa action retornou. Quando nenhuma action de formulário foi executada, ou quando o usuário navega para outro lugar e volta, page.form é null.

Esta propriedade é a forma como formulários progressivamente aprimorados surfaceiam resultados de validação do servidor para o componente sem recarregar a 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 }
	}
}

A action retorna um objeto simples. O SvelteKit torna esse objeto disponível como page.form no componente da página. Se o usuário atualizar a página, page.form é redefinido para null. Se o JavaScript estiver desabilitado, a mesma action é executada e o SvelteKit re-renderiza a página no servidor com o resultado da action, fazendo com que as mensagens de validação apareçam sem nenhum JavaScript no lado do cliente.

page.state

page.state é o valor do objeto de estado da entrada de histórico atual, definido usando pushState() ou replaceState() do SvelteKit de $app/navigation. Este é um mecanismo de roteamento superficial: permite atualizar o que um componente renderiza, e opcionalmente o que a URL aparece na barra de endereços do navegador, sem acionar uma navegação completa e sem executar as funções load novamente.

<!-- 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}

Quando pushState é chamado com um objeto de estado, o SvelteKit atualiza page.state reativamente. O modal aparece. Quando o usuário clica no botão Voltar do navegador, a entrada de histórico muda e page.state retorna ao seu valor anterior, fazendo com que o modal desapareça. Este padrão é a forma correta de implementar modais, drawers e outros overlays que devem ser dispensáveis com o botão voltar do navegador, sem a sobrecarga de uma navegação completa de página.

Erros Comuns e Anti-Padrões

Importando de $app/stores em vez de $app/state

O Svelte 4 expunha o objeto page através de $app/stores como uma store Svelte, exigindo import { page } from '$app/stores' e $page (com o prefixo de auto-assinatura) para ler valores dentro de um 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>

A API $app/stores ainda funciona no SvelteKit para compatibilidade com versões anteriores, mas requer a sintaxe de assinatura de store que é inconsistente com o modelo de runes do Svelte 5. Use $app/state em todo código novo.

Usando page.url.hash Durante SSR

page.url.hash é sempre uma string vazia no servidor porque as requisições HTTP não incluem fragmentos hash. Lê-lo durante o SSR e esperar um valor significativo causa falhas silenciosas que só são aparentes ao testar em um 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>

O $effect é executado apenas no navegador, portanto o hash está sempre disponível quando o código é executado.

Comparando page.route.id Sem Verificar null

page.route.id pode ser null em páginas de erro, pois erros podem ocorrer antes que uma rota seja totalmente correspondida. Sempre proteja contra null ao usá-lo em 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>

Considerações de Desempenho e Escalabilidade

Como page é um objeto reativo de granularidade fina, ler apenas as propriedades necessárias mantém os componentes eficientes. Um componente de navegação que lê page.url.pathname só é re-renderizado quando o pathname muda. Ele não é re-renderizado quando page.data muda, ou quando uma action de formulário popula page.form. Essa precisão é gratuita; o sistema de reatividade rastreia o acesso às propriedades automaticamente durante a renderização.

page.data merece atenção especial em componentes de layout raiz. Como page.data reflete os dados mesclados de qualquer página atualmente ativa, lê-lo amplamente em um layout raiz cria uma dependência que faz o layout ser re-renderizado sempre que qualquer página em qualquer parte da aplicação alterar seus dados. Prefira ler apenas as chaves específicas de que você precisa: page.data.title em vez de uma desestruturação completa do objeto.

Para page.form, observe que o resultado da action de formulário é serializado e enviado como parte da resposta de navegação. Objetos grandes retornados de actions de formulário tornam-se parte do payload de dados da página. Retorne apenas o mínimo necessário para a UI do formulário, especialmente valores de campos e mensagens de erro; evite retornar grandes conjuntos de dados de actions de formulário.

Quando NÃO Usar page

page de $app/state foi projetado para componentes que precisam ler o estado da rota atual de forma reativa. Ele não é um substituto para dados de funções de carregamento.

Dados que requerem processamento no servidor, acesso a banco de dados, autenticação ou transformação antes de ser seguro expô-los devem passar por uma função de carregamento e chegar como data através de $props(). Fazer fetch dentro de um componente usando page.url como parâmetro de fetch é o mesmo antipadrão que fazer fetch dentro de um componente em geral: ele é executado após a montagem do componente, não se beneficia do SSR e cria um flash de carregamento.

Da mesma forma, page.params é útil para ler valores de parâmetros em um componente que não é o próprio componente de página. Se você estiver dentro de +page.svelte e quiser os parâmetros, lê-los de page.params e lê-los do retorno da função de carregamento são igualmente corretos, mas usar a prop data tipada geralmente é mais limpo porque o tipo é preciso e o valor frequentemente já foi validado pela função de carregamento.

Conclusão

O objeto page de $app/state é a ponte entre o sistema de rotas do SvelteKit e sua árvore de componentes. Todo componente da aplicação pode ler a URL atual, o padrão de rota atual, os dados da página atual, o resultado da action de formulário atual e o status HTTP atual a partir dele, sem props, sem stores e sem assinaturas manuais. Ele é atualizado de forma reativa a cada navegação e é populado com valores significativos durante o SSR, de modo que não há inconsistências de ambiente.

Entender qual propriedade serve a cada caso de uso economiza uma quantidade significativa de trabalho arquitetural. page.url.pathname para detecção de link ativo. page.route.id para lógica no nível de seção. page.data para dados que fluem para layouts pai. page.form para aprimoramento progressivo de formulários. page.state para shallow routing com suporte ao botão voltar.

Principais Conclusões

page é importado de $app/state e reflete o estado de navegação atual como um objeto reativo de granularidade fina. Em aplicações SvelteKit com Svelte 5, sempre use $app/state em vez de $app/stores.

page.url é um objeto URL. page.url.hash é sempre vazio no servidor; leia-o apenas dentro de $effect. page.params espelha o que a função de carregamento recebe. page.route.id é o padrão de rota, não a URL resolvida; proteja-o contra null em páginas de erro.

page.data contém a saída mesclada de todas as funções de carregamento ativas. É a forma correta de ler dados no nível da página a partir de um layout pai, por exemplo, para definir o <title> do documento. page.form contém o resultado mais recente da action de formulário e é redefinido para null na navegação. page.state reflete o estado da entrada de histórico definido com pushState ou replaceState.

O Que Vem a Seguir

Com o objeto page compreendido, você tem uma visão completa de como a saída da função de carregamento chega aos componentes e como o estado de navegação da aplicação é exposto de forma reativa. A próxima grande decisão na arquitetura SvelteKit é entender qual dos dois tipos de arquivo de função de carregamento usar para uma determinada situação. O próximo artigo, Universal vs Server Load Functions, aborda a distinção completa: onde cada um é executado, o que cada um pode acessar e como combiná-los quando uma rota precisa de ambos.

Leitura Adicional

Documentação do $app/state — referência oficial para a API completa do objeto page, incluindo todas as propriedades e seus tipos
Documentação Oficial de Load do SvelteKit — aborda como as funções de carregamento produzem os dados que page.data reflete
Documentação de Form Actions do SvelteKit — como as actions de formulário funcionam e produzem o resultado que aparece em page.form
Shallow Routing do SvelteKit — pushState, replaceState e os padrões de page.state abordados neste artigo