O que é `+page.svelte`?

O arquivo +page.svelte é o coração de qualquer rota no SvelteKit. Ele define o que os usuários veem quando acessam uma URL. É um componente Svelte padrão com um nome especial que o SvelteKit reconhece como uma página.

+page.svelte é responsável pela camada visual da sua rota. O carregamento de dados pertence ao +page.js ou +page.server.js, as mutações de servidor pertencem às actions de formulário, e os utilitários compartilhados pertencem ao $lib. Quando cada arquivo tem uma função bem definida, as páginas permanecem legíveis e a refatoração se torna mecânica em vez de arriscada.

Sua Primeira Página: A Página Inicial

A rota mais importante em qualquer aplicação é a rota raiz, ou "página inicial". No SvelteKit, isso corresponde à raiz do seu diretório src/routes.

Se você criar um arquivo em src/routes/+page.svelte, estará definindo o conteúdo para https://seu-site.com/.

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

<h1>Welcome to My Website</h1>
<p>This is the homepage.</p>

Pronto. Acesse http://localhost:5173/ no seu navegador e você verá este conteúdo. Sem arquivos de configuração, sem registro de rotas — apenas um arquivo no lugar certo.

Adicionando Mais Páginas

Vamos expandir sua aplicação com páginas adicionais.

Página Sobre

Na pasta routes, adicione uma nova pasta chamada about e dentro dela crie o +page.svelte:

<!-- src/routes/about/+page.svelte -->
<h1>About Us</h1>
<p>We are a company that builds amazing things.</p>

<h2>Our Mission</h2>
<p>To make the web a better place, one component at a time.</p>

Página de Contato

Agora crie outra pasta chamada contact com seu próprio +page.svelte:

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

<form>
	<label>
		Name:
		<input type="text" name="name" />
	</label>

	<label>
		Email:
		<input type="email" name="email" />
	</label>

	<label>
		Message:
		<textarea name="message"></textarea>
	</label>

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

Estrutura de Diretórios

A estrutura de diretórios do seu projeto agora se parece com:

src/routes/
├── +page.svelte          → /
├── about/
│   └── +page.svelte      → /about
└── contact/
    └── +page.svelte      → /contact

Cada pasta se torna um segmento de URL. Cada +page.svelte define o que é renderizado naquela URL.

Páginas São Apenas Componentes Svelte

Um arquivo +page.svelte é um componente Svelte comum. Você pode usar tudo o que sabe sobre Svelte:

Estado com Runes

Você pode usar o sistema de reatividade do Svelte 5 diretamente nas suas páginas. A rune $state permite criar estado local que atualiza a UI quando alterado.

<!-- src/routes/counter/+page.svelte -->
<script lang="ts">
	let count = $state(0)
</script>

<h1>Counter</h1>
<p>Count: {count}</p>
<button onclick={() => count++}>Increment</button>

Para um mergulho profundo nas runes e na reatividade do Svelte 5, confira nosso guia completo de Runes do Svelte 5.

Importando Componentes

As páginas podem importar e usar outros componentes Svelte. Isso permite que você construa interfaces complexas compondo peças menores e reutilizáveis.

Vamos criar dois componentes: Button.svelte e Hero.svelte.

<!-- src/lib/components/Button.svelte -->
<script lang="ts">
	// Svelte 5: Use $props() to receive props
	let { onclick, children } = $props()
</script>

<button {onclick}>
	{@render children?.()}
</button>

<style>
	button {
		background-color: var(--brand);
		color: white;
		border: none;
		padding: 0.5rem 1rem;
		border-radius: 0.25rem;
		cursor: pointer;
		font-size: 1rem;
	}
</style>

<!-- src/lib/components/Hero.svelte -->
<script lang="ts">
	// Svelte 5: Use $props() to receive props
	let { title, subtitle } = $props()
</script>

<section class="hero">
	<h1>{title}</h1>
	<p>{subtitle}</p>
</section>

