Carregamento Universal de Dados no SvelteKit

Páginas estáticas são úteis, mas aplicações reais precisam de dados. O arquivo +page.js (ou +page.ts para TypeScript) é onde você carrega dados para suas páginas. Isso é chamado de carregamento de dados universal porque o mesmo código é executado tanto no servidor quanto no navegador — e entender por que isso importa é a chave para utilizá-lo bem.

Quando um usuário visita seu app pela primeira vez (digitando uma URL ou atualizando a página), a página é renderizada no servidor. Nesse momento, o Node.js executa sua função load para buscar dados antes de enviar o HTML ao navegador. Mas quando o usuário clica em um link para outra página, não há ida e volta ao servidor — o SvelteKit executa a mesma função load diretamente no navegador. Uma função, dois ambientes, comportamento consistente. Esse é o contrato que o +page.js oferece.

A restrição que acompanha esse poder: seu código deve funcionar em ambos os ambientes. Nada de window, document, acesso direto ao banco de dados ou chaves de API privadas. Se você precisar de qualquer um desses, use +page.server.js em vez disso.

A natureza "universal" do +page.js é tanto sua força quanto sua restrição. Ela permite navegação instantânea no lado do cliente (sem ida e volta ao servidor nas visitas subsequentes), mas significa que você só pode usar código que funcione tanto no Node.js quanto no navegador. Escolha com sabedoria com base em se seus dados são públicos ou sensíveis.

Sua Primeira Função Load

Vamos criar uma página de blog que exibe uma lista de posts. Primeiro, crie um arquivo +page.ts dentro do diretório src/routes/blog/:

// src/routes/blog/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async () => {
	// In a real app, this might come from an API or database
	const posts = [
		{
			slug: 'hello-world',
			title: 'Hello World',
			excerpt: 'My first blog post ever!',
			date: '2025-01-15'
		},
		{
			slug: 'learning-svelte',
			title: 'Learning Svelte',
			excerpt: 'Why Svelte is my new favorite framework.',
			date: '2025-01-14'
		},
		{
			slug: 'routing-deep-dive',
			title: 'SvelteKit Routing Deep Dive',
			excerpt: 'Everything you need to know about routing.',
			date: '2025-01-13'
		}
	]

	return {
		posts
	}
}

Esta função load é executada sempre que um usuário visita a página /blog. Ela busca uma lista de posts do blog (codificada diretamente aqui para maior clareza) e os retorna como um objeto. O que você retornar fica disponível como data no +page.svelte correspondente — não é necessária nenhuma configuração extra; o SvelteKit os conecta automaticamente.

Conectando Dados à Página

Qualquer objeto que você retornar de sua função load fica disponível no componente de página como a prop data.

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

	// The $props() rune receives the data from the load function
	let { data }: PageProps = $props()
</script>

<h1>Blog</h1>

