A Oportunidade Antes da Página Renderizar

Um usuário envia um formulário de login. O servidor cria uma sessão, emite um cookie e o redireciona para o seu painel. Nessa próxima requisição, antes que uma única linha do componente do painel seja executada, sua aplicação tem uma oportunidade: ler o cookie, validar a sessão, resolver a identidade do usuário. A página inteira depende de acertar isso na fração de segundo entre a chegada da requisição e o envio da resposta.

Essa oportunidade vive dentro de uma função de server load. Usá-la corretamente significa entender três coisas que ficam próximas, mas se comportam de forma diferente: ler cookies com o objeto cookies, definir cookies com cookies.set() em vez de um header de resposta, e definir outros headers de resposta com setHeaders de uma forma que leve em conta como SSR e navegação do cliente interagem de maneira diferente.

A maioria dos tutoriais sobre esse assunto reduz cookies a uma única linha: cookies.get('session'). Isso te coloca em movimento, mas deixa de fora o raciocínio que determina quando ler um cookie é a abordagem certa, por que definir um cookie requer uma API completamente diferente, como as regras de encaminhamento de cookies interagem com implantações em múltiplos domínios, e o que setHeaders realmente faz durante uma requisição renderizada no servidor versus uma navegação do cliente.

Este artigo aborda tudo isso. Ao final, você terá um modelo mental preciso de como o objeto cookies e a função setHeaders se comportam em funções de server load, por que funcionam da maneira que funcionam, e como aplicá-los a um padrão prático de carregamento de sessão que serve como base para autenticação na maioria das aplicações SvelteKit.

Uma convenção continua do restante desta série: sem ORMs, sem abstrações de cliente de banco de dados. Todo acesso a dados nos exemplos usa chamadas simples de fetch para endpoints de API. Isso mantém os exemplos focados no comportamento do SvelteKit sendo explicado, e não em qualquer camada de dados específica.

Quatro Preocupações, Uma Requisição

Considere uma aplicação SvelteKit autenticada típica. Quando um usuário faz login, o servidor cria um registro de sessão e envia o identificador da sessão de volta ao navegador como um cookie HTTP. Cada requisição subsequente desse navegador carrega o cookie. O servidor o lê, busca a sessão e sabe quem é o usuário.

No SvelteKit, as funções de server load são onde essa busca acontece. O +layout.server.ts na raiz da aplicação lê o cookie de sessão, o resolve para uma identidade de usuário e retorna essa identidade para cada página da aplicação. Cada +page.server.ts que precisa de autenticação pode então ler o usuário resolvido a partir dos dados do layout pai, em vez de ler o cookie eles mesmos.

O padrão parece simples, mas envolve quatro preocupações distintas que cada uma precisa de tratamento cuidadoso:

Ler cookies corretamente significa entender o objeto cookies no evento de load, quais cookies são acessíveis de quais rotas, e o que acontece quando um cookie está ausente.

Encaminhar credenciais de funções de server load para endpoints de API internos envolve o event.fetch do SvelteKit, que automaticamente carrega cookies para requisições de mesma origem. As regras que governam quais cookies são encaminhados e para quais origens importam para aplicações que abrangem múltiplos domínios ou subdomínios.

Definir cookies em resposta a um server load requer cookies.set(), não um header de resposta. Há uma razão específica para essa restrição, e entendê-la previne uma classe sutil de bugs.

Definir headers de resposta com setHeaders controla como o navegador e qualquer cache intermediário tratam a resposta. Tem um efeito significativo durante o SSR e um efeito diferente, mais limitado, durante a navegação do lado do cliente. Conhecer a diferença é o que torna setHeaders útil em vez de confuso.

O Objeto cookies vs setHeaders

As funções de server load recebem um objeto de evento de load. A propriedade cookies nesse objeto não é um parser bruto de header HTTP. É uma API estruturada que o SvelteKit constrói a partir do header de requisição Cookie de entrada e mantém ao longo da vida da requisição.

Quando você chama cookies.get('session'), o SvelteKit analisa a string de cookie, encontra o cookie pelo nome e retorna seu valor. Quando você chama cookies.set('session', value, options), o SvelteKit enfileira um header de resposta Set-Cookie e também atualiza seu estado interno de cookies para que leituras subsequentes dentro da mesma requisição reflitam o novo valor. Quando você chama cookies.delete('session'), ele enfileira um header que expira o cookie imediatamente e o remove do estado interno.

