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 em 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: assim que uma página é renderizada, como um componente que não é o próprio componente de página lê a rota atual, a URL atual ou o usuário atual?

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

Entender o objeto page não é 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 lado do servidor. Este artigo é uma referência completa sobre o que ele contém, como funciona seu modelo de reatividade 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 cada página da aplicação. Cada link de nav deve aparecer destacado quando o usuário está na sua rota correspondente. O componente de nav não recebe nenhuma prop; ele não tem um canal natural para saber qual rota está ativa no momento.

Sem page, as opções são limitadas. Você poderia passar a URL atual como prop 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 nav lê, que é o padrão correto para alguns casos de uso, mas adiciona 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 o SSR porque não há location do navegador no servidor.

O objeto page resolve os três problemas de uma vez. Ele está disponível em qualquer lugar, funciona no servidor durante o SSR com valores realistas derivados da requisição HTTP recebida, e é atualizado 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 inscrição, 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 ocorre uma navegação 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 o 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 lado do servidor, o objeto page é populado a partir da requisição HTTP recebida. 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 renderiza uma vez, usando esse instantâneo de estado, e o resultado é enviado como HTML. Quando o navegador assume e hidrata a página, o objeto page é inicializado com os mesmos valores e o comportamento do componente permanece consistente.

Durante a navegação do 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.

Cada Propriedade Explicada

page.url

page.url é um objeto URL padrão da Web API representando 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 do 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, então 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. Ler a partir dela em um $derived cria uma dependência que faz o valor derivado atualizar 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 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>

Na maioria dos casos, page.params e data da função load são os lugares certos para obter essas informações, e eles contêm os mesmos valores de parâmetros. A diferença é que data requer que uma função load exista e 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]. Crucialmente, é o padrão em vez do valor resolvido. Duas URLs diferentes como /blog/introduction-to-svelte e /blog/advanced-runes produzem o mesmo 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 visualização de página por tipo de rota, renderização condicional que difere entre rotas em 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 layouts intermediários, e o próprio load da página. É o mesmo objeto que +page.svelte recebe através da 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 só veem o valor de retorno da própria função load mesclado com seus ancestrais. page.data é a forma limpa e suportada pelo framework de fazer informações fluírem 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 todas as possíveis formas de dados de página, porque em tempo de execução o layout raiz simplesmente não sabe qual página está ativa. Você normalmente declara App.PageData com propriedades opcionais que qualquer página pode fornecer, e trata a ausência delas com coalescência nula como mostrado acima.

page.status

page.status é o código de status HTTP da resposta atual como um número. Para uma página normalmente renderizada é 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á status 200; a própria resposta de redirecionamento não é uma renderização de página.

page.status é mais útil no componente +error.svelte, onde permite renderizar condicionalmente mensagens diferentes 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 de 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 de uma exceção inesperada. É um objeto com uma string message. Para erros esperados lançados com error(status, message), ele 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 de 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 de +page.server.ts e contém o que essa action retornou. Quando nenhuma ação de formulário foi executada, ou quando o usuário navega para outro lugar e volta, page.form é null.

Esta propriedade é como formulários com aprimoramento progressivo expõem resultados de validação do lado do servidor ao 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 disponibiliza esse objeto como page.form no componente de 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 as mensagens de validação aparecerem sem nenhum JavaScript do 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 qual 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 o modal desaparecer. Esse padrão é a forma correta de implementar modais, drawers e outros overlays que devem ser fecháveis com o botão voltar do navegador, sem o overhead de navegação de página completa.

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 retroativa, 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 o SSR

page.url.hash é sempre uma string vazia no servidor porque as requisições HTTP não incluem fragmentos hash. Ler isso durante o SSR e esperar um valor significativo causa falhas silenciosas que só são aparentes quando testadas 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, então 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, porque erros podem ocorrer antes que uma rota seja completamente 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 Performance e Escalabilidade

Como page é um objeto reativo de granularidade fina, ler apenas as propriedades que você precisa 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 cuidado 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 lugar da aplicação muda seus dados. Prefira ler apenas as chaves específicas que você precisa: page.data.title em vez de um spread desestruturado do objeto inteiro.

Para page.form, note 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 é 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 ao banco de dados, autenticação ou transformação antes de serem seguros para expor 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 é o mesmo anti-padrão de fazer fetch dentro de um componente em geral: é 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ê está dentro de +page.svelte e quer os params, lê-los de page.params e lê-los do retorno da função de carregamento são igualmente corretos, mas usar o prop data tipado geralmente é mais limpo porque o tipo é preciso e o valor muitas vezes 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 reativamente em cada navegação, e é populado com valores significativos durante o SSR, portanto 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 em nível de seção. page.data para dados que fluem para cima 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 em nível de 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 do 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 reativamente. 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 por completo: 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