<style>
	.hero {
		padding: 2rem;
		background-color: var(--brand-light);
		color: var(--brand-dark);
		border-radius: 0.5rem;
		text-align: center;
	}
</style>

Agora você pode usar esses componentes nos seus arquivos +page.svelte:

<!-- src/routes/+page.svelte -->
<script lang="ts">
	import Button from '$lib/components/Button.svelte'
	import Hero from '$lib/components/Hero.svelte'
</script>

<Hero title="Welcome" subtitle="To my amazing website" />

<Button onclick={() => alert('Clicked!')}>Click me</Button>

Estilização

Os estilos em +page.svelte são escopados ao componente por padrão. Isso significa que você pode escrever CSS sem se preocupar com o impacto em outras partes da sua aplicação.

<!-- src/routes/about/+page.svelte -->
<h1>About Us</h1>
<p class="intro">We build amazing things.</p>

<style>
	h1 {
		color: var(--brand);
		font-size: 2.5rem;
	}

	.intro {
		font-size: 1.25rem;
		color: var(--text-dimmed);
	}
</style>

Ciclo de Vida: Páginas Montam e Desmontam

Como as páginas são apenas componentes Svelte, elas seguem o ciclo de vida normal do Svelte 5. Quando você navega entre páginas, a página antiga desmonta e a nova página monta. A forma idiomática do Svelte 5 de responder a esses eventos é o $effect, que é executado após o componente montar e pode retornar uma função de limpeza opcional que é executada antes de desmontar:

<!-- src/routes/+page.svelte -->
<script lang="ts">
	$effect(() => {
		console.log('Home page mounted')

		// Return a cleanup function that runs when the page unmounts
		return () => console.log('Home page unmounting')
	})
</script>

<h1>Home</h1>

Esse padrão é útil para cancelar assinaturas, limpar timers ou remover event listeners que foram adicionados quando a página carregou. As funções onMount e onDestroy ainda funcionam no Svelte 5, mas o $effect é a abordagem unificada que lida tanto com a configuração quanto com a limpeza em uma única função.

Como os layouts persistem durante a navegação entre páginas que compartilham um layout, apenas o componente de página em si monta e desmonta — o layout que o envolve permanece ativo. Isso importa quando você está liberando recursos: efeitos colaterais em um componente de página têm escopo de página, enquanto efeitos colaterais em um componente de layout vivem enquanto o usuário permanecer naquela seção do aplicativo.

Entendendo o Server-Side Rendering (SSR)

Se você já criou Single Page Applications (SPAs) antes, pode estar familiarizado com a "tela branca da morte". Isso acontece porque o navegador baixa um arquivo HTML essencialmente vazio e precisa esperar que um grande bundle JavaScript seja baixado, analisado e executado antes de mostrar qualquer coisa ao usuário. Em uma conexão lenta ou dispositivo de baixo desempenho, essa lacuna pode durar segundos.

O SvelteKit resolve isso com Server-Side Rendering (SSR). O conceito é direto: em vez de enviar uma página em branco e deixar o JavaScript construir a UI, o servidor executa seus componentes Svelte primeiro, produz HTML completo e o envia ao navegador. O usuário vê conteúdo real imediatamente, antes que um único byte de JavaScript tenha sido executado.

Como o SSR Funciona

Veja o que acontece quando um usuário acessa sua página /about:

A Requisição: O navegador do usuário solicita ao servidor a página /about.
O Servidor Trabalha: O SvelteKit executa suas funções de load para buscar os dados, depois executa seus componentes Svelte no servidor, produzindo um snapshot HTML completo da página.
A Entrega: O servidor envia este HTML completo ao navegador. O usuário vê o conteúdo (texto, imagens, layout) imediatamente — nenhum JavaScript é necessário para esta primeira renderização.
A Transferência (Hidratação): Um momento depois, o bundle JavaScript carrega e o Svelte "hidrata" a página — ele anexa os event listeners e torna a página interativa. Esse processo é invisível para o usuário; o HTML que ele já estava vendo simplesmente ganha interatividade.