Esse modelo com estado é intencional. Uma única requisição pode envolver ler um cookie de sessão, determinar que ele expirou, excluir o cookie antigo e definir um novo atualizado. O objeto cookies mantém consistência em todas essas operações sem que você precise rastrear o estado interno manualmente.

A função setHeaders é uma ferramenta separada com um propósito mais restrito. Ela define headers de resposta diferentes de Set-Cookie para a requisição atual. Ela afeta a resposta HTTP que o navegador ou cache recebe, não os dados que fluem para o componente de página.

Implementação

Passo 1: Lendo Cookies em uma Função de Server Load

O objeto cookies está disponível no evento de load em +page.server.ts e +layout.server.ts. Ele não está disponível em funções de load universais (+page.ts, +layout.ts) porque essas podem ser executadas no navegador, onde o acesso bruto a cookies é governado pela API document.cookie do JavaScript em vez de headers HTTP.

O uso mais importante de cookies.get() em uma aplicação típica é ler o identificador de sessão no server load do layout raiz. Este é o lugar natural para isso porque o layout raiz envolve cada página. Qualquer identidade de usuário resolvida aqui flui para cada página na hierarquia de rotas por meio da mesclagem de dados do SvelteKit.

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

import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	const sessionId = cookies.get('session_id')

	// If no session cookie exists, the user is not logged in.
	// Return a null user. Pages that require authentication will
	// redirect from their own load functions when they see null here.
	if (!sessionId) {
		return { user: null }
	}

	// Validate the session against the API. event.fetch automatically
	// forwards the original request's cookies to same-origin calls,
	// but here we are being explicit by passing the session ID in a
	// header, which works reliably regardless of cookie forwarding rules.
	const response = await fetch('/api/session/validate', {
		headers: {
			'X-Session-Id': sessionId
		}
	})

	if (!response.ok) {
		// Session invalid or expired. Return null so pages can react.
		return { user: null }
	}

	const user = await response.json()
	return { user }
}

// src/routes/api/session/validate/+server.ts

import type { RequestHandler } from './$types'
import { json, error } from '@sveltejs/kit'

interface UserRecord {
	id: string
	email: string
	displayName: string
	role: 'admin' | 'editor' | 'viewer'
	avatarUrl: string | null
}

// In a real application this handler queries whatever session store
// your application uses: Redis, a database table, JWT verification.
// The load function does not care. It calls fetch and reads the result.
export const GET: RequestHandler = async ({ request }) => {
	const sessionId = request.headers.get('X-Session-Id')

	if (!sessionId) {
		error(400, 'Session ID header missing')
	}

	// Simulated session lookup. Replace this with your actual session store.
	if (sessionId !== 'valid-session-token-example') {
		error(401, 'Session not found or expired')
	}

	const user: UserRecord = {
		id: 'user-1',
		email: 'alex@example.com',
		displayName: 'Alex Kim',
		role: 'editor',
		avatarUrl: '/avatars/user-1.jpg'
	}

	return json(user)
}

O valor user retornado pelo load do layout fica disponível para cada página por meio da prop data. Páginas que requerem autenticação inspecionam data.user e redirecionam quando ele é nulo.

// src/routes/dashboard/+page.server.ts

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

export const load: PageServerLoad = async ({ parent }) => {
	// Calling parent() gives this load function access to the layout
	// data without re-reading the cookie or re-validating the session.
	const { user } = await parent()

	if (!user) {
		// Redirect to the login page. The 303 status is correct for
		// a redirect after a GET request in SvelteKit's redirect helper.
		redirect(303, '/login')
	}

	// Fetch dashboard-specific data now that we know who the user is.
	// The user ID is known from the session, not from the URL.
	// This prevents users from accessing other users' dashboards
	// by changing a route parameter.
	const response = await fetch(`/api/users/${user.id}/dashboard`)

	if (!response.ok) {
		return { stats: null, recentActivity: [] }
	}

	const dashboardData = await response.json()
	return { stats: dashboardData.stats, recentActivity: dashboardData.recentActivity }
}

Chamar parent() é como um page server load acessa os dados resolvidos do layout server load. Esta é a chave para o padrão de leitura única: o layout raiz lê o cookie uma vez por requisição, resolve a sessão uma vez, e cada função de load filha herda esse resultado.

Passo 2: Regras de Encaminhamento de Cookies

