O Arquivo Negligenciado que Tipifica Toda a Sua Aplicação

Todo projeto SvelteKit gerado com suporte a TypeScript contém um arquivo chamado src/app.d.ts. Ele é pequeno por padrão, fácil de ignorar, e quase completamente inexplicado na maioria dos tutoriais. Você pode tê-lo aberto uma vez, visto duas interfaces vazias, e fechado sem pensar duas vezes.

Isso seria um erro.

app.d.ts é o arquivo onde você informa ao TypeScript o que sua aplicação SvelteKit fundamentalmente é em tempo de execução. Ele define a forma dos dados que fluem pelos seus hooks de servidor, pelas suas funções de carregamento, pelas suas ações de formulário e para dentro dos seus componentes. Sem ele, o TypeScript não tem ideia do que existe em event.locals, qual a forma dos seus erros, ou quais APIs de plataforma estão disponíveis no servidor. Com ele preenchido corretamente, toda a sua aplicação ganha uma segurança de tipos coerente e de ponta a ponta, que acompanha os dados desde o momento em que entram em uma requisição até o momento em que são renderizados no navegador.

Este artigo aborda tudo sobre o app.d.ts: por que o SvelteKit precisa de um arquivo de declaração global dedicado, o que cada uma de suas interfaces significa e controla, como construí-las corretamente para aplicações de produção reais, e os padrões que escalam desde um projeto pessoal simples até um SaaS multi-tenant com múltiplos alvos de implantação.

Por que Existe um Arquivo de Declaração Global Dedicado

Para entender por que o app.d.ts existe, você precisa entender a arquitetura do SvelteKit. O SvelteKit não é uma biblioteca de tempo de execução que você chama. É um framework que chama o seu código. Você escreve +page.server.ts, e o SvelteKit chama sua função load com um argumento LoadEvent. Você escreve src/hooks.server.ts, e o SvelteKit chama sua função handle com um RequestEvent.

Os tipos para esses eventos — LoadEvent, RequestEvent, PageServerLoad e outros — são gerados pelo próprio sistema de tipos do SvelteKit e dependem do que a sua aplicação coloca neles.

O objeto event.locals, por exemplo, existe como um contêiner completamente aberto. O SvelteKit o cria para cada requisição, passa-o pelos seus hooks, e o disponibiliza em cada função de carregamento e ação de formulário. Mas o próprio SvelteKit não tem ideia do que você coloca lá. Você pode populá-lo com um objeto user vindo da validação de sessão, um registro featureFlags de um serviço de configuração, um objeto tenant da resolução de subdomínio, ou tudo isso junto.

O TypeScript não consegue inferir nada disso. Ele precisa ser informado.

O SvelteKit resolve isso por meio de um mecanismo chamado augmentação de módulo. O framework disponibiliza interfaces internas como stubs vazios dentro de suas próprias definições de tipos. Você preenche esses stubs augmentando o namespace App dentro de src/app.d.ts.

Um stub é uma definição de tipo placeholder que não possui propriedades ou métodos reais. Os tipos internos do SvelteKit para `event.locals`, `event.platform` e outros são stubs até que você os augmente em `app.d.ts`. Esse design permite que o SvelteKit seja flexível e agnóstico ao framework, ao mesmo tempo que lhe dá o poder de definir os contratos de dados específicos da sua aplicação.

Quando o TypeScript compila seu projeto, ele mescla suas declarações com as do SvelteKit, e de repente todo event.locals em todos os arquivos de todo o seu projeto carrega o tipo que você declarou. Sem importações, sem asserções de tipo manuais, sem casts as User espalhados pelo seu código.

Esse é o poder do app.d.ts: é uma declaração do contrato de tempo de execução que sua aplicação mantém, e o TypeScript usa isso para verificar esse contrato em todos os lugares automaticamente.

O diagrama acima mostra o relacionamento com clareza. Você declara uma vez em app.d.ts, o sistema de tipos do SvelteKit o detecta, e ele se propaga para todos os lugares onde o framework passa essas estruturas para o seu código.

Anatomia do Arquivo Padrão

Um projeto SvelteKit recém-criado fornece o seguinte:

// src/app.d.ts

