Carregamento Universal de Dados em Layouts

Assim como as páginas possuem +page.js para carregamento de dados, os layouts possuem +layout.js. Esse arquivo carrega dados necessários pelo próprio layout e que fluem para todas as páginas e layouts filhos em sua subárvore. Ele é executado tanto no servidor quanto no navegador, tornando-o um carregamento de dados universal.

O ponto-chave sobre as funções de carregamento de layout é quando elas são executadas versus quando não são. A função de carregamento de um layout é executada na primeira vez que você entra em sua subárvore. Ela não é reexecutada automaticamente ao navegar entre páginas que compartilham esse layout — o SvelteKit armazena o resultado em cache e o reutiliza. Isso torna o carregamento de layout eficiente para dados que são estáveis durante a sessão de um usuário dentro de uma seção: estrutura de navegação, configuração do site, categorias disponíveis. Para dados que mudam com frequência ou dependem da URL atual, você precisará expressar essa dependência explicitamente (abordado na seção de invalidação abaixo).

O carregamento de dados no layout estabelece o "contexto ambiente" para uma seção do seu app: estrutura de navegação, flags de funcionalidades, preferências do usuário, configuração do site. Pense cuidadosamente sobre o que pertence aqui versus nas funções de carregamento de páginas individuais. O critério para dados de layout deve ser: "quase todas as páginas desta seção precisam disso?"

Quando Usar `+layout.js`

Use +layout.js quando precisar carregar:

Dados de navegação — Categorias, itens de menu, estrutura do site
Configuração pública — Flags de funcionalidades, configurações do site
Conteúdo compartilhado — Categorias de blog, categorias de produtos
Dados necessários por múltiplas páginas — Evite carregar os mesmos dados em cada página

O requisito principal: os dados devem ser públicos (sem segredos) e serializáveis.

Carregamento Básico de Dados no Layout

// src/routes/blog/+layout.ts
import type { LayoutLoad } from './$types'

export const load: LayoutLoad = async ({ fetch }) => {
	const response = await fetch('/api/categories')
	const categories = await response.json()

	return {
		categories
	}
}

Esses dados estão agora disponíveis em:

O componente de layout (+layout.svelte)
Todas as páginas filhas
Todos os layouts filhos

Os Dados Fluem para Downstream

Superpoder: Os dados retornados pela função load de um layout fluem para baixo como uma cascata. Eles ficam automaticamente disponíveis para todos os descendentes.

src/routes/
├── +layout.ts         → Returns { siteConfig }
├── +layout.svelte     → Has access to data.siteConfig
├── blog/
│   ├── +layout.ts     → Returns { categories }
│   ├── +layout.svelte → Has access to data.siteConfig AND data.categories
│   └── [slug]/
│       └── +page.svelte → Has access to ALL parent data

Acessando Dados do Pai

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

	let { data }: PageProps = $props()

	// data includes:
	// - siteConfig (from root +layout.ts)
	// - categories (from blog/+layout.ts)
	// - post (from [slug]/+page.ts)
</script>