Quando uma função de server load chama event.fetch com uma URL de mesma origem, o SvelteKit encaminha os cookies da requisição de entrada original para essa chamada de fetch. Este é o Superpoder Dois do artigo anterior. Mas mesma origem significa exatamente o que diz: o mesmo esquema, host e porta.

Considere uma aplicação implantada em app.example.com que tem um servidor de API em api.example.com. Estas são origens diferentes, mesmo que compartilhem um domínio raiz. Cookies definidos com Domain=example.com são enviados pelo navegador para ambos, mas o event.fetch do SvelteKit só encaminha cookies automaticamente para requisições que correspondem exatamente à origem da requisição de entrada.

// src/routes/reports/+page.server.ts

import type { PageServerLoad } from './$types'
import { INTERNAL_API_SECRET } from '$env/static/private'

export const load: PageServerLoad = async ({ cookies, fetch }) => {
	// Same-origin fetch to /api/reports. Cookies forwarded automatically.
	// No special handling needed.
	const internalResponse = await fetch('/api/reports/summary')

	// Cross-origin fetch to api.example.com. No automatic cookie forwarding.
	// The session cookie value is read explicitly and forwarded as a header.
	const sessionId = cookies.get('session_id')

	const externalResponse = await fetch('https://api.example.com/reports/detailed', {
		headers: {
			// Using a custom header is more explicit and intentional than
			// forwarding the cookie string directly in a Cookie header.
			// The API on api.example.com is configured to read this header.
			'X-Session-Id': sessionId ?? '',
			// Internal service-to-service authentication, separate from
			// the user session. Never expose this to the browser.
			Authorization: `Bearer ${INTERNAL_API_SECRET}`
		}
	})

	if (!internalResponse.ok || !externalResponse.ok) {
		return { summary: null, detailed: null }
	}

	const [summary, detailed] = await Promise.all([internalResponse.json(), externalResponse.json()])

	return { summary, detailed }
}

A regra a aplicar consistentemente: para rotas internas de mesma origem, confie no encaminhamento automático. Para requisições de origem cruzada, encaminhe credenciais explicitamente e deliberadamente. Isso força o fluxo de dados a ser visível no código em vez de implícito.

A função setHeaders aceita um objeto de headers de resposta. Ela é usada para coisas como Cache-Control, Vary, X-Frame-Options, e qualquer header personalizado que sua aplicação precise enviar. Mas ela explicitamente não aceita Set-Cookie.

Tentar definir um cookie por meio de setHeaders lançará um erro em tempo de execução:

// Wrong: SvelteKit throws an error if you attempt this.
export const load: PageServerLoad = async ({ setHeaders }) => {
	setHeaders({
		// This throws: "Use the 'cookies.set()' API instead"
		'set-cookie': 'session=abc; Path=/; HttpOnly'
	})
	return {}
}

A razão para essa restrição não é arbitrária. Definir cookies por meio de strings de header brutas significa contornar o rastreamento de estado interno de cookies do SvelteKit. Se o load do layout define um cookie e o load de uma página o lê, o SvelteKit precisa saber qual é o valor atual do cookie em cada ponto do ciclo de vida da requisição. Isso só é possível se todas as mutações de cookies passarem pelo objeto cookies.

Há também uma consideração de segurança. Atributos de cookies como HttpOnly, Secure, SameSite e Path existem para proteger cookies de serem lidos por JavaScript, enviados por conexões inseguras ou acessados de caminhos inesperados. A API cookies.set() aplica uma configuração padrão que faz escolhas seguras a menos que você opte explicitamente por sair delas. A abordagem de string bruta requer que você se lembre de cada atributo toda vez.

// src/routes/+layout.server.ts
// Demonstrating a session refresh pattern.

import type { LayoutServerLoad } from './$types'

export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	const sessionId = cookies.get('session_id')

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

	const response = await fetch('/api/session/validate', {
		headers: { 'X-Session-Id': sessionId }
	})

	if (!response.ok) {
		// Session is invalid. Delete the stale cookie so the browser
		// stops sending it on future requests.
		cookies.delete('session_id', { path: '/' })
		return { user: null }
	}

	const { user, refreshedSessionId } = await response.json()

	// If the API issued a new session ID (rolling session pattern),
	// update the cookie with the refreshed value.
	if (refreshedSessionId && refreshedSessionId !== sessionId) {
		cookies.set('session_id', refreshedSessionId, {
			// HttpOnly prevents JavaScript from reading the cookie value.
			// This is critical: session tokens should never be accessible
			// to client-side code because that exposes them to XSS attacks.
			httpOnly: true,

			// Secure ensures the cookie is only sent over HTTPS.
			// In development this can be false, but always true in production.
			secure: true,

			// Strict prevents the cookie from being sent on cross-site requests.
			// This protects against CSRF for most common attack vectors.
			sameSite: 'strict',

			// The path controls which routes the cookie is sent with.
			// '/' means all routes on this domain receive the cookie.
			path: '/',

			// maxAge sets the cookie lifetime in seconds.
			// 7 days expressed in seconds.
			maxAge: 60 * 60 * 24 * 7
		})
	}

	return { user }
}

