Carregamento de Dados de Layout Exclusivo do Servidor

O arquivo +layout.server.js (ou +layout.server.ts) fornece carregamento de dados exclusivo do servidor para layouts. Esta é a escolha mais comum para o layout raiz, pois é onde você normalmente lida com autenticação — verificando se um usuário está logado e disponibilizando essa informação em toda a sua aplicação.

Entender por que esse arquivo é tão central requer compreender o pipeline de requisições do SvelteKit. Toda requisição HTTP passa pelo hooks.server.ts antes de chegar a qualquer rota. Os hooks podem ler cookies de sessão, validar tokens e armazenar o resultado em event.locals — um objeto com escopo de requisição que acompanha a requisição desde os hooks até as funções de carregamento. O +layout.server.js raiz é então o lugar ideal para ler de locals e transmitir o objeto de usuário para todas as páginas da sua aplicação.

Esse pipeline de três estágios é o que torna a autenticação simples no SvelteKit:

hooks.server.ts   →  validates the session cookie  →  sets event.locals.user
+layout.server.ts →  reads event.locals.user        →  returns { user } to all pages
+layout.svelte    →  receives data.user             →  renders login/logout UI

O +layout.server.js raiz é executado em cada requisição, tornando-o o lugar perfeito para verificações de autenticação, carregamento de feature flags e estabelecimento do contexto do usuário. Configure esse arquivo corretamente e a autenticação fluirá naturalmente por toda a sua aplicação sem nenhum boilerplate por página.

O Padrão de Autenticação

O caso de uso mais importante para +layout.server.js é a autenticação. Ao carregar os dados do usuário no layout raiz, cada página da sua aplicação tem acesso ao usuário atual.

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

export const load: LayoutServerLoad = async ({ cookies, locals }) => {
	// `locals` is typically populated by hooks.server.ts
	// It contains data like the authenticated user

	return {
		user: locals.user ?? null
	}
}

Agora cada página e layout da sua aplicação pode acessar data.user:

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

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

<header>
	{#if data.user}
		<span>Welcome, {data.user.name}</span>
		<a href="/dashboard">Dashboard</a>
		<form method="POST" action="/logout">
			<button>Logout</button>
		</form>
	{:else}
		<a href="/login">Login</a>
		<a href="/signup">Sign Up</a>
	{/if}
</header>

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

Trabalhando com Hooks

Vamos percorrer o pipeline completo para que as peças se conectem. O objeto locals é populado no seu arquivo hooks.server.ts antes que qualquer função de carregamento seja executada:

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit'
import { db } from '$lib/server/database'

export const handle: Handle = async ({ event, resolve }) => {
	// Read session cookie
	const sessionId = event.cookies.get('session')

	if (sessionId) {
		// Validate session and get user
		const session = await db.sessions.findUnique({
			where: { id: sessionId },
			include: { user: true }
		})

		if (session && session.expiresAt > new Date()) {
			event.locals.user = {
				id: session.user.id,
				name: session.user.name,
				email: session.user.email,
				role: session.user.role
			}
		}
	}

	return resolve(event)
}

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

export const load: LayoutServerLoad = async ({ locals }) => {
	// User is already validated in hooks
	return {
		user: locals.user ?? null
	}
}

Parâmetros Exclusivos do Servidor

Assim como +page.server.js, a função de carregamento do layout do servidor tem acesso a parâmetros exclusivos do servidor:

export const load: LayoutServerLoad = async ({
	cookies, // Read and write cookies
	locals, // Data from hooks.server.ts
	request, // The original Request object
	url, // The URL object
	fetch, // Server-side fetch
	platform, // Platform-specific context
	setHeaders // Set response headers
}) => {
	// Your server-only logic
}

Lendo Cookies Diretamente

Às vezes você precisa ler cookies diretamente no layout:

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

export const load: LayoutServerLoad = async ({ cookies }) => {
	const theme = cookies.get('theme') ?? 'light'
	const locale = cookies.get('locale') ?? 'en'

	return {
		preferences: {
			theme,
			locale
		}
	}
}

Carregando Dados para Toda a Aplicação

O layout raiz é perfeito para carregar dados necessários em todos os lugares:

// src/routes/+layout.server.ts
import type { LayoutServerLoad } from './$types'
import { db } from '$lib/server/database'
import { ANALYTICS_KEY } from '$env/static/private'

export const load: LayoutServerLoad = async ({ locals, cookies }) => {
	// Get user from hooks
	const user = locals.user

	// Load user-specific data if logged in
	let notifications = []
	let unreadCount = 0

	if (user) {
		const result = await db.notifications.findMany({
			where: { userId: user.id },
			orderBy: { createdAt: 'desc' },
			take: 5
		})
		notifications = result
		unreadCount = await db.notifications.count({
			where: { userId: user.id, read: false }
		})
	}

	// Load site-wide settings
	const settings = await db.settings.findFirst()

	return {
		user,
		notifications,
		unreadCount,
		settings: {
			siteName: settings?.siteName ?? 'My App',
			maintenanceMode: settings?.maintenanceMode ?? false
		}
	}
}

Padrão de Rotas Protegidas

Use os dados do layout do servidor para proteger seções inteiras da sua aplicação:

// src/routes/(protected)/+layout.server.ts
import { redirect } from '@sveltejs/kit'
import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ locals, url }) => {
	if (!locals.user) {
		// Redirect to login with return URL
		const returnTo = encodeURIComponent(url.pathname)
		redirect(303, `/login?returnTo=${returnTo}`)
	}

	return {
		user: locals.user
	}
}

