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 redireciona o usuário 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 fazer isso corretamente na fração de segundo entre a chegada da requisição e o envio da resposta.

Essa oportunidade existe dentro de uma função de server load. Usá-la corretamente significa entender três coisas que estão próximas umas das outras, mas que se comportam de forma diferente: ler cookies com o objeto cookies, definir cookies com cookies.set() em vez de por meio de um header de resposta, e definir outros headers de resposta com setHeaders de uma forma que leva 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 é suficiente para começar, mas deixa de fora o raciocínio que determina quando ler um cookie é a abordagem correta, 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 pelo 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 forma 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 fetch simples para endpoints de API. Isso mantém os exemplos focados no comportamento do SvelteKit que está 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 de 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 dos dados do layout pai, em vez de ler o cookie novamente por conta própria.

O padrão parece simples, mas envolve quatro preocupações distintas que precisam ser tratadas com cuidado:

Ler cookies corretamente significa entender o objeto cookies no evento de load, quais cookies são acessíveis a partir 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 carrega automaticamente 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 evita uma classe sutil de bugs.

Definir headers de resposta com setHeaders controla como o navegador e quaisquer caches intermediários tratam a resposta. Tem um efeito significativo durante o SSR e um efeito diferente e mais limitado durante a navegação do lado do cliente. Saber 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 de header HTTP bruto. É uma API estruturada que o SvelteKit constrói a partir do header de requisição Cookie de entrada e mantém ao longo do tempo de vida da requisição.

Quando você chama cookies.get('session'), o SvelteKit analisa a string de cookie, encontra o cookie com o nome informado 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 a leitura de um cookie de sessão, a determinação de que ele expirou, a exclusão do cookie antigo e a definição de um novo atualizado. O objeto cookies mantém a 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. Afeta a resposta HTTP que o navegador ou cache recebe, não os dados que fluem para o componente da 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 do 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 do 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 possui um servidor de API em api.example.com. Essas 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 correspondam 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 ser aplicada de forma consistente: para rotas internas de mesma origem, confie no encaminhamento automático. Para requisições de origem cruzada, encaminhe credenciais de forma explícita e deliberada. 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 através 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 interno de estado 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() impõe uma configuração padrão que faz escolhas seguras, a menos que você opte explicitamente por sair delas. A abordagem de string bruta exige que você se lembre de cada atributo em todas as ocasiões.

// 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 espera-se 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 serve para cada 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 à frente de sua aplicação por 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 diz aos intermediários que eles têm permissão para armazená-la em cache e servi-la a qualquer usuário. Uma resposta private diz a eles para mantê-la apenas para o único navegador que a solicitou. Se uma página contiver dados específicos 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 poderá ser servida a partir 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 lida com a navegação internamente. A função de load é executada no navegador, busca dados e atualiza a página. setHeaders é chamado neste contexto, mas não tem uma resposta HTTP para anexar os headers. O SvelteKit ignora a chamada silenciosamente. Os headers de controle de cache que você definir 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 da página completa na primeira visita. Eles não afetam como o SvelteKit gerencia as 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 ela 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 o carregamento inicial da página, setHeaders é a ferramenta certa. Se você precisar controlar quando o SvelteKit re-executa 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 está 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 computar isAuthenticated a partir do valor data.user. Isso mantém a reatividade limpa: se os dados do usuário mudarem na mesma sessão de 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 de carregamento 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 de carregamento em +page.ts não inclui uma propriedade cookies. Mas o motivo a entender é que as funções de carregamento universal 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 com string de cabeçalho bruto ignora o rastreamento interno de estado de cookies do SvelteKit. Qualquer chamada subsequente a cookies.get('session_id') dentro do mesmo ciclo de vida da requisição não veria o novo valor porque o objeto cookies nunca foi notificado da mudança.

Definindo cabeçalhos conflitantes entre funções de carregamento de layout e 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 as funções de carregamento de layout e 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 de carregamento mais específica para uma determinada rota: a função de carregamento do servidor da página. O layout não deve definir cabeçalhos de cache se páginas individuais precisarem 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á excluindo o correto.