A API cookies.set() exige que você especifique path explicitamente. Isso é intencional. Sem um path, o comportamento do cookie é definido em relação à URL que definiu o cookie, o que produz comportamento surpreendente quando um cookie é definido profundamente na hierarquia de rotas, mas se espera que seja legível em todos os lugares. Sempre passe path: '/' a menos que você tenha uma razão específica para restringir o cookie a uma subárvore.

Passo 4: Definindo Headers de Resposta com setHeaders

A função setHeaders é para todo header de resposta que não seja Set-Cookie. Seu uso mais comum em funções de load é o controle de cache, que comunica ao navegador e a qualquer CDN ou proxy reverso na frente de sua aplicação quanto tempo uma resposta pode ser reutilizada.

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

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

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

	if (!response.ok) {
		error(404, 'Article not found')
	}

	const article = await response.json()

	// This page's content changes rarely. Tell the browser and any CDN
	// that the response can be cached for one hour.
	// 'public' means intermediate caches (CDNs, proxies) can also store it.
	// 'max-age' is the lifetime in seconds: 3600 = one hour.
	// 's-maxage' overrides max-age for shared caches like CDNs.
	setHeaders({
		'cache-control': 'public, max-age=3600, s-maxage=86400'
	})

	return { article }
}

// src/routes/dashboard/+page.server.ts

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

export const load: PageServerLoad = async ({ parent, setHeaders, fetch }) => {
	const { user } = await parent()

	if (!user) {
		redirect(303, '/login')
	}

	const response = await fetch(`/api/users/${user.id}/dashboard`)
	const dashboardData = await response.json()

	// Dashboard content is user-specific and must not be cached by
	// shared caches. 'private' restricts caching to the browser only.
	// 'no-store' prevents even the browser from caching it.
	// Use this for any page containing sensitive user data.
	setHeaders({
		'cache-control': 'private, no-store'
	})

	return dashboardData
}

A escolha entre public e private não é sobre controle de acesso no sentido do SvelteKit. É uma instrução de cache. Uma resposta public informa aos intermediários que eles têm permissão para armazená-la em cache e servi-la a qualquer usuário. Uma resposta private informa a eles para mantê-la apenas para o único navegador que a solicitou. Se uma página contiver qualquer dado específico do usuário, ela deve ser private.

Passo 5: O que setHeaders Faz Durante SSR vs Navegação do Cliente

Esta é a parte do setHeaders que surpreende os desenvolvedores. Seu efeito é assimétrico dependendo de quando a função de load é executada.

Durante uma requisição SSR, setHeaders define headers na resposta HTTP real enviada ao navegador. Um header Cache-Control: public, max-age=3600 significa que o navegador e qualquer CDN entre o usuário e o servidor armazenarão em cache o HTML renderizado. Na próxima vez que a mesma URL for solicitada, ela pode ser servida do cache sem que o servidor execute nenhuma função de load.

Durante uma navegação do lado do cliente (quando o usuário clica em um link em uma aplicação SvelteKit em execução), não há resposta HTTP. O navegador já está executando JavaScript e o SvelteKit gerencia a navegação internamente. A função de load é executada no navegador, busca dados e atualiza a página. setHeaders é chamado nesse contexto, mas não há resposta HTTP para anexar os headers. O SvelteKit ignora a chamada silenciosamente. Os headers de controle de cache que você definiu não têm efeito nas navegações do cliente.

A implicação prática é que os headers de controle de cache definidos em funções de load se aplicam à renderização de página completa na primeira visita. Eles não afetam como o SvelteKit gerencia navegações subsequentes do lado do cliente para a mesma rota. Essas navegações usam o próprio modelo de navegação e invalidação do SvelteKit, que é independente do cache HTTP.