Agora qualquer página dentro de (protected)/ requer autenticação:

src/routes/
├── (protected)/
│   ├── +layout.server.ts    → Requires auth
│   ├── dashboard/
│   │   └── +page.svelte     → Protected
│   ├── settings/
│   │   └── +page.svelte     → Protected
│   └── profile/
│       └── +page.svelte     → Protected
├── login/
│   └── +page.svelte         → Public
└── +layout.server.ts        → Root (loads user if present)

Controle de Acesso Baseado em Funções

Estenda o padrão para permissões baseadas em funções:

// src/routes/(admin)/+layout.server.ts
import { error, redirect } from '@sveltejs/kit'
import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ locals }) => {
	if (!locals.user) {
		redirect(303, '/login')
	}

	if (locals.user.role !== 'admin') {
		error(403, {
			message: 'Access Denied',
			hint: 'You need admin privileges to access this area.'
		})
	}

	return {
		user: locals.user
	}
}

Herança de Dados

Os dados dos layouts pai estão disponíveis para layouts filhos e páginas:

// src/routes/+layout.server.ts (root)
export const load: LayoutServerLoad = async ({ locals }) => {
	return {
		user: locals.user,
		appVersion: '2.1.0'
	}
}

// src/routes/dashboard/+layout.server.ts
export const load: LayoutServerLoad = async ({ locals, parent }) => {
	// Get parent data
	const parentData = await parent()

	// Load dashboard-specific data
	const stats = await getDashboardStats(locals.user.id)

	return {
		// Parent data is automatically included
		stats
	}
}

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

	let { data }: PageProps = $props()

	// Has access to:
	// - data.user (from root layout)
	// - data.appVersion (from root layout)
	// - data.stats (from dashboard layout)
</script>

Boas Práticas de Segurança

Não Exponha Dados Sensíveis

// AVOID: Exposing all user data
export const load: LayoutServerLoad = async ({ locals }) => {
	return {
		user: locals.user // Might include passwordHash!
	}
}

// PREFERRED: Only expose what's needed
export const load: LayoutServerLoad = async ({ locals }) => {
	if (!locals.user) return { user: null }

	return {
		user: {
			id: locals.user.id,
			name: locals.user.name,
			email: locals.user.email,
			avatar: locals.user.avatar,
			role: locals.user.role
		}
	}
}

Valide em Cada Requisição

export const load: LayoutServerLoad = async ({ locals, cookies }) => {
	// Even if locals.user exists, verify the session is still valid
	const sessionId = cookies.get('session')

	if (!sessionId) {
		return { user: null }
	}

	// Verify session hasn't been revoked
	const session = await db.sessions.findUnique({
		where: { id: sessionId }
	})

	if (!session || session.revokedAt) {
		cookies.delete('session', { path: '/' })
		return { user: null }
	}

	return { user: locals.user }
}

Conclusão

O arquivo +layout.server.js representa a contraparte do lado do servidor para o carregamento universal de dados de layout, fornecendo uma base segura para autenticação, autorização e acesso a dados sensíveis. Por ser executado exclusivamente no servidor, ele permite acesso direto ao banco de dados, chaves de API privadas e gerenciamento de sessão sem expor detalhes de implementação ou credenciais de segurança ao navegador. Mais comumente usado em layouts raiz para estabelecer o contexto de autenticação do usuário, ele transforma a segurança de uma preocupação por página em infraestrutura para toda a aplicação.

Dominar o +layout.server.js significa entender seu relacionamento com +layout.js para estratégias híbridas de dados, reconhecer quando os dados devem ser exclusivos do servidor versus universais e implementar a sanitização adequada dos dados antes de enviá-los aos clientes.

Combinado com grupos de layout para seções de rotas protegidas e o objeto locals para dados com escopo de requisição, ele fornece a base para construir aplicações seguras e prontas para produção, onde a autenticação flui naturalmente desde a raiz por toda a hierarquia de rotas.

Principais Conclusões

+layout.server.js fornece dados de layout exclusivos do servidor que nunca são executados no navegador, ideal para autenticação, consultas a banco de dados e operações sensíveis que utilizam credenciais privadas
Mais comumente usado no layout raiz (src/routes/+layout.server.js) para estabelecer o contexto de autenticação do usuário em toda a aplicação, que flui automaticamente para todas as páginas
Acesse recursos exclusivos do servidor, incluindo cookies para gerenciamento de sessão, locals para dados com escopo de requisição e platform para detalhes do ambiente de implantação
Os dados fluem para todos os descendentes - layouts filhos e páginas recebem os dados do layout do servidor por meio da prop data sem necessidade de passagem explícita
Combine com grupos de layout para seções protegidas - use grupos (authenticated) com +layout.server.js para impor requisitos de autenticação em subárvores inteiras de rotas
Sempre sanitize os dados antes de expô-los ao cliente - filtre campos sensíveis como hashes de senha, IDs internos ou flags de administrador antes de retornar os dados
Pode coexistir com +layout.js para estratégias híbridas - o servidor carrega dados de autenticação/sensíveis, enquanto o universal carrega dados públicos como navegação ou categorias
Os dados retornados devem ser serializáveis - sem funções, classes ou referências circulares, apenas estruturas de dados compatíveis com JSON

Veja Também

Documentação Oficial do SvelteKit - +layout.server.js
Cookies - Gerenciamento de sessão e autenticação
Contexto da Função de Carregamento - Entendendo locals, cookies, platform
Grupos de Layout - Organizando rotas protegidas
Padrões de Autenticação - Construindo fluxos de autenticação seguros