O Problema dos Dados Compartilhados

No artigo anterior, estabelecemos como uma única página busca seus dados por meio de uma função load em +page.ts. Esse modelo funciona bem quando uma rota existe de forma isolada. Na prática, porém, as rotas raramente existem de forma isolada. Um blog tem dezenas de posts que vivem todos sob a mesma seção /blog. Um painel tem dezenas de visualizações que compartilham uma navegação lateral. Uma aplicação SaaS tem dezenas de páginas que todas precisam saber quem é o usuário atual.

Buscar esses dados compartilhados dentro de cada função de carregamento de página individualmente seria dispendioso e propenso a erros. Dispendioso porque a mesma consulta é executada de forma redundante em cada navegação; propenso a erros porque qualquer alteração na estrutura de dados compartilhados precisa ser replicada em cada arquivo que os busca.

O SvelteKit resolve isso com funções de carregamento de layout. Assim como +layout.svelte fornece uma UI compartilhada que envolve cada página dentro de um segmento de rota, +layout.ts (ou +layout.server.ts) fornece dados compartilhados que estão disponíveis para cada página dentro desse mesmo segmento. Os dois sistemas se espelham por design, e uma vez que você entende um, o outro segue naturalmente.

Este artigo explica como o carregamento de dados no nível de página e no nível de layout funcionam juntos, como os dados fluem pela hierarquia de layouts, como o SvelteKit mescla dados de múltiplas fontes e como acessar dados em ambas as direções: de cima para baixo, do pai para o filho, e de baixo para cima, da página para o layout pai.

Uma Página, Muitas Fontes

Considere uma aplicação de blog. A estrutura de rotas é assim:

src/routes/
├── +layout.svelte          ← root layout, wraps everything
├── +layout.server.ts       ← root layout load (user session, nav data)
├── blog/
│   ├── +layout.svelte      ← blog section layout, sidebar with post list
│   ├── +layout.server.ts   ← blog layout load (list of all posts)
│   └── [slug]/
│       ├── +page.svelte    ← individual post page
│       └── +page.server.ts ← post page load (the specific post)

A página de post individual precisa de um artigo específico — esses são dados de nível de página, exclusivos dessa rota. A seção do blog precisa de uma lista de todos os posts para a barra lateral — isso é compartilhado por todos os posts sob /blog, então pertence ao carregamento do layout do blog. O layout raiz precisa da sessão do usuário atual para o cabeçalho de navegação — isso é compartilhado por toda a aplicação, então pertence ao carregamento do layout raiz.

Sem funções de carregamento de layout, você teria duas opções ruins: buscar a lista de posts na função de carregamento de cada post individual (redundante e inconsistente), ou usar algum mecanismo externo como uma store inicializada na inicialização da aplicação (frágil e desconectada do pipeline de dados do SvelteKit). As funções de carregamento de layout oferecem uma terceira opção que não é nenhuma dessas: declarar os dados uma vez no nível correto da hierarquia e deixar o SvelteKit distribuí-los.

Princípios

O sistema de layout do SvelteKit e seu sistema de carregamento de dados são hierarquias paralelas que se mapeiam na mesma estrutura de diretório de rotas. Para cada arquivo +layout.svelte pode haver um +layout.ts ou +layout.server.ts ao lado, e eles se comportam exatamente como seus equivalentes +page — exportam uma função load, recebem os mesmos argumentos de evento e retornam um objeto simples.

A diferença fundamental é o escopo. Os dados de uma função de carregamento de página estão disponíveis apenas para aquela página específica. Os dados de uma função de carregamento de layout estão disponíveis para o próprio layout e para cada página e layout aninhado dentro desse segmento de rota. Os dados fluem para baixo pela árvore automaticamente.

Quando o SvelteKit renderiza uma página, ele chama todas as funções de carregamento aplicáveis (do layout raiz descendo por quaisquer layouts aninhados até a própria página) e mescla todos os seus valores de retorno. Cada +layout.svelte e +page.svelte então recebe os dados relevantes para seu próprio nível e tudo acima dele.

Implementação

Passo 1: Adicionar uma Função de Carregamento a um Layout