Isso também significa que você não pode usar setHeaders em uma função de load universal (+page.ts) com a expectativa de que ele controlará o cache do navegador em todas as navegações. Um load universal é executado tanto no servidor quanto no navegador, mas setHeaders só faz algo no lado do servidor. Se você precisar de comportamento de cache para a carga inicial da página, setHeaders é a ferramenta certa. Se você precisar controlar quando o SvelteKit reexecuta uma função de load após a renderização inicial, isso é tratado por invalidate e depends, que é um mecanismo diferente abordado em um artigo posterior desta série.

Exemplo Prático: Carregando uma Sessão de Usuário

A seguir, há um exemplo completo e integrado que reúne todos os conceitos: um layout raiz que lê um cookie de sessão, o valida, opcionalmente o atualiza, define headers de controle de cache apropriados e disponibiliza o usuário resolvido para cada página.

Os tipos de sessão

// src/lib/types/session.ts

export interface SessionUser {
	id: string
	email: string
	displayName: string
	role: 'admin' | 'editor' | 'viewer'
	avatarUrl: string | null
}

export interface SessionValidationResult {
	user: SessionUser
	// The API may issue a new session ID when it extends a session.
	// If null, the existing session ID is still valid and unchanged.
	refreshedSessionId: string | null
}

O server load do layout raiz

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

import type { LayoutServerLoad } from './$types'
import type { SessionValidationResult } from '$lib/types/session'

const SESSION_COOKIE = 'sid'

export const load: LayoutServerLoad = async ({ cookies, url, setHeaders, fetch }) => {
	const sessionId = cookies.get(SESSION_COOKIE)

	// No session cookie present. User is not authenticated.
	// Return null without making any network requests.
	if (!sessionId) {
		return { user: null }
	}

	const response = await fetch('/api/session/validate', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({ sessionId })
	})

	// Invalid or expired session. Remove the stale cookie to prevent
	// it from being sent on every subsequent request unnecessarily.
	if (!response.ok) {
		cookies.delete(SESSION_COOKIE, { path: '/' })
		return { user: null }
	}

	const result: SessionValidationResult = await response.json()

	// Rolling session: if the server issued a new session ID, replace
	// the old one. This extends the session lifetime on active use.
	if (result.refreshedSessionId) {
		cookies.set(SESSION_COOKIE, result.refreshedSessionId, {
			httpOnly: true,
			secure: true,
			sameSite: 'strict',
			path: '/',
			maxAge: 60 * 60 * 24 * 7
		})
	}

	// The layout response itself is not publicly cacheable because it
	// varies by user session. The SSR output for this request contains
	// user-specific data embedded in the page.
	setHeaders({
		'cache-control': 'private, no-cache'
	})

	return { user: result.user }
}

A rota de API de validação de sessão

// src/routes/api/session/validate/+server.ts

import type { RequestHandler } from './$types'
import { json, error } from '@sveltejs/kit'
import type { SessionValidationResult, SessionUser } from '$lib/types/session'

interface ValidateRequestBody {
	sessionId: string
}

// A real session store. Here simulated with a static map.
// In production, this would query Redis, a database table, or verify a JWT.
const SESSION_STORE = new Map<string, { user: SessionUser; createdAt: number }>([
	[
		'valid-session-token-example',
		{
			user: {
				id: 'user-1',
				email: 'alex@example.com',
				displayName: 'Alex Kim',
				role: 'editor',
				avatarUrl: '/avatars/user-1.jpg'
			},
			createdAt: Date.now()
		}
	]
])

const SESSION_LIFETIME_MS = 7 * 24 * 60 * 60 * 1000 // 7 days
const SESSION_REFRESH_THRESHOLD_MS = 24 * 60 * 60 * 1000 // refresh if less than 1 day left

export const POST: RequestHandler = async ({ request }) => {
	let body: ValidateRequestBody

	try {
		body = await request.json()
	} catch {
		error(400, 'Invalid request body')
	}

	const record = SESSION_STORE.get(body.sessionId)

	if (!record) {
		error(401, 'Session not found')
	}

	const age = Date.now() - record.createdAt

	if (age > SESSION_LIFETIME_MS) {
		SESSION_STORE.delete(body.sessionId)
		error(401, 'Session expired')
	}

	// Issue a new session ID if the session is approaching expiry.
	let refreshedSessionId: string | null = null

	if (age > SESSION_LIFETIME_MS - SESSION_REFRESH_THRESHOLD_MS) {
		refreshedSessionId = crypto.randomUUID()
		SESSION_STORE.set(refreshedSessionId, {
			user: record.user,
			createdAt: Date.now()
		})
		SESSION_STORE.delete(body.sessionId)
	}

	const result: SessionValidationResult = {
		user: record.user,
		refreshedSessionId
	}

	return json(result)
}