<ul class="post-list">
	{#each data.posts as post}
		<li>
			<article>
				<h2>
					<a href="/blog/{post.slug}">{post.title}</a>
				</h2>
				<time datetime={post.date}>{post.date}</time>
				<p>{post.excerpt}</p>
			</article>
		</li>
	{/each}
</ul>

<style>
	.post-list {
		list-style: none;
		padding: 0;
	}

	article {
		margin-bottom: 2rem;
		padding-bottom: 2rem;
		border-bottom: 1px solid #eee;
	}

	h2 {
		margin-bottom: 0.5rem;
	}

	time {
		color: #666;
		font-size: 0.875rem;
	}
</style>

Como os Dados Fluem: O Modelo Mental

Entender esse fluxo de dados é a chave para dominar o SvelteKit. É um caminho previsível e unidirecional, e o importante a internalizar é que o componente nunca espera pelos dados — no momento em que seu componente é executado, os dados já estão lá.

O Gatilho: Um usuário visita uma página (ex.: /blog)
O Carregador: O SvelteKit procura um arquivo +page.js e executa a função load
A Espera: O SvelteKit aguarda a conclusão da sua função load (incluindo quaisquer chamadas com await)
A Transferência: O objeto retornado por load é passado ao componente de página
A Renderização: O componente +page.svelte renderiza, recebendo os dados pela prop data

flowchart
    A(User visits /blog) --> B[+page.ts - load function runs]
    B --> C{Fetch & Await}
    C --> G(Data Ready)
    G --> D(Return Data Object)
    D --> H(Pass to Component)
    H --> E(Render +page.svelte)
    E --> F([Display data.posts])

    style A fill:#ffffff, color:#000
    style F fill:#e8f5e9, color:#000
    style B fill:#fff3e0, color:#000
    style E fill:#f3e5f5, color:#000
	style C fill:#ffebee, color:#000
	style G fill:#a4fcb1, color:#000
	style D fill:#f9fbe7, color:#000
	style H fill:#e1f5fe, color:#000

A função load é executada antes de seu componente renderizar. Isso significa que você não precisa gerenciar "estados de carregamento" dentro do seu componente para dados iniciais — sem flags isLoading = true, sem renderizações condicionais verificando se os dados existem. No momento em que o +page.svelte é montado, os dados têm garantia de estar lá. Isso é fundamentalmente diferente de SPAs onde os componentes buscam dados por conta própria após a montagem.

Buscando Dados de APIs

Em aplicações reais, você buscará dados de APIs. A função load do SvelteKit recebe uma função fetch customizada especial que funciona tanto no servidor quanto no navegador:

// src/routes/blog/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ fetch }) => {
	// This fetch works on server AND browser
	const response = await fetch('/api/posts')
	const posts = await response.json()

	return {
		posts
	}
}

Por Que Usar o `fetch` Fornecido?

Esta é uma das sutilezas mais importantes do SvelteKit. Se você usar o fetch global diretamente, perde várias garantias que apenas a versão fornecida oferece.

Durante o SSR, o fetch fornecido pode chamar seus próprios endpoints +server.js como se fosse um cliente — ele conhece o roteamento interno do seu app. O fetch global no Node.js precisaria de uma URL absoluta e não saberia em qual porta seu app está rodando.

Lida com rotas internas: Pode chamar seus próprios endpoints de API durante o SSR sem precisar de URLs absolutas
Deduplica requisições: Se múltiplas funções load buscarem a mesma URL, apenas uma requisição HTTP é disparada
Preserva cookies: Encaminha automaticamente os cookies do usuário para requisições autenticadas
Funciona em qualquer lugar: O mesmo código roda no servidor e no cliente sem modificação

Sempre desestruture o fetch do parâmetro da função load em vez de usar o global.

Os Parâmetros da Função Load

A função load recebe um objeto com várias propriedades úteis:

export const load: PageLoad = async ({
	fetch, // Special fetch that works server + client
	params, // Route parameters (e.g., { slug: 'my-post' })
	url, // URL object with pathname, searchParams, etc.
	route, // Information about the current route
	data // Data from parent layouts (if they exist)
}) => {
	// Your loading logic here
}

Você pode desestruturar apenas as propriedades que precisar:

export const load: PageLoad = async ({ params, url }) => {
	// Use what you need
}

Usando Parâmetros de Rota

Parâmetros de rota são segmentos dinâmicos na sua URL, definidos por colchetes nos nomes dos seus arquivos ou pastas (ex.: [slug], [id]). Quando um usuário visita uma URL que corresponde a uma rota dinâmica, o SvelteKit extrai o valor e o disponibiliza no objeto params da sua função load.

Para rotas dinâmicas como /blog/[slug], você pode acessar o parâmetro:

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

export const load: PageLoad = async ({ params, fetch }) => {
	// params.slug contains the value from the URL
	const response = await fetch(`/api/posts/${params.slug}`)
	const post = await response.json()

	return {
		post
	}
}

Para necessidades de roteamento mais complexas e parâmetros dinâmicos, consulte nosso guia de Roteamento Avançado.

Usando Parâmetros de Busca da URL

No Svelte 5, o parâmetro url fornecido à sua função load é um objeto URL, então você pode usar url.searchParams.get('key') diretamente. Isso facilita a leitura de query strings para filtragem, pesquisa ou paginação.