A convenção de pareamento de arquivos é idêntica à das páginas. Onde +layout.svelte fornece o shell de UI, +layout.ts ou +layout.server.ts fornece os dados que esse shell precisa. O SvelteKit os conecta automaticamente pelo nome do arquivo.

Aqui está o layout da seção do blog com sua função de carregamento:

// src/routes/blog/+layout.server.ts

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

export const load: LayoutServerLoad = async ({ fetch }) => {
	const res = await fetch('/api/posts')
	if (!res.ok) error(res.status, 'Failed to load posts')

	const posts: Array<{ title: string; slug: string; publishedAt: string }> = await res.json()

	return { posts }
}

Observe o tipo usado aqui: LayoutServerLoad, não PageServerLoad. O SvelteKit gera ambos a partir de ./$types, e são tipos distintos porque as funções de carregamento de layout e as funções de carregamento de página têm entradas disponíveis ligeiramente diferentes e implicações diferentes para como seus dados são compartilhados. Sempre use o tipo específico de layout para arquivos de layout.

<!-- src/routes/blog/+layout.svelte -->

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

	let { data, children }: LayoutProps = $props()
</script>

<div class="blog-shell">
	<aside class="sidebar">
		<h2>All Posts</h2>
		<nav>
			{#each data.posts as post (post.slug)}
				<a href="/blog/{post.slug}">{post.title}</a>
			{/each}
		</nav>
	</aside>

	<main>
		{@render children()}
	</main>
</div>

O snippet children é como o Svelte 5 renderiza conteúdo aninhado dentro de um layout. Quando um usuário visita /blog/my-post, o SvelteKit renderiza o +layout.svelte do layout do blog e coloca o +page.svelte do post onde {@render children()} aparece. O layout envolve a página; a barra lateral está sempre lá, e o conteúdo do post muda por rota.

Dois aspectos no componente de layout merecem atenção. Primeiro, LayoutProps é importado de ./$types; este é o equivalente de layout de PageProps, e ele tipifica tanto data quanto children adequadamente. Segundo, data.posts é corretamente tipado como o array retornado pela função de carregamento do layout, com autocompletar completo para post.title, post.slug e post.publishedAt.

Passo 2: Entender Como os Dados Chegam à Página

Agora considere a página de post individual. Ela tem sua própria função de carregamento que busca o post específico, mas a prop data que ela recebe em +page.svelte contém mais do que apenas aquele post:

// src/routes/blog/[slug]/+page.server.ts

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

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

	if (!res.ok) error(res.status, 'Post not found')

	const post = await res.json()
	return { post }
}

<!-- src/routes/blog/[slug]/+page.svelte -->

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

	let { data }: PageProps = $props()

	// data.post comes from this page's own load function
	// data.posts comes from the parent blog layout's load function
	let currentIndex = $derived(data.posts.findIndex((p) => p.slug === page.params.slug))
	let nextPost = $derived(data.posts[currentIndex + 1])
</script>

<article>
	<h1>{data.post.title}</h1>
	<div class="content">{@html data.post.content}</div>
</article>