O page load protegido

// src/routes/account/+page.server.ts

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

export const load: PageServerLoad = async ({ parent, setHeaders, fetch }) => {
	// parent() reads the already-resolved layout data.
	// This does not re-validate the session. The cookie was read once
	// by the layout and the result is reused here.
	const { user } = await parent()

	if (!user) {
		redirect(303, '/login?returnTo=/account')
	}

	const response = await fetch(`/api/users/${user.id}/account`)

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

	const account = await response.json()

	// Account data is personal. Prevent all caching.
	setHeaders({
		'cache-control': 'private, no-store'
	})

	return { account }
}

O componente do layout raiz

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

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

	let { data, children }: { data: LayoutData; children: import('svelte').Snippet } = $props()

	// data.user is null when not logged in, or a SessionUser when authenticated.
	// $derived makes the boolean reactive so the nav updates if the user
	// state changes within the same page session (e.g., after login).
	const isAuthenticated = $derived(data.user !== null)
</script>

<header>
	<nav>
		<a href="/">Home</a>
		<a href="/articles">Articles</a>

		{#if isAuthenticated}
			<a href="/account">{data.user?.displayName}</a>
			<form method="POST" action="/api/auth/logout">
				<button type="submit">Log out</button>
			</form>
		{:else}
			<a href="/login">Log in</a>
		{/if}
	</nav>
</header>

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

O componente usa $derived para calcular isAuthenticated a partir do valor de data.user. Isso mantém a reatividade limpa: se os dados do usuário mudarem na mesma sessão da aplicação (por exemplo, após uma ação de login ou logout do lado do cliente acionar invalidate), o valor derivado é atualizado e a navegação reflete o novo estado sem nenhuma atualização imperativa explícita.

Erros Comuns e Anti-Padrões

Lendo cookies em uma função load universal

// Wrong: cookies is not available in +page.ts
// This file can run in the browser where the cookies object does not exist.
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ cookies }) => {
	// TypeScript will catch this: 'cookies' does not exist on PageLoadEvent.
	// But even if it did, the browser has no equivalent API here.
	const sessionId = cookies.get('session_id')
	return {}
}

// Correct: use +page.server.ts for any cookie access.
// The .server suffix guarantees the file never runs in the browser.
import type { PageServerLoad } from './$types'

export const load: PageServerLoad = async ({ cookies }) => {
	const sessionId = cookies.get('session_id')
	return {}
}

O TypeScript detectará esse erro em tempo de compilação porque o tipo do evento load em +page.ts não inclui uma propriedade cookies. Mas a razão a ser compreendida é que funções load universais são projetadas para rodar tanto no servidor quanto no cliente, e não existe uma API de cookies unificada que funcione de forma idêntica nos dois ambientes.

Tentando definir cookies com setHeaders

// Wrong: setHeaders does not accept Set-Cookie.
// SvelteKit throws a runtime error.
export const load: PageServerLoad = async ({ setHeaders }) => {
	setHeaders({
		'set-cookie': 'session_id=abc; HttpOnly; Secure; SameSite=Strict; Path=/'
	})
	return {}
}

// Correct: all cookie mutations go through cookies.set().
export const load: PageServerLoad = async ({ cookies }) => {
	cookies.set('session_id', 'abc', {
		httpOnly: true,
		secure: true,
		sameSite: 'strict',
		path: '/'
	})
	return {}
}

Além do erro em tempo de execução, a abordagem de string de cabeçalho bruta ignora o rastreamento interno de estado de cookies do SvelteKit. Qualquer chamada subsequente a cookies.get('session_id') dentro do mesmo ciclo de vida de requisição não enxergaria o novo valor porque o objeto cookies nunca foi notificado da mudança.

Definindo cabeçalhos conflitantes entre funções load de layout e de página

// src/routes/+layout.server.ts
export const load: LayoutServerLoad = async ({ setHeaders }) => {
	// Layout sets one cache directive.
	setHeaders({ 'cache-control': 'public, max-age=3600' })
	return {}
}