Acesse query strings como /search?q=svelte:

// src/routes/search/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ url, fetch }) => {
	const query = url.searchParams.get('q') || ''

	const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`)
	const results = await response.json()

	return {
		query,
		results
	}
}

Quando o `load` É Executado?

É importante entender isso:

Cenário	Onde o `load` É Executado
Primeira visita à página (digitando URL, refresh)	Servidor
Clicando em um link para esta página	Navegador
Usando avançar/voltar do navegador	Navegador (geralmente em cache)

A mesma função load funciona em ambos os ambientes. Isso é poderoso, mas significa que você não pode usar recursos exclusivos do servidor aqui (como acesso direto ao banco de dados ou chaves de API privadas). Para esses casos, use +page.server.js.

Retornando Diferentes Tipos de Dados

A função load pode retornar qualquer dado serializável. Essa flexibilidade permite que você:

Retorne dados de múltiplas fontes
Inclua metadados para a página
Passe valores derivados/calculados
Forneça configuração de componentes

export const load: PageLoad = async ({ fetch }) => {
	const [postsRes, categoriesRes] = await Promise.all([
		fetch('/api/posts'),
		fetch('/api/categories')
	])

	return {
		posts: await postsRes.json(),
		categories: await categoriesRes.json(),
		metadata: {
			title: 'Blog',
			description: 'Read our latest posts'
		}
	}
}

Carregamento Paralelo de Dados

Quando sua página precisa de dados de várias fontes independentes, buscá-los em paralelo significa que todas as requisições começam ao mesmo tempo. Isso reduz drasticamente o tempo total de carregamento — a página carrega no tempo da requisição mais lenta, não na soma de todas as requisições.

Aqui está a distinção fundamental a entender: await dentro de código async é sequencial. Cada await pausa a execução até que aquela promise seja resolvida antes de continuar. Promise.all, por outro lado, dispara todas as promises simultaneamente e aguarda todas elas juntas.

// PREFERRED: All three requests fire simultaneously
export const load: PageLoad = async ({ fetch }) => {
	const [posts, categories, featured] = await Promise.all([
		fetch('/api/posts').then((r) => r.json()),
		fetch('/api/categories').then((r) => r.json()),
		fetch('/api/featured').then((r) => r.json())
	])

	return { posts, categories, featured }
}

Evite buscas sequenciais quando as requisições são independentes. Esse padrão adiciona latência proporcional ao número de requisições:

// AVOID: Sequential — each request waits for the previous to complete
// If each call takes 100ms, this takes ~300ms total.
// The Promise.all above takes ~100ms regardless of request count.
export const load: PageLoad = async ({ fetch }) => {
	const posts = await fetch('/api/posts').then((r) => r.json())
	const categories = await fetch('/api/categories').then((r) => r.json())
	const featured = await fetch('/api/featured').then((r) => r.json())

	return { posts, categories, featured }
}

O padrão sequencial só é apropriado quando uma requisição genuinamente depende do resultado de outra — por exemplo, buscar o ID de um usuário e então buscar os posts desse usuário. Se as requisições são independentes, sempre use Promise.all.

Use Promise.all para fontes de dados independentes. Sua página carregará tão rápido quanto a requisição mais lenta, não a soma de todas as requisições.

Tratamento de Erros em Funções Load

O tratamento adequado de erros é essencial para uma boa experiência do usuário. Use o helper error para acionar o mecanismo de tratamento de erros do SvelteKit:

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

export const load: PageLoad = async ({ params, fetch }) => {
	const response = await fetch(`/api/posts/${params.slug}`)

	if (response.status === 404) {
		error(404, {
			message: 'Post not found',
			hint: 'The post may have been removed or renamed.'
		})
	}

	if (!response.ok) {
		error(response.status, 'Failed to load post')
	}

	return {
		post: await response.json()
	}
}

Para um mergulho profundo em páginas de erro customizadas e tratamento avançado de erros, consulte +error.svelte.

Erros Comuns

#1: Usando APIs do Navegador

// AVOID:  localStorage doesn't exist on the server!
export const load: PageLoad = async () => {
	const theme = localStorage.getItem('theme')
	return { theme }
}

// PREFERRED: Check for browser environment
import { browser } from '$app/environment'

export const load: PageLoad = async () => {
	const theme = browser ? localStorage.getItem('theme') : 'light'
	return { theme }
}

#2: Não Tratando Erros

// AVOID:  What if the API is down?
export const load: PageLoad = async ({ fetch }) => {
	const response = await fetch('/api/data')
	return await response.json()
}

// PREFERRED: Handle error cases
import { error } from '@sveltejs/kit'

export const load: PageLoad = async ({ fetch }) => {
	const response = await fetch('/api/data')

	if (!response.ok) {
		error(response.status, 'Failed to load data')
	}

	return await response.json()
}

#3: Retornando Dados Não Serializáveis

// AVOID:  Functions can't travel from server to browser
export const load: PageLoad = async () => {
	return {
		formatDate: (d: Date) => d.toLocaleDateString()
	}
}

// PREFERRED: Return data, handle formatting in component
export const load: PageLoad = async () => {
	return {
		date: new Date().toISOString()
	}
}

Conclusão

O arquivo +page.js incorpora a filosofia de JavaScript universal do SvelteKit — código que roda em qualquer lugar, fornecendo comportamento consistente seja durante a renderização no servidor ou na navegação do lado do cliente. Ao executar tanto no servidor quanto no cliente, ele possibilita experiências de usuário otimizadas: carregamentos iniciais rápidos com renderização no servidor, navegações subsequentes instantâneas com busca no lado do cliente, e lógica de carregamento de dados compartilhada sem duplicação. Essa universalidade é a arma secreta do SvelteKit para construir aplicações que se sentem rápidas em qualquer lugar, permanecendo fundamentalmente baseadas na web.

Dominar o +page.js significa entender as restrições do código universal (sem window, sem document, sem APIs privadas), aproveitar o fetch aprimorado para deduplicação automática de requisições e credenciais, e usar o acesso a dados do pai para construir sobre o contexto fornecido pelo layout. Combinado com pré-carregamento estratégico e rastreamento adequado de dependências com depends(), as funções de carregamento universal criam aplicações onde os dados fluem naturalmente de URLs para componentes, a navegação se sente instantânea, e a fronteira entre servidor e cliente se torna um detalhe de implementação em vez de um fardo arquitetural.

Principais Conclusões

+page.js executa universalmente - roda durante o SSR no servidor e durante a navegação do lado do cliente no navegador, fornecendo carregamento de dados consistente em qualquer lugar
Deve usar código agnóstico de plataforma - sem window, document ou APIs específicas do navegador, pois executa tanto no servidor quanto no cliente
O fetch aprimorado fornece superpoderes - encaminhamento automático de cookies, deduplicação de requisições entre funções de carregamento e resolução de URLs relativas durante o SSR
Acesse dados do layout pai via await parent() - construa sobre contexto de autenticação, categorias ou outros dados fornecidos pelo layout sem prop drilling
O pré-carregamento torna a navegação instantânea - use data-sveltekit-preload-data em links para buscar dados da página ao passar o mouse antes da navegação
Os dados retornados devem ser serializáveis - apenas dados compatíveis com JSON (sem funções, classes, Dates, RegExp) para transferência do servidor para o cliente
Use depends() para invalidação lógica - crie chaves de invalidação personalizadas como depends('app:posts') para disparar recarregamentos via invalidate()
Promise.all permite busca paralela - combine múltiplas operações assíncronas para carregar dados relacionados simultaneamente sem cascatas sequenciais

Veja Também

Documentação Oficial do SvelteKit - +page.js
Universal vs Carregamento no Servidor - Escolhendo a abordagem correta
fetch em Funções de Carregamento - Capacidades aprimoradas do fetch
Pré-carregamento - Estratégias de pré-carregamento de links
Invalidação - Revalidação manual de dados
Função parent() - Acessando dados do layout