<aside>
	<h3>Categories</h3>
	{#each data.categories as category}
		<a href="/blog?category={category.slug}">{category.name}</a>
	{/each}
</aside>

<article>
	<h1>{data.post.title}</h1>
	<p>{data.post.content}</p>
</article>

Acessando Dados do Pai em Funções de Carregamento

As funções de carregamento filhas podem acessar os dados do pai usando a função parent():

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

export const load: PageLoad = async ({ params, parent }) => {
	// Wait for parent layout data
	const parentData = await parent()

	// Now you can use parentData.categories, etc.
	const category = parentData.categories.find((c) => c.id === params.categoryId)

	return {
		post: await fetchPost(params.slug),
		categoryName: category?.name
	}
}

Chame parent() apenas quando realmente precisar de dados de um layout pai. Chamá-lo desnecessariamente força essa função de carregamento a aguardar o pai terminar antes de iniciar — mesmo que os dados produzidos não tenham nada a ver com o resultado do pai. Se você pode buscar seus dados de forma independente e só precisa de uma pequena parte do contexto pai (como uma string de locale ou uma lista de categorias), considere se essa parte poderia estar em params, url ou na própria rota. Chamadas desnecessárias a parent() são uma das causas mais comuns de waterfalls evitáveis no carregamento de dados em apps SvelteKit.

Carregamento de Dados Baseado em URL

As funções de carregamento de layout têm acesso à URL, permitindo carregar dados diferentes com base em parâmetros de consulta:

// src/routes/blog/+layout.ts
import type { LayoutLoad } from './$types'

export const load: LayoutLoad = async ({ fetch, url }) => {
	const activeCategory = url.searchParams.get('category')

	const [categories, featuredPosts] = await Promise.all([
		fetch('/api/categories').then((r) => r.json()),
		fetch(`/api/posts/featured?category=${activeCategory || ''}`).then((r) => r.json())
	])

	return {
		categories,
		featuredPosts,
		activeCategory
	}
}

Quando os Dados do Layout São Recarregados

Este é um dos comportamentos mais importantes para entender e uma fonte comum de confusão.

Por padrão, a função de carregamento de um layout é executada uma vez quando você entra na subárvore do layout. Ela não é reexecutada ao navegar entre páginas irmãs dentro dessa subárvore. Navegar de /blog/post-a para /blog/post-b não reexecutará /blog/+layout.ts. Isso é intencional — recarregar categorias de navegação ou configuração do site a cada clique de página seria desperdício.

Mas às vezes você precisa que o layout seja reexecutado. Se a função de carregamento do seu layout busca uma lista filtrada com base em um parâmetro de consulta da URL, ela precisa ser reexecutada quando esse parâmetro muda.

A maneira de expressar isso no SvelteKit é lendo o objeto url ou chamando depends(). O SvelteKit rastreia o que uma função de carregamento acessou durante sua última execução. Se a URL mudar de uma forma que produziria entradas diferentes, a função de carregamento é reexecutada:

// src/routes/blog/+layout.ts
import type { LayoutLoad } from './$types'

export const load: LayoutLoad = async ({ fetch, url, depends }) => {
	// Declaring a custom dependency allows manual invalidation via invalidate('app:category')
	depends('app:category')

	// Reading url.searchParams causes SvelteKit to re-run this function
	// whenever the ?category= query string changes
	const category = url.searchParams.get('category')

	return {
		posts: await fetch(`/api/posts?category=${category}`).then((r) => r.json())
	}
}

Como essa função de carregamento lê url.searchParams, o SvelteKit sabe que ela depende da string de consulta da URL. Mudar de /blog?category=tech para /blog?category=design reexecutará a função de carregamento do layout automaticamente. Sem acessar o objeto url, a função de carregamento só seria executada uma vez.

Para acionar uma reexecução de qualquer parte do seu app, chame invalidate('app:category') ou use invalidateAll() para uma nova busca completa de todas as funções de carregamento na página atual.

Carregamento Paralelo de Dados

Ao carregar múltiplos recursos, use Promise.all para maior eficiência:

// src/routes/+layout.ts
import type { LayoutLoad } from './$types'

export const load: LayoutLoad = async ({ fetch }) => {
	// Load all resources in parallel
	const [navigation, footerLinks, announcements] = await Promise.all([
		fetch('/api/navigation').then((r) => r.json()),
		fetch('/api/footer-links').then((r) => r.json()),
		fetch('/api/announcements').then((r) => r.json())
	])

	return {
		navigation,
		footerLinks,
		announcements
	}
}

Combinando com `+layout.server.js`

Você pode ter tanto +layout.js quanto +layout.server.js para o mesmo layout. Quando isso acontece:

+layout.server.js é executado primeiro (no servidor)
Seus dados ficam disponíveis para +layout.js como a propriedade data
+layout.js pode transformar ou adicionar a esses dados

// src/routes/+layout.server.ts
export const load = async ({ locals }) => {
	return {
		user: locals.user // Server-only (from cookies/session)
	}
}

// src/routes/+layout.ts
import type { LayoutLoad } from './$types'

export const load: LayoutLoad = async ({ data, fetch }) => {
	// `data` contains { user } from +layout.server.ts

	const navigation = await fetch('/api/navigation').then((r) => r.json())

	return {
		...data, // Include server data
		navigation // Add universal data
	}
}

Padrões Comuns

Configuração para Todo o Site

// src/routes/+layout.ts
import type { LayoutLoad } from './$types'

export const load: LayoutLoad = async ({ fetch }) => {
	const config = await fetch('/api/config').then((r) => r.json())

	return {
		siteName: config.siteName,
		features: {
			darkMode: config.enableDarkMode,
			newsletter: config.enableNewsletter
		}
	}
}

Navegação com Estado Ativo

// src/routes/+layout.ts
import type { LayoutLoad } from './$types'

export const load: LayoutLoad = async ({ url }) => {
	const navigation = [
		{ href: '/', label: 'Home' },
		{ href: '/about', label: 'About' },
		{ href: '/blog', label: 'Blog' },
		{ href: '/contact', label: 'Contact' }
	].map((item) => ({
		...item,
		active: url.pathname === item.href || url.pathname.startsWith(item.href + '/')
	}))

	return { navigation }
}

Conclusão

O arquivo +layout.js representa um padrão poderoso para estabelecer contexto global da aplicação e dados compartilhados sem a sobrecarga de requisições redundantes ou prop drilling.

Ao carregar dados uma vez no nível do layout e disponibilizá-los para todas as rotas descendentes, você cria uma arquitetura mais eficiente e sustentável, onde a estrutura de navegação, as preferências do usuário e a configuração compartilhada fluem naturalmente pela hierarquia de componentes.

A natureza universal desse arquivo (executado tanto no servidor quanto no cliente) garante comportamento consistente, independentemente de os usuários chegarem via URL direta ou navegação pelo lado do cliente.

Dominar o +layout.js requer compreender seu relacionamento com +layout.server.js para estratégias híbridas de dados, a função parent() para acessar dados de ancestrais e os padrões de invalidação para controlar quando os layouts são reexecutados.

Ao organizar cuidadosamente quais dados pertencem aos layouts versus às páginas, você constrói aplicações que são tanto performáticas quanto fáceis de raciocinar — com limites claros entre o contexto compartilhado e as preocupações específicas de cada página.

Principais Conclusões

+layout.js fornece carregamento universal de dados para layouts que é executado tanto no servidor (SSR) quanto no cliente (navegação), disponibilizando dados para o componente de layout e todas as rotas filhas
Os dados fluem para downstream para todos os descendentes — páginas e layouts filhos recebem automaticamente os dados do layout pai por meio da prop data, sem passagem explícita de props
A função parent() permite composição de dados — funções de carregamento filhas podem aguardar parent() para acessar dados de ancestrais e complementá-los com propriedades adicionais
Os dados do layout são armazenados em cache durante a navegação entre rotas irmãs — os dados só são recarregados ao sair e retornar ao escopo do layout ou quando explicitamente invalidados
Os padrões de invalidação controlam as reexecuções — use depends('custom:identifier') com invalidate() ou inclua dependências baseadas em URL para acionar a atualização dos dados do layout
Combine com +layout.server.js para estratégias híbridas — use .server.js para dados sensíveis (autenticação, banco de dados) e .js para dados públicos (navegação, categorias)
O carregamento paralelo otimiza o desempenho — use Promise.all() para buscar múltiplas fontes de dados de forma concorrente em vez de sequencial
Deve retornar dados serializáveis — todos os dados retornados por +layout.js devem ser serializáveis em JSON, pois fluem do servidor para o cliente durante o SSR

Veja Também

Documentação Oficial do SvelteKit - +layout.js
Funções de Carregamento do SvelteKit - Guia completo sobre funções de carregamento
invalidate() e invalidateAll() - Invalidação manual de dados