// src/routes/blog/[slug]/+page.server.ts
export const load: PageServerLoad = async ({ setHeaders }) => {
	// Page tries to set a different cache directive.
	// SvelteKit throws: "conflicting values for header 'cache-control'"
	setHeaders({ 'cache-control': 'private, no-store' })
	return {}
}

Quando funções load de layout e de página são executadas para a mesma requisição, o SvelteKit mescla suas chamadas de setHeaders. Se ambas tentarem definir o mesmo cabeçalho com valores diferentes, o SvelteKit lança um erro. A solução é definir cache-control apenas na função load mais específica para uma determinada rota: a server load da página. O layout não deve definir cabeçalhos de cache se páginas individuais precisam controlá-los de forma independente.

// Correct: only the page load sets cache-control.
// The layout does not touch it.
export const load: PageServerLoad = async ({ setHeaders, parent }) => {
	const { user } = await parent()
	setHeaders({
		'cache-control': user ? 'private, no-store' : 'public, max-age=300'
	})
	return {}
}

// Wrong: cookies.delete requires a path option.
// Without it, SvelteKit throws an error.
export const load: PageServerLoad = async ({ cookies }) => {
	cookies.delete('session_id')
	return { user: null }
}

// Correct: always provide path when calling cookies.delete().
// The path must match the path used when the cookie was set.
export const load: PageServerLoad = async ({ cookies }) => {
	cookies.delete('session_id', { path: '/' })
	return { user: null }
}

A opção path é exigida pela API do SvelteKit para evitar ambiguidade. Um cookie definido com Path=/ e um cookie definido com Path=/admin são cookies distintos mesmo que compartilhem o mesmo nome. Especificar o path explicitamente garante que você está deletando o correto.

Considerações de Performance e Escalabilidade

A server load do layout raiz é executada em cada requisição renderizada no servidor. Em uma aplicação autenticada, isso significa que a requisição de validação de sessão é feita em cada primeira visita a cada página. Manter esse caminho rápido é uma das otimizações de maior impacto disponíveis.

A rota de validação de sessão deve ser o mais leve possível. Uma busca por ID de sessão em um armazenamento em memória como Redis é uma operação de submilissegundo. Uma consulta ao banco de dados sem índice pode levar dezenas de milissegundos. A diferença é negligível por si só, mas se multiplica entre milhares de usuários simultâneos e torna-se o fator limitante do throughput do seu servidor.

Para aplicações onde a maioria das páginas é publicamente acessível, a verificação condicional no início do load do layout é importante:

export const load: LayoutServerLoad = async ({ cookies, fetch }) => {
	const sessionId = cookies.get('session_id')

	// Exit immediately if there is no session to validate.
	// Unauthenticated users pay zero API cost on the layout load.
	if (!sessionId) {
		return { user: null }
	}

	// Only users with a session cookie reach this fetch call.
	const response = await fetch('/api/session/validate', {
		method: 'POST',
		headers: { 'Content-Type': 'application/json' },
		body: JSON.stringify({ sessionId })
	})

	// ...rest of validation
}

Para páginas que são publicamente cacheáveis, setHeaders com as diretivas Cache-Control e Vary apropriadas permite que CDNs sirvam a página sem sequer atingir seu servidor de origem. Uma página de artigo de blog, uma página de documentação ou uma landing page de marketing pode ser cacheada na borda com um TTL razoável, e a função load de origem é executada uma vez por entrada de cache em vez de uma vez por visita de usuário.

// src/routes/docs/[...path]/+page.server.ts

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

export const load: PageServerLoad = async ({ params, setHeaders, fetch }) => {
	const path = params.path.join('/')
	const response = await fetch(`/api/docs?path=${encodeURIComponent(path)}`)

	if (!response.ok) {
		error(404, 'Documentation page not found')
	}

	const doc = await response.json()

	// Documentation pages are public and change infrequently.
	// CDNs can cache them for one hour (s-maxage).
	// Browsers revalidate after five minutes (max-age).
	// The Vary header tells caches that the response depends on
	// Accept-Encoding (for compression), which is standard practice.
	setHeaders({
		'cache-control': 'public, max-age=300, s-maxage=3600',
		vary: 'Accept-Encoding'
	})

	return { doc }
}

Quando NÃO Usar Este Padrão

O padrão de sessão no layout raiz descrito neste artigo é a abordagem correta para aplicações onde a maioria ou todas as páginas compartilham o conceito de usuário atual. Mas nem toda aplicação tem essa estrutura.