sequenceDiagram
    participant Browser
    participant Server
    participant Database

    Browser->>Server: GET /about
    Server->>Database: Fetch data
    Database->>Server: Return data
    Server->>Server: Render Svelte component
    Server->>Browser: Send complete HTML
    Note over Browser: User sees content immediately
    Browser->>Browser: Download JavaScript
    Browser->>Browser: Hydrate (attach events)
    Note over Browser: Page becomes interactive

Por que o SSR Importa

Os benefícios se acumulam de maneiras que fazem diferença em aplicações reais. Os mecanismos de busca podem rastrear seu conteúdo porque ele chega como HTML — nenhuma execução de JavaScript é necessária. Conexões lentas ainda entregam uma página utilizável imediatamente em vez de um spinner. Usuários com JavaScript desabilitado ou bloqueado (firewalls corporativos, extensões de privacidade, erros de script) veem seu conteúdo em vez de uma página em branco.

Você não precisa configurar nada para que isso funcione. O SSR é o comportamento padrão no SvelteKit e se aplica a cada +page.svelte automaticamente.

Veja o SSR em Ação

Quer provar que seu código roda tanto no servidor quanto no cliente? Adicione um console.log a qualquer página:

<!-- src/routes/+page.svelte -->
<script lang="ts">
	console.log('Hello from the page!')
</script>

<h1>Home</h1>

Atualize a página e verifique tanto o seu terminal (servidor) quanto o console do navegador (cliente). Você verá "Hello from the page!" em ambos os lugares. Isso prova que o componente renderiza duas vezes:

Primeiro no servidor (você o vê no terminal)
Depois no cliente durante a hidratação (você o vê nas DevTools do navegador)

Essa execução dupla é fundamental para entender o SvelteKit!

Recebendo Dados das Funções de Load

Embora o +page.svelte possa funcionar completamente por conta própria, seu verdadeiro poder vem quando combinado com o carregamento de dados. Quando você coloca um arquivo +page.js ou +page.server.js no mesmo diretório que o +page.svelte, o SvelteKit os conecta automaticamente: ele executa a função de load primeiro, aguarda sua conclusão e passa o valor retornado para o componente de página como a prop data.

A conexão é feita por convenção de nomenclatura — ambos os arquivos residem no mesmo diretório de rota, e o SvelteKit sabe que eles pertencem juntos. Você não importa um do outro. Não há conexão explícita. O fato de +page.ts e +page.svelte compartilharem a mesma pasta é suficiente:

src/routes/blog/
├── +page.ts       ← SvelteKit runs this, gets { posts: [...] }
└── +page.svelte   ← SvelteKit passes { posts: [...] } here as data

<!-- src/routes/blog/+page.svelte -->
<script lang="ts">
	import type { PageProps } from './$types'

	// data is everything returned from +page.ts — typed automatically
	let { data }: PageProps = $props()
</script>

<h1>Blog</h1>