// See https://svelte.dev/docs/kit/types#app-namespace
// for information about these interfaces
declare global {
	namespace App {
		// interface Error {}
		// interface Locals {}
		// interface PageData {}
		// interface PageState {}
		// interface Platform {}
	}
}

export {}

Cinco interfaces comentadas dentro do namespace App, envoltas em um bloco declare global. O export {} no final não é decoração; ele faz o TypeScript tratar o arquivo como um módulo em vez de um script, o que é necessário para que o declare global funcione corretamente. Se você o remover, a augmentação quebra silenciosamente.

Cada uma dessas cinco interfaces corresponde a uma parte específica do modelo de dados de tempo de execução do SvelteKit. Vamos percorrê-las uma a uma, da mais comumente usada à mais especializada.

App.Locals: O Portador de Dados com Escopo de Requisição

App.Locals é a mais importante das cinco interfaces para a maioria das aplicações. Ela tipifica a propriedade locals que existe no RequestEvent, o objeto que seu hook handle recebe para cada requisição recebida.

O objeto locals é a resposta do SvelteKit à pergunta: "como faço para passar dados do lado do servidor para minhas funções de carregamento sem buscá-los duas vezes?" Você autentica o usuário uma vez no seu hook handle, anexa o resultado ao locals, e cada +page.server.ts e +layout.server.ts subsequente pode lê-lo diretamente de event.locals sem fazer outra chamada ao banco de dados ou API.

Veja como uma declaração realista de App.Locals se parece para uma aplicação com autenticação baseada em sessão:

// src/app.d.ts

declare global {
	namespace App {
		interface Locals {
			user: {
				id: string
				email: string
				role: 'admin' | 'editor' | 'viewer'
				displayName: string
			} | null
			session: {
				id: string
				expiresAt: Date
			} | null
			requestId: string
		}
	}
}

export {}

Essa forma inline é adequada para começar e torna a estrutura imediatamente visível. Na prática, quando seus tipos User e Session existirem em $lib/types.ts, referencie-os com expressões de tipo import() — caso contrário, você acaba mantendo a mesma forma em dois lugares:

// src/app.d.ts — preferred in real projects

declare global {
	namespace App {
		interface Locals {
			user: import('$lib/types').User | null
			session: import('$lib/types').Session | null
			requestId: string
		}
	}
}

export {}

A seção de Erros Comuns no final deste artigo aborda esse padrão com mais detalhes.

Com isso implementado, o hook handle em src/hooks.server.ts pode popular esses campos com verificação de tipos completa:

// src/hooks.server.ts

import type { Handle } from '@sveltejs/kit'
import { nanoid } from 'nanoid'
// nanoid - a tiny, secure, URL-friendly, unique string ID generator for JavaScript.

export const handle: Handle = async ({ event, resolve }) => {
	// requestId is always set — no auth needed for this
	event.locals.requestId = nanoid()

	const sessionToken = event.cookies.get('session')

	if (!sessionToken) {
		event.locals.user = null
		event.locals.session = null
		return resolve(event)
	}

	const sessionData = await fetch(`${event.url.origin}/api/sessions/${sessionToken}`, {
		headers: { 'x-internal-key': process.env.INTERNAL_KEY ?? '' }
	}).then((r) => (r.ok ? r.json() : null))

	if (!sessionData) {
		event.locals.user = null
		event.locals.session = null
		return resolve(event)
	}

	event.locals.user = sessionData.user
	event.locals.session = {
		id: sessionData.sessionId,
		expiresAt: new Date(sessionData.expiresAt)
	}

	return resolve(event)
}

O TypeScript agora aplica cada atribuição. Se você tentar definir event.locals.user = { id: 123 } (número em vez de string), o compilador detecta o problema. Se você tentar ler event.locals.permissions (um campo que você nunca declarou), o compilador rejeita. Todo o pipeline de locals se torna type-safe sem uma única importação ou cast.

Nas suas funções de carregamento, ler de locals é igualmente limpo:

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

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

export const load: LayoutServerLoad = async ({ locals }) => {
	// TypeScript knows locals.user is { id, email, role, displayName } | null
	if (!locals.user) {
		redirect(302, '/login')
	}

	// After the redirect guard, TypeScript narrows the type
	// locals.user is now non-null below this point
	return {
		currentUser: locals.user
	}
}