Sites puramente públicos sem autenticação alguma não têm utilidade para cookies de sessão em funções load. Se seu blog, site de documentação ou site de marketing não tem login, não há nada a ler e nenhum cookie a gerenciar.

Backends exclusivamente de API construídos apenas com rotas +server.ts do SvelteKit não usam funções load de página. O tratamento de cookies nesse caso é feito diretamente no manipulador de requisições, não através das APIs de função load.

Layouts muito restritos para leituras de sessão podem criar acoplamento desnecessário. Se você tem uma seção autenticada do seu site em /app e uma seção pública em / e as duas nunca compartilham um layout autenticado em comum, ler a sessão no layout raiz força uma leitura de cookie em cada página, incluindo páginas puramente públicas onde a autenticação é irrelevante. Nesse caso, um layout dedicado em src/routes/app/+layout.server.ts é mais apropriado do que colocar a lógica de sessão na raiz.

Páginas com polling de alta frequência ou em tempo real não devem depender de funções load para atualização de dados. Funções load são executadas na navegação, não em um temporizador. Se uma página precisa de dados que se atualizam a cada poucos segundos, o componente lida com a atualização usando um $effect que configura um intervalo de polling ou uma conexão WebSocket. A função load fornece o snapshot inicial e o componente o mantém atualizado.

Conclusão

Cookies e cabeçalhos de resposta em funções load de servidor não são complicados, mas têm regras que importam. Cookies pertencem exclusivamente a +page.server.ts e +layout.server.ts porque esses são os únicos contextos com execução garantida no servidor. O objeto cookies é stateful dentro de uma requisição, e todas as mutações de cookie devem passar por ele porque o SvelteKit rastreia esse estado internamente. Definir um cookie através de setHeaders ignora esse rastreamento e lança um erro por design.

A função setHeaders define cabeçalhos de resposta HTTP para a resposta SSR. Cabeçalhos Cache-Control definidos ali instruem navegadores e CDNs sobre como cachear a página renderizada. Durante navegações client-side esses cabeçalhos não têm efeito porque não há resposta HTTP à qual sejam anexados.

O padrão de sessão no layout raiz — ler o cookie de sessão uma vez e disponibilizar o usuário resolvido para todas as páginas através da mesclagem de dados do SvelteKit — é a fundação arquitetural correta para autenticação. Ele mantém as leituras de cookie em um único lugar, evita validação redundante e torna a identidade do usuário disponível sem prop drilling através de cada layout e página na hierarquia.

Principais Conclusões

Principais conclusões:

Cookies são acessíveis apenas em +page.server.ts e +layout.server.ts. Funções load universais não podem acessá-los.
Todas as mutações de cookie, incluindo definição e exclusão, devem passar pelo objeto cookies. Usar setHeaders para Set-Cookie lança um erro em tempo de execução.
cookies.set() exige uma opção path explícita. Sempre use path: '/' a menos que você tenha uma razão para restringir o cookie a uma subárvore.
O event.fetch do SvelteKit encaminha cookies automaticamente para requisições de mesma origem. Requisições cross-origin exigem encaminhamento explícito de credenciais.
setHeaders define cabeçalhos de resposta HTTP para a resposta SSR. Não tem efeito durante navegações client-side.
Use Cache-Control: private, no-store para páginas com dados específicos do usuário e public, max-age=N para páginas publicamente cacheáveis.
Definir o mesmo cabeçalho tanto no layout quanto nas server loads da página lança um erro de conflito. Atribua a responsabilidade de controle de cache à função load mais específica para cada rota.
Leia o cookie de sessão na server load do layout raiz exatamente uma vez por requisição e use parent() nas loads de página para acessar o usuário resolvido sem reler o cookie.

Próximos Passos

Cookies e cabeçalhos fornecem acesso aos metadados de requisição e resposta dentro de funções load de servidor. Mas há uma questão mais ampla: onde dados com escopo de requisição, como uma sessão validada, realmente residem antes de chegar a uma função load, e como são colocados lá inicialmente? A resposta é event.locals, populado por hooks.server.ts. O próximo artigo, locals e o Ciclo de Vida dos Hooks, aborda como o hook handle funciona, como tipar e popular locals, e como esses dados fluem para cada função load de servidor na sua aplicação.

Leitura Complementar

Documentação de Cookies do SvelteKit — referência oficial para a API de cookies no evento load
Documentação de Load do SvelteKit — referência oficial para cookies e setHeaders em funções load