{#each data.posts as post}
	<article>
		<h2>{post.title}</h2>
		<p>{post.excerpt}</p>
	</article>
{/each}

Se você adicionar um +page.js mas acessar um campo que ele não retorna, o TypeScript avisa imediatamente — sem surpresas em tempo de execução. Isso é abordado em profundidade em +page.js (para dados públicos) e +page.server.js (para consultas ao banco de dados e segredos).

Tratando Actions de Formulário

Além de data, +page.svelte também pode receber uma prop form. Isso é usado quando você envia um formulário para uma action de servidor (definida em +page.server.js).

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

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

{#if form?.success}
	<p class="success">Form submitted successfully!</p>
{/if}

<form method="POST">
	<!-- form fields -->
</form>

Exploraremos as actions de formulário em profundidade quando abordarmos +page.server.js.

Gerenciando o Head

`<svelte:head>`

Cada página frequentemente precisa de seu próprio título e meta tags para SEO. O Svelte fornece um elemento especial <svelte:head> que permite inserir elementos no <head> do seu documento.

<!-- src/routes/about/+page.svelte -->
<svelte:head>
	<title>About Us | My Website</title>
	<meta name="description" content="Learn more about our company and mission." />
</svelte:head>

<h1>About Us</h1>

O conteúdo de <svelte:head> em rotas aninhadas é combinado com os layouts pai. O <title> mais específico (mais profundo) prevalece, enquanto as demais tags são mescladas.

Preservando o Estado

`Snapshot`

Às vezes você quer preservar um estado efêmero — como o texto em um campo de busca — quando o usuário navega para outra página e depois clica em "voltar". O SvelteKit facilita isso com snapshots. Você define como capturar o estado na saída e como restaurá-lo no retorno.

No Svelte 5, snapshot é exportado do <script> de instância normal usando export const. Este é um dos exports não-prop que o Svelte 5 ainda suporta — export let para props foi substituído por $props(), mas export const para expor valores na instância do componente permanece válido. As funções capture e restore fecham sobre o estado reativo search no mesmo bloco de script:

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

	let search = $state('')

	export const snapshot: Snapshot<string> = {
		capture: () => search,
		restore: (value) => {
			search = value
		}
	}
</script>

<input bind:value={search} placeholder="Search..." />

Quando capture() é chamado (ao navegar para fora), ele lê o valor atual de search. Quando restore(value) é chamado (ao navegar de volta), ele escreve de volta em search, acionando a reatividade do Svelte e atualizando o campo. O fechamento sobre $state garante que isso funcione corretamente com a reatividade refinada do Svelte 5.

Snapshots são abordados em detalhes em nosso artigo sobre Navegação, incluindo padrões avançados e casos de uso.

Pré-carregamento de Dados: Navegação Instantânea

Percebe como a navegação entre páginas parece instantânea? Isso porque o SvelteKit pré-carrega dados quando você passa o mouse sobre os links.

Em seu src/app.html, você verá:

<body data-sveltekit-preload-data="hover"></body>

Isso significa que quando o mouse passa sobre um link, o SvelteKit começa a buscar os dados daquela página antes de você clicar. No momento em que você clica, os dados já estão carregados!

Você pode controlar esse comportamento:

"hover" — Pré-carregar ao passar o mouse (padrão, ótimo para desktop)
"tap" — Pré-carregar no touchstart/mousedown (melhor para mobile)
"off" — Sem pré-carregamento

Padrões Comuns

Nesta seção, exploraremos alguns padrões comuns que você usará em arquivos +page.svelte.

Renderização Condicional Baseada em Dados

Frequentemente queremos exibir conteúdo diferente com base nos dados recebidos. Por exemplo, exibir uma lista de posts ou uma mensagem caso não haja nenhum.

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

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

{#if data.posts.length > 0}
	<ul>
		{#each data.posts as post}
			<li>{post.title}</li>
		{/each}
	</ul>
{:else}
	<p>No posts yet. Check back soon!</p>
{/if}

Acessando o Estado Global da Página

Às vezes você precisa acessar a URL atual, parâmetros ou dados do usuário em qualquer lugar na árvore de componentes (não apenas em +page.svelte). O SvelteKit fornece o objeto page para isso.

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

<p>Current path: {page.url.pathname}</p>

{#if page.data.user}
	<p>Welcome back, {page.data.user.name}!</p>
{/if}

Rotas Aninhadas com Layout Compartilhado

As páginas podem ser aninhadas dentro de pastas para criar caminhos de URL. Você também pode usar arquivos +layout.svelte para compartilhar UI (como cabeçalhos ou barras laterais) entre múltiplas páginas em um diretório.

src/routes/
├── blog/
│   ├── +layout.svelte    → Wraps all blog pages
│   ├── +page.svelte      → /blog (list of posts)
│   └── [slug]/
│       └── +page.svelte  → /blog/my-post (individual post)

Saiba mais em nosso guia +layout.svelte.

Erros Comuns

1. Esquecendo o Prefixo `+`

src/routes/
├── page.svelte          WRONG: Ignored by SvelteKit
└── +page.svelte          CORRECT: This is your page

2. Esperar Dados Sem uma Função de Carregamento

<!-- AVOID: data will be empty if there's no +page.ts! -->
<script lang="ts">
	let { data } = $props()
</script>

<p>{data.title}</p> <!-- Error: title is undefined -->

Se você precisar de dados, crie um arquivo +page.js ou +page.server.js (ou seus equivalentes .ts se preferir TypeScript).

3. Usar APIs do Navegador Durante o SSR

Durante o SSR (Server-Side Rendering), seu código é executado em um ambiente Node.js onde objetos específicos do navegador como window, document ou localStorage não existem. Se você tentar acessá-los diretamente, obterá um erro em tempo de execução no servidor.

Para usar APIs do navegador com segurança, sempre verifique se está executando no navegador usando o booleano browser de $app/environment:

<script lang="ts">
	import { browser } from '$app/environment'

	// AVOID: window doesn't exist on the server!
	// const width = window.innerWidth

	// PREFERRED: Check for browser environment
	const width = browser ? window.innerWidth : 0
</script>

Conclusão

O arquivo +page.svelte é onde o roteamento encontra a UI — o componente que efetivamente renderiza o que os usuários veem ao visitar uma URL. Como um componente Svelte padrão com acesso completo a runes, imports, estilos e todos os recursos do Svelte, ele representa o ponto final do sistema de roteamento do SvelteKit onde os dados se tornam interface. Seja recebendo dados de funções de carregamento, respondendo a interações do usuário ou renderizando conteúdo dinâmico, os componentes de página são onde a funcionalidade da sua aplicação se torna tangível.

Dominar o +page.svelte significa compreender sua natureza dual: durante o SSR ele renderiza no servidor para fornecer carregamentos iniciais rápidos, e então hidrata no navegador para se tornar uma aplicação totalmente interativa. Ao tratar corretamente as props de dados com $props(), aproveitar a hierarquia de layouts para UI compartilhada e usar a constante browser para lógica específica de ambiente, você constrói páginas que funcionam em qualquer lugar enquanto se sentem rápidas e responsivas. A convenção do prefixo + e a passagem automática de props das funções de carregamento tornam a conexão entre roteamento, dados e UI fluida e intuitiva.

Pontos-Chave

+page.svelte define o que é renderizado em uma rota - é um componente Svelte padrão que se torna o conteúdo da página que os usuários veem
Recebe dados via $props() — let { data }: PageProps = $props() é automaticamente populado pelas funções de carregamento de +page.js ou +page.server.js sem nenhuma configuração extra
SSR habilitado por padrão - as páginas são renderizadas primeiro no servidor para carregamentos iniciais rápidos, depois hidratam para componentes interativos no navegador
Capacidades completas de componente Svelte - use runes ($state, $derived, $effect), imports, estilos e todos os recursos do Svelte
O prefixo + é obrigatório - o SvelteKit reconhece apenas arquivos que começam com + como arquivos de rota especiais
Use a constante browser para verificações de ambiente - de $app/environment para executar condicionalmente código exclusivo do navegador com segurança durante o SSR
Envolvido pela hierarquia de layouts - renderiza dentro dos componentes pai +layout.svelte, herdando a estrutura de UI compartilhada
Navegação automática no lado do cliente - quando os usuários navegam entre páginas, o SvelteKit troca os componentes de página sem recarregamentos completos da página

Veja Também

Documentação Oficial do SvelteKit - +page.svelte
Runes do Svelte 5 - Reatividade com $state, $derived, $effect
SSR e Hidratação — Conceitos de renderização no lado do servidor
Constante browser — Detecção de ambiente

O que é +page.svelte?