O estreitamento após a chamada redirect é um benefício sutil, mas importante. Como redirect lança uma exceção (nunca retorna), o TypeScript estreita corretamente locals.user de User | null para User após a guarda. Você obtém tipos precisos sem asserção manual.

App.PageData: Tipificando o Objeto de Dados nos Seus Componentes

App.PageData é menos comumente escrito manualmente, porque o SvelteKit gera o tipo PageData para cada rota automaticamente a partir do tipo de retorno de sua função load. Quando você examina o arquivo ./$types gerado em qualquer diretório de rota, encontrará um tipo PageData que reflete exatamente o que seu load retornou.

No entanto, App.PageData serve a um propósito diferente: ele define uma linha de base para todo o site para dados que estão sempre presentes em page.data, independentemente de qual rota está ativa. Isso é particularmente útil quando a função de carregamento do seu layout raiz sempre fornece determinados campos.

Considere uma aplicação onde o layout raiz sempre carrega o usuário atual e a configuração global de navegação:

// src/app.d.ts

declare global {
	namespace App {
		interface Locals {
			user: import('$lib/types').User | null
			requestId: string
		}

		interface PageData {
			// These come from +layout.server.ts at the root and are
			// always present on $page.data across the entire site
			currentUser: import('$lib/types').User | null
			siteConfig: {
				siteName: string
				maintenanceMode: boolean
				featureFlags: Record<string, boolean>
			}
		}
	}
}

export {}

Com App.PageData declarado dessa forma, page.data em qualquer componente de toda a sua aplicação carrega esses campos com tipos corretos, mesmo sem importar nada:

<!-- src/lib/components/NavBar.svelte -->
<script>
	import { page } from '$app/state'
</script>