{#if nextPost}
	<nav class="pagination">
		<a href="/blog/{nextPost.slug}">Next: {nextPost.title}</a>
	</nav>
{/if}

Esta é a parte importante: o componente de página acessa data.posts. Esses dados vieram da função de carregamento do layout pai, não da sua própria. O SvelteKit mescla silenciosamente os dados de cada função de carregamento na cadeia de layout ativa antes que qualquer componente os veja:

O SvelteKit mescla tudo antes que o componente o receba. Da perspectiva do componente de página, data é um único objeto plano contendo todos os dados de todas as funções de carregamento acima na árvore.

Essa mesclagem é por que data.posts funciona em +page.svelte mesmo que a própria função de carregamento da página nunca tenha tocado em posts. A página do post pode implementar a navegação "próximo post" puramente a partir dos dados que seu layout pai já buscou, portanto nenhuma requisição de rede adicional é necessária.

Passo 3: Lidar com Colisões de Chaves em Dados Mesclados

Quando múltiplas funções de carregamento na mesma árvore de layout retornam dados, o SvelteKit mescla todos os seus valores de retorno em um único objeto para cada componente. Isso é conveniente, mas significa que a nomenclatura das chaves importa. Se duas funções de carregamento retornam uma chave com o mesmo nome, a que está mais próxima da página vence.

A regra oficial é: a última na árvore vence.

// src/routes/+layout.server.ts
export const load = async ({ fetch }) => {
	const res = await fetch('/api/user/me')
	const user = await res.json()

	return {
		user,
		title: 'My Blog' // ← this key
	}
}

// src/routes/blog/[slug]/+page.server.ts
export const load: PageServerLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/posts/${params.slug}`)
	const post = await res.json()

	return {
		post,
		title: params.slug // ← same key, page wins
	}
}

Nesse cenário, data.title dentro de +page.svelte será o valor do slug, não 'My Blog'. O title do layout raiz é sobreposto. Isso é útil quando uma página precisa substituir algo definido por um pai, mas pode ser surpreendente se acontecer acidentalmente.

A solução é uma nomenclatura deliberada de chaves: use nomes específicos e inequívocos em vez de genéricos como data, title ou items. Em uma aplicação real, você pode usar namespaces: layoutTitle, pageTitle ou, melhor ainda, estruturá-los como objetos aninhados: { meta: { title: 'My Blog' } } vs { post: { title: params.slug } }.

Passo 4: Acessar Dados de Página a partir de um Layout Pai

Tudo acima descreve dados fluindo para baixo, de layouts pai para páginas filhas. Ocasionalmente você precisa que os dados fluam na direção oposta. O caso mais comum é um layout raiz que deseja definir uma tag <title> dinâmica com base nos dados retornados pela página que estiver ativa no momento.

O SvelteKit suporta isso por meio de page.data, exportado de $app/state:

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

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

	let { children } = $props()
</script>

<svelte:head>
	<!-- page.data contains the merged data of the currently active page -->
	<title>{page.data.title ?? 'My Blog'}</title>
</svelte:head>

<header>
	<a href="/">My Blog</a>
</header>

{@render children()}

// src/routes/blog/[slug]/+page.server.ts

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 // ← this reaches the root layout via page.data
	}
}

page.data é reativo. Quando o usuário navega para uma página diferente, page.data atualiza para refletir os dados mesclados da nova página, e o <title> atualiza automaticamente. É assim que o SvelteKit habilita títulos de documento dinâmicos sem prop-drilling ou stores globais.

O tipo de page.data é definido por App.PageData nas declarações de tipo da sua aplicação. O SvelteKit não infere automaticamente esse tipo de união porque não pode saber em tempo de compilação qual página estará ativa em tempo de execução; o layout raiz deve lidar com a incerteza com um padrão sensato, como mostrado com o operador de coalescência nula ?? 'My Blog' acima.

Erros Comuns e Anti-Padrões

Duplicar Dados Compartilhados em Funções de Carregamento de Página

Quando desenvolvedores se deparam pela primeira vez com a necessidade de dados compartilhados, uma reação comum é buscá-los em cada função de carregamento de página que os necessita. Isso parece seguro — cada página é autossuficiente —, mas anula completamente o propósito do sistema de carregamento de layout.

// AVOID: Fetching shared data in every page

// src/routes/blog/[slug]/+page.server.ts
export const load: PageServerLoad = async ({ params, fetch }) => {
	const [postRes, postsRes] = await Promise.all([
		fetch(`/api/posts/${params.slug}`),
		fetch('/api/posts') // ← fetched here
	])
	return {
		post: await postRes.json(),
		posts: await postsRes.json()
	}
}

// src/routes/blog/+page.server.ts (the blog index page)
export const load: PageServerLoad = async ({ fetch }) => {
	const res = await fetch('/api/posts') // ← fetched again
	return { posts: await res.json() }
}

// PREFERRED: Fetch shared data once in the layout

// src/routes/blog/+layout.server.ts
export const load: LayoutServerLoad = async ({ fetch }) => {
	const res = await fetch('/api/posts')
	return { posts: await res.json() }
}

// src/routes/blog/[slug]/+page.server.ts
export const load: PageServerLoad = async ({ params, fetch }) => {
	const res = await fetch(`/api/posts/${params.slug}`)
	if (res.status === 404) error(404, 'Post not found')
	return { post: await res.json() } // ← posts is already available via the layout
}

As funções de carregamento de layout não são chamadas novamente em cada navegação entre rotas filhas se suas dependências não tiverem mudado. Quando um usuário navega de um post do blog para outro, o SvelteKit reconhece que nada do que a função de carregamento do layout do blog depende mudou, portanto reutiliza o resultado em cache. Cada carregamento de página individual que duplicou esses dados seria executado novamente desnecessariamente.

Usar o Tipo Errado para Funções de Carregamento de Layout vs Página

Os tipos gerados para funções de carregamento de layout e de página são distintos, e usar o tipo errado causará erros de TypeScript ou, pior, comportamento incorreto silencioso.

// AVOID: Using PageServerLoad in a layout file

// src/routes/blog/+layout.server.ts
import type { PageServerLoad } from './$types' // ← wrong import

export const load: PageServerLoad = async ({ fetch }) => {
	const res = await fetch('/api/posts')
	return { posts: await res.json() }
}

// PREFERRED: Using LayoutServerLoad in a layout file

// src/routes/blog/+layout.server.ts
import type { LayoutServerLoad } from './$types' // ← correct

export const load: LayoutServerLoad = async ({ fetch }) => {
	const res = await fetch('/api/posts')
	return { posts: await res.json() }
}

Da mesma forma, no próprio componente de layout, use LayoutProps em vez de PageProps. A distinção importa porque LayoutProps inclui o tipo do snippet children que PageProps não tem; componentes de página não renderizam rotas aninhadas.

Esquecer que children É Obrigatório em Componentes de Layout

Todo componente de layout que envolve rotas filhas deve renderizar seu snippet children. Se você omitir {@render children()}, as páginas filhas simplesmente não aparecerão. Isso é óbvio quando o arquivo de layout é novo, mas é fácil de quebrar acidentalmente ao refatorar o template de um layout.

<!-- AVOID: Layout that swallows its children -->

<script lang="ts">
	import type { LayoutProps } from './$types'
	let { data }: LayoutProps = $props()
	// children is destructured but never used
</script>

<aside>
	{#each data.posts as post}
		<a href="/blog/{post.slug}">{post.title}</a>
	{/each}
</aside>
<!-- The page content will never appear -->

<!-- PREFERRED: Layout that renders its children -->

<script lang="ts">
	import type { LayoutProps } from './$types'
	let { data, children }: LayoutProps = $props()
</script>

<aside>
	{#each data.posts as post}
		<a href="/blog/{post.slug}">{post.title}</a>
	{/each}
</aside>

<main>
	{@render children()}
</main>

Sempre desestruture children de $props() e sempre chame {@render children()} em algum lugar no template. Não há aviso do SvelteKit quando um layout descarta silenciosamente seus filhos, portanto esse erro pode ser confuso para depurar.

Considerações de Desempenho e Escalabilidade

As funções de carregamento de layout são uma das ferramentas de desempenho mais significativas do SvelteKit, mas apenas quando usadas com compreensão de como o rastreamento de dependências funciona.

O SvelteKit rastreia o que cada função de carregamento acessa durante a execução. Uma função de carregamento de layout que busca todos os posts e os retorna não depende de params, portanto sempre retorna os mesmos dados independentemente de qual post específico o usuário está visualizando. Quando o usuário navega de um post para outro, o SvelteKit vê que a função de carregamento do layout do blog não tem dependências relevantes que mudaram e pula completamente sua chamada. Os dados da chamada anterior são reutilizados.

Isso significa que a lista de posts na barra lateral é atualizada apenas quando a lista realmente muda — não a cada navegação. Para um blog com centenas de posts, isso representa potencialmente dezenas de consultas ao banco de dados economizadas por sessão de usuário.

A implicação para como você estrutura suas funções de carregamento de layout é que você deve mantê-las com escopo adequado. Uma função de carregamento de layout raiz que busca dados necessários por toda rota na aplicação é aceitável. Uma função de carregamento de layout raiz que busca dados necessários apenas por uma seção específica da aplicação desperdiça esses dados em cada rota que não os necessita e os torna disponíveis em page.data mesmo onde são irrelevantes.

Quando você tem layouts aninhados, pense em cada nível como tendo um escopo natural. Layout raiz: identidade do usuário e navegação global. Layout de seção: navegação específica da seção e dados de referência compartilhados. Página: o conteúdo específico para essa visualização exata. Respeitar esses escopos mantém as funções de carregamento enxutas e faz o sistema de rastreamento de dependências trabalhar a seu favor.

Quando NÃO Usar Este Padrão

Funções de load de layout são excelentes para dados que são genuinamente compartilhados entre todas as rotas dentro do escopo de um layout. Elas são a ferramenta errada para dados que são compartilhados por um mecanismo diferente da hierarquia de rotas.

Se você precisa que dados sejam compartilhados entre rotas irmãs que não compartilham um ancestral de layout comum, por exemplo entre /dashboard/stats e /settings/profile, uma função de load de layout teria que residir na raiz, tornando esses dados disponíveis em todo lugar, mesmo onde são irrelevantes. Uma solução melhor para dados compartilhados transversais é o objeto locals do SvelteKit, populado em um hook de servidor e disponível em qualquer função de load de servidor que precisar dele.

Funções de load de layout também não devem ser usadas para contornar a ausência de uma arquitetura de dados adequada. Se sua aplicação tem um grande número de chamadas de API que todas "parecem compartilhadas", a solução geralmente é pensar com mais cuidado sobre quais dados são genuinamente de escopo de layout versus quais dados devem ser buscados sob demanda ou gerenciados como estado do lado do cliente.

Conclusão

As funções layout load do SvelteKit estendem o mesmo modelo mental que as funções page load — exporte uma função load, retorne um objeto simples, receba-o como data e aplique-o em cada nível da hierarquia de rotas.

Os dados dos layouts pai fluem automaticamente para baixo para todas as páginas filhas. Colisões de chaves entre níveis são resolvidas em favor da página. E quando os dados de nível de página precisam fluir para cima, como para um layout raiz que define um título dinâmico, page.data de $app/state fornece um caminho limpo e reativo.

A combinação de carregamento de página e layout cria um pipeline de dados completo onde cada componente em cada nível da árvore tem exatamente os dados que precisa, buscados no escopo correto, sem redundância e sem conexões manuais entre componentes.

Principais Conclusões

As funções de load de layout seguem exatamente a mesma convenção que as funções de load de página: um export load de +layout.ts ou +layout.server.ts, tipado com LayoutLoad ou LayoutServerLoad de ./$types. Os dados que elas retornam estão disponíveis para o componente de layout e para todas as páginas e layouts aninhados dentro daquele segmento de rota.

O SvelteKit mescla todos os valores de retorno das funções de load em um único objeto data em cada nível da árvore. Se duas funções de load retornarem a mesma chave, aquela mais próxima da página prevalece. Nomes de chaves deliberados evitam sombreamento acidental.

As funções de load de layout não são chamadas novamente quando a dependência que elas rastreiam não mudou. Isso as torna um lugar eficiente para dados compartilhados entre muitas rotas; a consulta é executada uma vez e reutilizada nas navegações dentro do escopo daquele layout.

page.data de $app/state fornece acesso reativo aos dados mesclados da página atualmente ativa, possibilitando padrões como títulos de documento dinâmicos em um layout raiz sem prop-drilling ou stores.

O Que Vem a Seguir

Até agora, todas as funções de load desta série foram executadas em ambos os ambientes: no servidor durante o SSR e no navegador durante a navegação do lado do cliente. Esse é o comportamento padrão de +page.ts e +layout.ts. Mas algumas funções de load precisam ser executadas exclusivamente no servidor: consultas a banco de dados, chaves de API privadas, cookies de sessão.

O SvelteKit lida com isso por meio de uma convenção de arquivo separada, e entender quando usar cada uma é uma das decisões mais importantes na arquitetura de aplicações SvelteKit. O próximo artigo, The page Object from $app/state, cobre esse objeto reativo por completo — todas as suas propriedades, como ele é atualizado durante a navegação do lado do cliente e os padrões que dependem dele em toda a sua aplicação.

Leitura Adicional

$app/state documentation (referência completa para o objeto page e page.data)
Official SvelteKit Load Documentation (a referência oficial)