Considerações de Desempenho e Escalabilidade

O carregamento do servidor no layout raiz é executado em toda requisição renderizada no servidor. Em uma aplicação autenticada, isso significa que a busca de validação de sessão é executada em toda 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 o Redis é uma operação de sub-milissegundo. Uma consulta ao banco de dados sem índice pode levar dezenas de milissegundos. A diferença é insignificante por si só, mas se multiplica em milhares de usuários simultâneos e se torna o fator limitante no throughput do seu servidor.

Para aplicações em que a maioria das páginas é acessível publicamente, a verificação condicional no início do carregamento 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 podem ser armazenadas em cache publicamente, setHeaders com diretivas apropriadas de Cache-Control e Vary permite que CDNs sirvam a página sem acionar 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 armazenada em cache na borda com um TTL razoável, e a função de carregamento 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 em que a maioria ou todas as páginas compartilham o conceito do usuário atual. Mas nem toda aplicação tem essa estrutura.

Sites puramente públicos sem nenhuma autenticação não têm utilidade para cookies de sessão em funções de carregamento. 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 utilizam funções de carregamento de página de forma alguma. O tratamento de cookies para esses casos é feito diretamente no manipulador de requisição, não através das APIs de funções de carregamento.

Layouts muito específicos 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 comum, ler a sessão no layout raiz força uma leitura de cookie em todas as páginas, 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 de carregamento para atualização de dados. As funções de carregamento 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 gerencia a atualização com um $effect que configura um intervalo de polling ou uma conexão WebSocket. A função de carregamento fornece o snapshot inicial e o componente o mantém atualizado.

Conclusão

Cookies e cabeçalhos de resposta em funções de carregamento do servidor não são complicados, mas possuem regras que importam. Cookies pertencem exclusivamente a +page.server.ts e +layout.server.ts porque esses são os únicos contextos com garantia de execução no servidor. O objeto cookies é stateful dentro de uma requisição, e todas as mutações de cookies devem passar por ele porque o SvelteKit rastreia esse estado internamente. Definir um cookie através de setHeaders contorna 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 armazenar em cache a página renderizada. Durante navegações no lado do cliente, esses cabeçalhos não têm efeito porque não há resposta HTTP à qual anexá-los.

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 por meio da mesclagem de dados do SvelteKit — é a base arquitetural correta para autenticação. Ele mantém as leituras de cookies em um único lugar, evita validações redundantes e torna a identidade do usuário disponível sem prop drilling por todos os layouts e páginas da hierarquia.

Principais Aprendizados

Principais aprendizados:

Cookies são acessíveis apenas em +page.server.ts e +layout.server.ts. Funções de carregamento universais não podem acessá-los.
Todas as mutações de cookies, 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() requer uma opção path explícita. Sempre use path: '/' a menos que tenha um motivo para restringir o cookie a uma subárvore.
O event.fetch do SvelteKit encaminha cookies automaticamente para requisições de mesma origem. Requisições de origem cruzada requerem encaminhamento explícito de credenciais.
setHeaders define cabeçalhos de resposta HTTP para a resposta SSR. Não tem efeito durante navegações no lado do cliente.
Use Cache-Control: private, no-store para páginas com dados específicos do usuário e public, max-age=N para páginas armazenáveis em cache publicamente.
Definir o mesmo cabeçalho tanto no layout quanto nas funções de carregamento do servidor da página lança um erro de conflito. Atribua a responsabilidade pelo controle de cache à função de carregamento mais específica para cada rota.
Leia o cookie de sessão no carregamento do servidor do layout raiz exatamente uma vez por requisição e use parent() nos carregamentos 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 das funções de carregamento do servidor. Mas há uma questão mais ampla: onde dados com escopo de requisição, como uma sessão validada, realmente residem antes de chegarem a uma função de carregamento, e como são colocados lá em primeiro lugar? A resposta é event.locals, populado pelo 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 de carregamento do servidor em sua aplicação.

Leitura Adicional

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