<!-- TypeScript knows page.data.currentUser and page.data.siteConfig exist -->
{#if page.data.currentUser}
	<span>Welcome, {page.data.currentUser.displayName}</span>
{/if}

{#if page.data.siteConfig.maintenanceMode}
	<div class="banner">Scheduled maintenance in progress.</div>
{/if}

A percepção-chave é que App.PageData representa a interseção do que todas as suas páginas compartilham. Ele não substitui os tipos por rota; ele os augmenta. O tipo PageData de uma rota específica (de ./$types) incluirá tanto os campos específicos da rota quanto tudo que foi declarado em App.PageData.

Não use isso em excesso. App.PageData deve conter apenas dados que genuinamente aparecem em todas as páginas. Se você adicionar um campo aqui que seu layout raiz não popula de fato, você criou uma mentira de tipo que confundirá qualquer pessoa que leia o código mais tarde.

App.Error: Definindo a Forma dos Seus Payloads de Erro

Por padrão, o helper error() do SvelteKit aceita um código de status e uma string de mensagem. O objeto de erro resultante tem a forma { message: string }. Isso é suficiente para aplicações simples, mas sistemas de produção geralmente precisam de informações de erro mais ricas: códigos de erro para tratamento no lado do cliente, IDs de correlação para rastreamento de logs, detalhes estruturados para mensagens voltadas ao usuário em múltiplos idiomas.

App.Error permite que você declare a forma de cada objeto de erro que o SvelteKit produz e que os arquivos +error.svelte recebem. O único requisito é que a interface deve incluir message: string, porque o próprio framework define esse campo em vários lugares.

Uma interface de erro bem projetada para uma aplicação de produção com backend de API:

// src/app.d.ts

declare global {
	namespace App {
		interface Error {
			message: string
			code: string // machine-readable error code, e.g. 'AUTH_REQUIRED'
			correlationId?: string // ties the error back to a server log entry
			detail?: string // extended human-readable explanation
		}
	}
}

export {}

Quando você lança erros nas suas funções de carregamento ou rotas de servidor, você passa um objeto correspondente a essa forma:

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

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

export const load: PageServerLoad = async ({ locals, fetch }) => {
	if (!locals.user) {
		error(401, {
			message: 'Authentication required',
			code: 'AUTH_REQUIRED',
			correlationId: locals.requestId
		})
	}

	const profile = await fetch(`/api/users/${locals.user.id}/profile`).then((r) => {
		if (!r.ok) {
			error(500, {
				message: 'Failed to load profile data',
				code: 'PROFILE_FETCH_FAILED',
				correlationId: locals.requestId,
				detail: `Upstream responded with ${r.status}`
			})
		}
		return r.json()
	})

	return { profile }
}

O componente +error.svelte em qualquer nível pode então acessar esses campos por meio de page.error:

<!-- src/routes/+error.svelte -->
<script>
	import { page } from '$app/state'
</script>

<div class="error-page">
	<h1>{page.status}</h1>
	<p>{page.error?.message}</p>

	{#if page.error?.code}
		<code class="error-code">{page.error.code}</code>
	{/if}

	{#if page.error?.correlationId}
		<p class="correlation">
			Reference ID: <code>{page.error.correlationId}</code>
		</p>
	{/if}

	{#if page.error?.detail}
		<details>
			<summary>Technical details</summary>
			<p>{page.error.detail}</p>
		</details>
	{/if}
</div>

Uma nota sutil: você também precisa implementar o hook handleError em src/hooks.server.ts se quiser que erros não capturados (aqueles não explicitamente lançados com error()) estejam em conformidade com sua forma App.Error. Sem ele, erros inesperados terão apenas { message: string } e nenhum dos seus campos adicionais:

// src/hooks.server.ts

import type { HandleServerError } from '@sveltejs/kit'

export const handleError: HandleServerError = ({ error, event, status, message }) => {
	const correlationId = event.locals.requestId ?? 'unknown'

	// Log the full error server-side for diagnostics
	console.error(`[${correlationId}] Unhandled error:`, error)

	// Return only what is safe to expose to the client
	return {
		message: status === 500 ? 'An unexpected error occurred.' : message,
		code: 'INTERNAL_ERROR',
		correlationId
	}
}

O hook handleError é o adaptador entre seus erros de servidor não controlados e a forma tipada App.Error que você prometeu entregar. Trate-o como um complemento obrigatório para qualquer definição não trivial de App.Error.

App.Platform: Alvejando Ambientes de Implantação Específicos

App.Platform é a mais específica de ambiente das cinco interfaces. Ela tipifica o objeto event.platform, que os adaptadores do SvelteKit populam com APIs e contextos específicos da plataforma quando sua aplicação é executada em um determinado alvo de implantação.

Se você faz implantação no Node.js com adapter-node, event.platform é essencialmente indefinido porque o próprio Node.js fornece todas as APIs padrão que você precisa. Mas se você implanta no Cloudflare Workers ou Cloudflare Pages, o objeto de plataforma carrega bindings para a infraestrutura da Cloudflare: namespaces KV, buckets R2, bancos de dados D1, Durable Objects, variáveis de ambiente e o contexto de execução para waitUntil.

Sem App.Platform declarado, acessar event.platform retorna App.Platform | undefined, e App.Platform é uma interface vazia, portanto cada acesso a propriedade é um erro de tipo.

Veja uma declaração realista para o Cloudflare Pages:

// src/app.d.ts

declare global {
	namespace App {
		interface Locals {
			user: import('$lib/types').User | null
			requestId: string
		}

		interface Platform {
			env: {
				// KV namespace for session storage
				SESSIONS_KV: KVNamespace
				// R2 bucket for user file uploads
				UPLOADS_BUCKET: R2Bucket
				// D1 database binding
				DB: D1Database
				// Plain environment variables (secrets, config)
				AUTH_SECRET: string
				INTERNAL_API_URL: string
			}
			context: {
				waitUntil(promise: Promise<unknown>): void
			}
			caches: CacheStorage & { default: Cache }
			cf?: IncomingRequestCfProperties
		}
	}
}

export {}

Note que KVNamespace, R2Bucket, D1Database, CacheStorage e IncomingRequestCfProperties são tipos provenientes de @cloudflare/workers-types. Você instala esse pacote como dependência de desenvolvimento e o referencia aqui. Os tipos não precisam ser importados com uma instrução import porque são declarados como globais pelo próprio pacote workers-types.

Com isso declarado, seu código do lado do servidor ganha segurança de tipos completa para as APIs da Cloudflare:

// src/hooks.server.ts

import type { Handle } from '@sveltejs/kit'
import { nanoid } from 'nanoid'

export const handle: Handle = async ({ event, resolve }) => {
	event.locals.requestId = nanoid()

	// TypeScript knows event.platform.env.SESSIONS_KV is a KVNamespace
	const sessionToken = event.cookies.get('session')

	if (sessionToken && event.platform) {
		const sessionJson = await event.platform.env.SESSIONS_KV.get(sessionToken)

		if (sessionJson) {
			const session = JSON.parse(sessionJson)
			event.locals.user = session.user
		} else {
			event.locals.user = null
		}
	} else {
		event.locals.user = null
	}

	const response = await resolve(event)

	// Use waitUntil to update session expiry without blocking the response
	if (sessionToken && event.platform && event.locals.user) {
		event.platform.context.waitUntil(
			event.platform.env.SESSIONS_KV.put(
				sessionToken,
				JSON.stringify({
					user: event.locals.user
				}),
				{ expirationTtl: 86400 }
			)
		)
	}

	return response
}

event.platform é sempre anulável porque seu código pode ser executado em uma plataforma que não o popula (por exemplo, durante o vite dev). Sempre proteja com if (event.platform) antes de acessar APIs específicas da plataforma. O sistema de tipos aplica isso corretamente: event.platform é tipado como App.Platform | undefined.

Se você almeja múltiplas plataformas ou quer suportar implantações tanto na Cloudflare quanto no Node a partir do mesmo código-fonte, você pode usar uma abordagem de união:

// src/app.d.ts

interface CloudflarePlatform {
	env: {
		SESSIONS_KV: KVNamespace
		UPLOADS_BUCKET: R2Bucket
		AUTH_SECRET: string
	}
	context: { waitUntil(promise: Promise<unknown>): void }
}

interface VercelEdgePlatform {
	env: Record<string, string>
}

declare global {
	namespace App {
		interface Platform extends Partial<CloudflarePlatform>, Partial<VercelEdgePlatform> {}
	}
}

export {}

Esse padrão cria uma interface de plataforma onde todas as propriedades específicas da plataforma são opcionais. Seu código então usa verificações em tempo de execução ('env' in event.platform && 'SESSIONS_KV' in event.platform.env) além da guarda nula para ramificar adequadamente. É uma abordagem pragmática quando uma separação limpa de plataforma não é possível.

App.PageState: Roteamento Shallow Tipificado

App.PageState é a mais nova das cinco interfaces e a menos familiar para a maioria dos desenvolvedores. Ela tipifica a propriedade state usada com a API de roteamento shallow do SvelteKit.

O roteamento shallow permite atualizar a URL e empurrar entradas na pilha de histórico do navegador sem acionar uma navegação completa e re-executar as funções de carregamento. O caso de uso canônico é uma visualização de detalhe que sobrepõe a página atual — como clicar em uma foto em uma galeria para abrir um visualizador modal — onde a URL deve ser atualizada (para que o compartilhamento funcione), mas a página subjacente não deve recarregar.

Você empurra estado shallow usando a função pushState de $app/navigation:

import { pushState } from '$app/navigation'

// Opens a modal showing the selected article without leaving the list
function openArticleModal(articleId: string) {
	pushState(`/articles/${articleId}`, {
		modalOpen: true,
		selectedArticleId: articleId
	})
}

O segundo argumento para pushState é o objeto de estado. Sem App.PageState, o TypeScript aceita isso como App.PageState & Record<string, unknown>, que é funcionalmente sem tipo. Com ele declarado, o objeto de estado é totalmente tipado:

// src/app.d.ts

declare global {
	namespace App {
		interface PageState {
			modalOpen?: boolean
			selectedArticleId?: string
			selectedImageIndex?: number
			drawerOpen?: boolean
		}
	}
}

export {}

A leitura do estado de volta em um componente usa page.state:

<!-- src/routes/articles/+page.svelte -->
<script>
	import { page } from '$app/state'
	import { pushState, replaceState } from '$app/navigation'
	import ArticleModal from '$lib/components/ArticleModal.svelte'
	import type { PageData } from './$types'

	let { data }: { data: PageData } = $props()

	function openModal(articleId: string) {
		pushState(`/articles/${articleId}`, {
			modalOpen: true,
			selectedArticleId: articleId
		})
	}

	function closeModal() {
		// replaceState to avoid adding a history entry for the close action
		replaceState('', {
			modalOpen: false,
			selectedArticleId: undefined
		})
	}
</script>

<ul>
	{#each data.articles as article}
		<li>
			<button onclick={() => openModal(article.id)}>
				{article.title}
			</button>
		</li>
	{/each}
</ul>

<!-- TypeScript knows page.state.modalOpen and page.state.selectedArticleId -->
{#if page.state.modalOpen && page.state.selectedArticleId}
	<ArticleModal articleId={page.state.selectedArticleId} onclose={closeModal} />
{/if}

Todos os campos em App.PageState devem ser opcionais, pois o estado da página começa vazio quando o usuário carrega uma URL diretamente pela primeira vez. Nunca é possível garantir qual estado existe na entrada do histórico em que o usuário chegou.

Compondo um app.d.ts de Produção

Tudo o que foi abordado até agora se reúne em um único arquivo para uma aplicação real. Veja como um app.d.ts completo e pronto para produção se parece em um SaaS multi-tenant implantado no Cloudflare Pages:

// src/app.d.ts

declare global {
	namespace App {
		interface Locals {
			// Authenticated user, or null if the request is unauthenticated
			// This is the single source of truth for "who is making this request?" across the entire app.
			user: {
				// You should use imports from your shared types rather than inline shapes in real projects
				// user: import('$lib/types').User | null
				id: string
				email: string
				role: 'owner' | 'admin' | 'member' | 'viewer'
				displayName: string
				avatarUrl: string | null
			} | null

			// The resolved tenant from subdomain/path/header routing
			tenant: {
				// You should use imports from your shared types rather than inline shapes in real projects
				// tenant: import('$lib/types').Tenant | null
				id: string
				slug: string
				name: string
				plan: 'free' | 'pro' | 'enterprise'
				features: Record<string, boolean>
			} | null

			// Unique ID for this request, used in logs and error correlation
			requestId: string

			// Performance timing helper — populated by the handle hook
			requestStartTime: number
		}

		interface PageData {
			// Always populated by the root +layout.server.ts
			// Null when unauthenticated (public pages)
			currentUser: App.Locals['user']
			currentTenant: App.Locals['tenant']
		}

		interface Error {
			message: string
			code: string
			correlationId?: string
			detail?: string
			fieldErrors?: Record<string, string[]>
		}

		interface Platform {
			env: {
				// Session storage
				SESSIONS_KV: KVNamespace
				// File storage
				ASSETS_BUCKET: R2Bucket
				// Primary database
				DB: D1Database
				// Secrets
				AUTH_SECRET: string
				ENCRYPTION_KEY: string
				INTERNAL_API_KEY: string
			}
			context: {
				waitUntil(promise: Promise<unknown>): void
				passThroughOnException(): void
			}
			cf?: IncomingRequestCfProperties
		}

		interface PageState {
			// Overlay/modal routing state
			modalOpen?: boolean
			modalType?: 'create-project' | 'invite-member' | 'confirm-delete' | 'view-asset'
			modalEntityId?: string

			// Drawer / panel state for split-view layouts
			detailPanelOpen?: boolean
			selectedItemId?: string
		}
	}
}

export {}

Este arquivo tem aproximadamente 60 linhas. Ele descreve o contrato de tempo de execução de uma aplicação SaaS inteira: quem pode ser autenticado, qual contexto de tenant flui por cada requisição, quais APIs de plataforma estão disponíveis, como os erros são estruturados, qual estado de sobreposição em nível de página existe. Qualquer desenvolvedor que entre no projeto pode ler este arquivo e entender o modelo de dados fundamental da aplicação em menos de cinco minutos.

O Fluxo de Dados, de Ponta a Ponta

É útil ver como os tipos declarados em app.d.ts se conectam ao longo de todo o ciclo de vida da requisição. O diagrama a seguir rastreia uma única requisição autenticada desde a chegada HTTP até a renderização do componente:

Os tipos fluem porque App.Locals é declarado uma vez e o TypeScript automaticamente o propaga pelo tipo de event em cada hook, função de carregamento e ação de servidor em toda a sua base de código.

Erros Comuns e Anti-Padrões

Esquecer o `export {}` no Final

// Avoid — missing export {}
declare global {
	namespace App {
		interface Locals {
			user: User | null
		}
	}
}

// Preferred — always include export {}
declare global {
	namespace App {
		interface Locals {
			user: User | null
		}
	}
}

export {}

Sem o export {}, o TypeScript trata o arquivo como um script global em vez de um módulo. declare global dentro de um contexto de script não funciona como esperado, e o augmentation falha silenciosamente. Seu event.locals.user será tipado como any ou gerará erros, e a causa será difícil de rastrear. Sempre inclua export {}.

Usar Tipos Inline em Vez de Importar Definições Compartilhadas

Quando você declara informações do tipo User diretamente em app.d.ts, cria um risco de manutenção. Se o seu tipo User mudar (por exemplo, você adicionar um campo displayName), precisará lembrar de atualizá-lo em dois lugares: a fonte da verdade (ex.: $lib/types/user.ts) e a declaração inline em app.d.ts. Essa duplicação é propensa a erros e pode levar a incompatibilidades de tipos que o TypeScript não consegue detectar.

// Avoid — duplicating type definitions inline in app.d.ts
declare global {
	namespace App {
		interface Locals {
			user: {
				id: string
				email: string
				role: 'admin' | 'editor'
			} | null
		}
	}
}

// Preferred — import from a shared type definition
declare global {
	namespace App {
		interface Locals {
			user: import('$lib/types/user').User | null
		}
	}
}

Preencher Campos de Locals Sem Declará-los

// Avoid — setting a field TypeScript has not been told about
export const handle: Handle = async ({ event, resolve }) => {
	;(event.locals as any).featureFlags = await loadFeatureFlags()
	return resolve(event)
}

// Preferred — declare it, then set it
// In app.d.ts:
interface Locals {
	featureFlags: Record<string, boolean>
}

// In hooks.server.ts:
export const handle: Handle = async ({ event, resolve }) => {
	event.locals.featureFlags = await loadFeatureFlags()
	return resolve(event)
}

Usar as any para contornar a tipagem de locals é um atalho comum que anula todo o propósito de App.Locals. O erro do TypeScript informando que uma propriedade não existe em event.locals é um sinal de que você precisa atualizar app.d.ts, não uma razão para fazer cast para any.

Colocar Dados Específicos de Rota em App.PageData

// Avoid — specific route data in App.PageData
interface PageData {
	currentUser: User | null
	articleList: Article[] // Only exists on /articles
	dashboardStats: Stats // Only exists on /dashboard
}

// Preferred — only genuinely universal data in App.PageData
interface PageData {
	currentUser: User | null
	siteConfig: SiteConfig
}

App.PageData promete que esses campos existem em todas as páginas. Se articleList vier apenas do loader da rota /articles, ele será undefined em todos os outros lugares, criando um contrato de tipo falso que causará erros em tempo de execução. Mantenha App.PageData enxuto e genuinamente universal.

Considerações de Desempenho e Escalabilidade

app.d.ts é uma construção em tempo de compilação. Ele tem custo zero em tempo de execução. O TypeScript apaga todas as informações de tipo durante a compilação, portanto as interfaces que você declara aqui não produzem nenhuma saída JavaScript.

As considerações de desempenho são, portanto, sobre design em vez de execução. Uma interface Locals com muitos campos profundamente aninhados incentiva um padrão em que o hook handle realiza muito trabalho em cada requisição, mesmo para rotas que não precisam de nenhum desses dados. Uma requisição a /favicon.ico não deveria acionar uma sequência completa de validação de sessão e resolução de tenant.

Estruturar seu hook handle para ser condicional com base no caminho da requisição é uma resposta prática a isso, e app.d.ts oferece bom suporte através de campos opcionais:

// src/app.d.ts

interface Locals {
	requestId: string // Always populated
	user: import('$lib/types').User | null // Populated for non-static routes
	tenant: import('$lib/types').Tenant | null // Populated for tenant routes only
}

Tornar user e tenant anuláveis (em vez de tipos não nulos obrigatórios) sinaliza no sistema de tipos que nem toda requisição os preenche. Funções de carregamento que exigem autenticação verificam se são nulos e redirecionam ou geram erros adequadamente. Isso é uma modelagem precisa do comportamento da sua aplicação.

Para equipes grandes trabalhando na mesma base de código, app.d.ts se torna um ponto de coordenação. Alterações em App.Locals afetam cada função de carregamento e hook em todo o projeto. Remover um campo ou alterar seu tipo é uma refatoração que o TypeScript guiará com erros de compilação em cada ponto de uso, que é exatamente a ferramenta certa para o trabalho. Trate as alterações em app.d.ts com o mesmo cuidado que você daria a um contrato de API compartilhado.

Quando NÃO Depender Exclusivamente de app.d.ts

app.d.ts cuida da tipagem na fronteira do framework SvelteKit, mas não substitui um sistema de tipos bem estruturado para o modelo de domínio da sua própria aplicação. Não coloque todo o seu sistema de tipos de domínio em app.d.ts. As interfaces aqui devem ser referências enxutas a tipos que vivem em $lib/types, não a fonte da verdade para esses tipos.

Da mesma forma, app.d.ts não fornece validação em tempo de execução. Se o seu hook de validação de sessão receber uma resposta JSON malformada de uma API de autenticação e você a atribuir diretamente a event.locals.user, o TypeScript não detectará a incompatibilidade em tempo de execução. Para dados que cruzam um limite de rede, use uma biblioteca de validação de esquema (como Zod ou Valibot) para validar antes de atribuir a locals. A declaração de tipo em app.d.ts então documenta o contrato pós-validação, não a esperança pré-validação.

Se você está construindo uma biblioteca ou um pacote SvelteKit destinado ao uso dentro de outros projetos, não pode fazer augment do namespace App por conta própria; esse privilégio pertence à aplicação consumidora. Tipos específicos de biblioteca devem usar outros mecanismos (exportações tipadas, wrappers genéricos) em vez do augmentation via app.d.ts.

Conclusão

app.d.ts é o menor arquivo em um projeto SvelteKit e um dos mais consequentes. É o arquivo onde você descreve, na linguagem do TypeScript, o contrato de tempo de execução que sua aplicação mantém. Declare App.Locals e todo o seu pipeline de requisições ganha segurança de tipos coerente e integrada ao framework. Declare App.Error e seu tratamento de erros se torna consistente e confiável desde o hook de servidor até o componente de erro. Declare App.Platform e as APIs do seu alvo de implantação se tornam cidadãos de primeira classe do TypeScript.

O investimento necessário é mínimo: um punhado de declarações de interface que você escreve uma vez e atualiza conforme sua aplicação evolui. O retorno é substancial: uma base de código onde o TypeScript entende o fluxo completo de dados desde a requisição HTTP até o componente renderizado, onde erros de tipo detectam violações de contrato antes que cheguem à produção, e onde novos colaboradores podem entender o modelo de dados em tempo de execução da aplicação lendo um único arquivo.

Principais Conclusões

app.d.ts usa o augmentation de módulo do TypeScript para injetar tipos nas interfaces do framework do SvelteKit, tornando-o a fonte única da verdade para o contrato de tipo em tempo de execução da sua aplicação.

Principais conclusões:

App.Locals tipa event.locals em todos os hooks, funções de carregamento e ações de servidor sem nenhuma importação ou cast manual
App.Error define a forma de todos os objetos de erro; combine-o com handleError em hooks.server.ts para garantir que erros não capturados estejam em conformidade com a mesma forma
App.Platform torna as APIs do alvo de implantação totalmente tipadas; sempre proteja com if (event.platform) pois pode ser undefined em desenvolvimento
App.PageData deve conter apenas campos que o layout raiz genuinamente popula para cada página; dados específicos de rota pertencem a tipos específicos de rota
App.PageState tipa o estado passado para pushState e replaceState para roteamento superficial; todos os campos devem ser opcionais
Sempre inclua export {} no final do arquivo ou o augmentation falhará silenciosamente
Use expressões de tipo import() para referenciar definições de tipo compartilhadas em vez de duplicá-las inline

Leitura Adicional

SvelteKit: Types — App namespace — Referência oficial para todas as cinco interfaces no namespace App
SvelteKit: Hooks — Como handle e handleError interagem com App.Locals e App.Error
SvelteKit: Shallow routing — pushState, replaceState e App.PageState na prática
SvelteKit: Adapters — Como diferentes adapters populam event.platform
TypeScript: Declaration Merging — O mecanismo TypeScript subjacente que faz app.d.ts funcionar
@cloudflare/workers-types — Definições de tipo para APIs do Cloudflare Workers referenciadas em App.Platform