El Archivo Ignorado que Tipifica Toda tu App

Todo proyecto SvelteKit generado con soporte para TypeScript contiene un archivo llamado src/app.d.ts. Por defecto es pequeño, fácil de ignorar y casi completamente inexplicado en la mayoría de los tutoriales. Quizás lo abriste una vez, viste dos interfaces vacías y lo cerraste sin pensarlo dos veces.

Eso sería un error.

app.d.ts es el archivo donde le dices a TypeScript qué es fundamentalmente tu aplicación SvelteKit en tiempo de ejecución. Define la forma de los datos que fluyen a través de tus hooks de servidor, de tus funciones load, de tus acciones de formulario y hacia tus componentes. Sin él, TypeScript no tiene idea de qué vive en event.locals, qué forma tienen tus errores o qué APIs de plataforma están disponibles en el servidor. Con él correctamente completado, toda tu aplicación obtiene una seguridad de tipos coherente de extremo a extremo que sigue los datos desde el momento en que ingresan a una solicitud hasta el momento en que se renderizan en el navegador.

Este artículo cubre todo sobre app.d.ts: por qué SvelteKit necesita un archivo de declaración global dedicado en primer lugar, qué significa y controla cada una de sus interfaces, cómo construirlas correctamente para aplicaciones de producción reales, y los patrones que escalan desde un proyecto personal simple hasta un SaaS multi-tenant con múltiples destinos de despliegue.

Por Qué Existe un Archivo de Declaración Global Dedicado

Para entender por qué existe app.d.ts, necesitas comprender la arquitectura de SvelteKit. SvelteKit no es una librería en tiempo de ejecución que tú llamas. Es un framework que llama a tu código. Tú escribes +page.server.ts, y SvelteKit llama a su función load con un argumento LoadEvent. Tú escribes src/hooks.server.ts, y SvelteKit llama a su función handle con un RequestEvent.

Los tipos para esos eventos — LoadEvent, RequestEvent, PageServerLoad, y otros — son generados por el propio sistema de tipos de SvelteKit y dependen de lo que tu aplicación ponga en ellos.

El objeto event.locals, por ejemplo, existe como un contenedor completamente abierto. SvelteKit lo crea para cada solicitud, lo pasa a través de tus hooks y lo hace disponible en cada función load y acción de formulario. Pero SvelteKit en sí no tiene idea de qué pones ahí. Podrías poblarlo con un objeto user de la validación de sesión, un registro featureFlags de un servicio de configuración, un objeto tenant de la resolución de subdominio, o todo lo anterior.

TypeScript no puede inferir nada de eso. Necesita que se lo indiques.

SvelteKit resuelve esto mediante un mecanismo llamado module augmentation (aumento de módulos). El framework incluye interfaces internas como stubs vacíos dentro de sus propias definiciones de tipos. Tú completas esos stubs aumentando el namespace App dentro de src/app.d.ts.

Un stub es una definición de tipo placeholder que no tiene propiedades ni métodos reales. Los tipos internos de SvelteKit para `event.locals`, `event.platform`, y otros son stubs hasta que los aumentas en `app.d.ts`. Este diseño permite que SvelteKit sea flexible y agnóstico al framework mientras te da el poder de definir los contratos de datos específicos de tu aplicación.

Cuando TypeScript compila tu proyecto, fusiona tus declaraciones con las de SvelteKit, y de repente cada event.locals en cada archivo de todo tu proyecto lleva el tipo que declaraste. Sin importaciones, sin aserciones de tipo manuales, sin casts as User dispersos por todo tu código.

Ese es el poder de app.d.ts: es una declaración del contrato en tiempo de ejecución que tu aplicación mantiene, y TypeScript lo usa para verificar ese contrato en todas partes de forma automática.

El diagrama anterior muestra la relación con claridad. Declaras una vez en app.d.ts, el sistema de tipos de SvelteKit lo recoge, y se propaga a todos lados donde el framework pasa esas estructuras a tu código.

Anatomía del Archivo por Defecto

Un proyecto SvelteKit recién creado te da esto:

// 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 del namespace App, envueltas en un bloque declare global. El export {} al final no es decorativo; hace que TypeScript trate esto como un módulo en lugar de un script, lo cual es necesario para que declare global funcione correctamente. Si lo eliminas, el aumento se rompe silenciosamente.

Cada una de esas cinco interfaces corresponde a una parte específica del modelo de datos en tiempo de ejecución de SvelteKit. Repasémoslas una por una, de la más utilizada a la más especializada.

App.Locals: El Portador de Datos con Alcance por Solicitud

App.Locals es la más importante de las cinco interfaces para la mayoría de las aplicaciones. Tipifica la propiedad locals que vive en RequestEvent, el objeto que tu hook handle recibe por cada solicitud entrante.

El objeto locals es la respuesta de SvelteKit a la pregunta: "¿cómo paso datos del lado del servidor a mis funciones load sin obtenerlos dos veces?" Autentificas al usuario una vez en tu hook handle, adjuntas el resultado a locals, y cada +page.server.ts y +layout.server.ts subsecuente puede leerlo directamente desde event.locals sin hacer otra llamada a la base de datos o API.

Aquí está cómo luce una declaración realista de App.Locals para una aplicación con autenticación basada en sesiones:

// 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 {}

Esta forma inline está bien para comenzar y hace que la estructura sea inmediatamente visible. En la práctica, una vez que tus tipos User y Session existen en $lib/types.ts, refiérelos con expresiones de tipo import() en su lugar — de lo contrario terminas manteniendo la misma forma en dos 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 {}

La sección de Errores Comunes al final de este artículo cubre este patrón con más detalle.

Con esto establecido, el hook handle en src/hooks.server.ts puede poblar esos campos con verificación 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)
}

TypeScript ahora verifica cada asignación. Si intentas establecer event.locals.user = { id: 123 } (número en lugar de string), el compilador lo detecta. Si intentas leer event.locals.permissions (un campo que nunca declaraste), el compilador lo rechaza. Todo el pipeline de locals se vuelve con seguridad de tipos sin una sola importación o cast.

En tus funciones load, leer desde locals es igualmente limpio:

// 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
	}
}

El narrowing después de la llamada a redirect es un beneficio sutil pero importante. Debido a que redirect lanza (nunca retorna), TypeScript correctamente estrecha locals.user de User | null a User después del guard. Obtienes tipos precisos sin aserciones manuales.

App.PageData: Tipificando el Objeto de Datos en tus Componentes

App.PageData se escribe manualmente con menos frecuencia, porque SvelteKit genera el tipo PageData para cada ruta automáticamente a partir del tipo de retorno de su función load. Cuando miras el archivo ./$types generado en cualquier directorio de ruta, encontrarás un tipo PageData que refleja exactamente lo que tu load retornó.

Sin embargo, App.PageData sirve para un propósito diferente: define una línea de base para todo el sitio de datos que siempre está presente en page.data, independientemente de qué ruta esté activa. Esto es particularmente útil cuando la función load de tu layout raíz siempre provee ciertos campos.

Considera una aplicación donde el layout raíz siempre carga el usuario actual y la configuración de navegación global:

// 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 {}

Con App.PageData declarado de esta manera, page.data en cualquier componente de tu app lleva esos campos con tipos correctos, incluso sin 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}

La idea clave es que App.PageData representa la intersección de lo que todas tus páginas comparten. No reemplaza los tipos por ruta; los aumenta. El tipo PageData de una ruta específica (de ./$types) incluirá tanto los campos específicos de la ruta como todo lo declarado en App.PageData.

No abuses de esto. App.PageData solo debe contener datos que genuinamente aparecen en cada página. Si agregas un campo aquí que tu layout raíz no popula realmente, has creado una mentira de tipos que confundirá a cualquiera que lea el código después.

App.Error: Dando Forma a tus Payloads de Error

Por defecto, el helper error() de SvelteKit acepta un código de estado y un string de mensaje. El objeto de error resultante tiene la forma { message: string }. Esto es suficiente para aplicaciones simples, pero los sistemas de producción a menudo necesitan información de error más rica: códigos de error para el manejo del lado del cliente, IDs de correlación para el rastreo de logs, detalles estructurados para mensajes dirigidos al usuario en múltiples idiomas.

App.Error te permite declarar la forma de cada objeto de error que SvelteKit produce y que los archivos +error.svelte reciben. El único requisito es que la interfaz debe incluir message: string, porque el framework mismo establece ese campo en varios lugares.

Una interfaz de error bien diseñada para una aplicación respaldada por una API de producción:

// 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 {}

Cuando lanzas errores en tus funciones load o rutas de servidor, pasas un objeto que coincide con esta 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 }
}

El componente +error.svelte en cualquier nivel puede entonces acceder a estos campos a través 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>

Una nota sutil: también necesitas implementar el hook handleError en src/hooks.server.ts si quieres que los errores no capturados (aquellos no lanzados explícitamente con error()) se ajusten a tu forma App.Error. Sin él, los errores inesperados solo tendrán { message: string } y ninguno de tus campos adicionales:

// 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
	}
}

El hook handleError es el adaptador entre tus errores de servidor no controlados y la forma tipada App.Error que prometiste entregar. Trátalo como un complemento requerido para cualquier definición de App.Error no trivial.

App.Platform: Apuntando a Entornos de Despliegue Específicos

App.Platform es la más específica del entorno de las cinco interfaces. Tipifica el objeto event.platform, que los adaptadores de SvelteKit pueblan con APIs y contexto específicos de la plataforma cuando tu aplicación se ejecuta en un destino de despliegue particular.

Si despliegas en Node.js con adapter-node, event.platform es esencialmente undefined porque Node.js mismo provee todas las APIs estándar que necesitas. Pero si despliegas en Cloudflare Workers o Cloudflare Pages, el objeto de plataforma lleva bindings a la infraestructura de Cloudflare: namespaces KV, buckets R2, bases de datos D1, Durable Objects, variables de entorno y el contexto de ejecución para waitUntil.

Sin App.Platform declarado, acceder a event.platform te da App.Platform | undefined, y App.Platform es una interfaz vacía, por lo que cada acceso a una propiedad es un error de tipo.

Aquí hay una declaración realista para 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 {}

Ten en cuenta que KVNamespace, R2Bucket, D1Database, CacheStorage e IncomingRequestCfProperties son tipos que provienen de @cloudflare/workers-types. Instalas ese paquete como dependencia de desarrollo y lo referencias aquí. Los tipos no necesitan ser importados con una declaración import porque el propio paquete workers-types los declara como globales.

Con esto declarado, tu código del lado del servidor obtiene seguridad de tipos completa para las APIs de 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 siempre es nullable porque tu código podría ejecutarse en una plataforma que no lo popula (por ejemplo, durante vite dev). Siempre protege con if (event.platform) antes de acceder a APIs específicas de la plataforma. El sistema de tipos lo aplica correctamente: event.platform está tipado como App.Platform | undefined.

Si apuntas a múltiples plataformas o quieres soportar tanto despliegues en Cloudflare como en Node desde el mismo código base, puedes usar un enfoque de unión:

// 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 {}

Este patrón crea una interfaz de plataforma donde todas las propiedades específicas de la plataforma son opcionales. Tu código entonces usa verificaciones en tiempo de ejecución ('env' in event.platform && 'SESSIONS_KV' in event.platform.env) además del guard de null para ramificarse apropiadamente. Es un enfoque pragmático cuando una separación limpia de plataformas no es posible.

App.PageState: Shallow Routing Tipado

App.PageState es la más nueva de las cinco interfaces y la menos familiar para la mayoría de los desarrolladores. Tipifica la propiedad state utilizada con la API de shallow routing de SvelteKit.

El shallow routing te permite actualizar la URL y agregar entradas al historial del navegador sin desencadenar una navegación completa ni volver a ejecutar las funciones load. El caso de uso canónico es una vista de detalle que se superpone a la página actual — como hacer clic en una foto de una galería para abrir un visor modal — donde la URL debe actualizarse (para que compartir funcione) pero la página subyacente no debe recargarse.

Empujas el estado shallow usando la función 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
	})
}

El segundo argumento de pushState es el objeto de estado. Sin App.PageState, TypeScript acepta esto como App.PageState & Record<string, unknown>, que es funcionalmente sin tipo. Con él declarado, el objeto de estado está completamente tipado:

// src/app.d.ts

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

export {}

Leer el estado de vuelta en un componente utiliza 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 los campos en App.PageState deben ser opcionales, porque el estado de página comienza vacío cuando el usuario carga una URL directamente por primera vez. Nunca se puede garantizar qué estado existe en la entrada del historial en la que el usuario aterrizó.

Composición de un app.d.ts para producción

Todo lo cubierto hasta ahora se une en un solo archivo para una aplicación real. Así es como se ve un app.d.ts completo y listo para producción para un SaaS multi-tenant desplegado en 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 archivo tiene aproximadamente 60 líneas. Describe el contrato en tiempo de ejecución de toda una aplicación SaaS: quién puede estar autenticado, qué contexto de tenant fluye a través de cada solicitud, qué APIs de plataforma están disponibles, cómo se estructuran los errores, qué estado de superposición a nivel de página existe. Cualquier desarrollador que se una al proyecto puede leer este archivo y comprender el modelo de datos fundamental de la aplicación en menos de cinco minutos.

El flujo de datos, de extremo a extremo

Ayuda ver cómo los tipos declarados en app.d.ts se conectan a lo largo del ciclo de vida completo de la solicitud. El siguiente diagrama traza una única solicitud autenticada desde la llegada HTTP hasta el renderizado del componente:

Los tipos fluyen porque App.Locals se declara una vez y TypeScript lo hila automáticamente a través del tipo de event en cada hook, función load y acción de servidor en todo tu código base.

Errores comunes y anti-patrones

Olvidar el `export {}` al 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 {}

Sin export {}, TypeScript trata el archivo como un script global en lugar de un módulo. declare global dentro de un contexto de script no funciona como se espera, y la augmentación falla silenciosamente. Tu event.locals.user tendrá el tipo any o generará errores, y la causa será difícil de rastrear. Incluye siempre export {}.

Usar tipos en línea en lugar de importar definiciones compartidas

Cuando declaras información del tipo User directamente en app.d.ts, creas un riesgo de mantenimiento. Si tu tipo User cambia (por ejemplo, agregas un campo displayName), tienes que recordar actualizarlo en dos lugares: la fuente de verdad (p. ej., $lib/types/user.ts) y la declaración en línea en app.d.ts. Esta duplicación es propensa a errores y puede provocar incompatibilidades de tipos que TypeScript no puede 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
		}
	}
}

Poblar campos de Locals sin declararlos

// 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 saltarse el tipado de locals es un atajo común que anula el propósito completo de App.Locals. El error de TypeScript que indica que una propiedad no existe en event.locals es una señal de que necesitas actualizar app.d.ts, no una razón para hacer un cast a any.

Poner datos específicos de una ruta en 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 estos campos existen en cada página. Si articleList solo proviene del loader de la ruta /articles, será undefined en todos los demás lugares, creando un contrato de tipo falso que causará errores en tiempo de ejecución. Mantén App.PageData liviano y genuinamente universal.

Consideraciones de rendimiento y escalabilidad

app.d.ts es una construcción en tiempo de compilación. Tiene cero costo en tiempo de ejecución. TypeScript elimina toda la información de tipos durante la compilación, por lo que las interfaces que declaras aquí no producen ningún resultado en JavaScript.

Las consideraciones de rendimiento son, por lo tanto, sobre el diseño más que sobre la ejecución. Una interfaz Locals con muchos campos profundamente anidados fomenta un patrón donde el hook handle realiza una gran cantidad de trabajo en cada solicitud, incluso para rutas que no necesitan ninguno de esos datos. Una solicitud a /favicon.ico no debería desencadenar una secuencia completa de validación de sesión y resolución de tenant.

Estructurar tu hook handle para que sea condicional según la ruta de la solicitud es una respuesta práctica a esto, y app.d.ts lo soporta bien mediante campos opcionales:

// 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
}

Hacer que user y tenant sean anulables (en lugar de tipos no nulos requeridos) señala en el sistema de tipos que no cada solicitud los popula. Las funciones load que requieren autenticación verifican si son nulos y redirigen o generan un error en consecuencia. Esto es un modelado preciso del comportamiento de tu aplicación.

Para equipos grandes que trabajan en el mismo código base, app.d.ts se convierte en un punto de coordinación. Los cambios en App.Locals afectan a todas las funciones load y hooks en todo el proyecto. Eliminar un campo o cambiar su tipo es una refactorización que TypeScript te guiará con errores de compilación en cada sitio de uso, que es exactamente la herramienta adecuada para el trabajo. Trata los cambios en app.d.ts con el mismo cuidado que darías a un contrato de API compartido.

Cuándo NO depender únicamente de app.d.ts

app.d.ts gestiona el tipado en el límite del framework SvelteKit, pero no reemplaza a un sistema de tipos bien estructurado para el modelo de dominio propio de tu aplicación. No pongas todo tu sistema de tipos de dominio en app.d.ts. Las interfaces aquí deben ser referencias ligeras a tipos que viven en $lib/types, no la fuente de verdad para esos tipos.

Del mismo modo, app.d.ts no proporciona validación en tiempo de ejecución. Si tu hook de validación de sesión recibe una respuesta JSON malformada de una API de autenticación y la asignas directamente a event.locals.user, TypeScript no detectará la discrepancia en tiempo de ejecución. Para datos que cruzan un límite de red, utiliza una biblioteca de validación de esquemas (como Zod o Valibot) para validar antes de asignar a locals. La declaración de tipo en app.d.ts entonces documenta el contrato post-validación, no la esperanza pre-validación.

Si estás construyendo una biblioteca o un paquete SvelteKit destinado a usarse dentro de otros proyectos, no puedes augmentar el namespace App tú mismo; ese privilegio pertenece a la aplicación que lo consume. Los tipos específicos de la biblioteca deben usar otros mecanismos (exportaciones tipadas, wrappers genéricos) en lugar de la augmentación de app.d.ts.

Conclusión

app.d.ts es el archivo más pequeño en un proyecto SvelteKit y uno de los más trascendentes. Es el archivo donde describes, en el lenguaje de TypeScript, el contrato en tiempo de ejecución que tu aplicación mantiene. Declara App.Locals y toda tu pipeline de solicitudes obtiene seguridad de tipos coherente e integrada con el framework. Declara App.Error y el manejo de errores se vuelve consistente y confiable desde el hook de servidor hasta el componente de error. Declara App.Platform y las APIs de tu destino de despliegue se convierten en ciudadanos de primera clase de TypeScript.

La inversión requerida es mínima: un puñado de declaraciones de interfaz que escribes una vez y actualizas a medida que tu aplicación evoluciona. El retorno es sustancial: un código base donde TypeScript comprende el flujo completo de datos desde la solicitud HTTP hasta el componente renderizado, donde los errores de tipo detectan violaciones del contrato antes de que lleguen a producción, y donde los nuevos colaboradores pueden comprender el modelo de datos en tiempo de ejecución de la aplicación leyendo un único archivo.

Puntos clave

app.d.ts usa la augmentación de módulos de TypeScript para inyectar tipos en las interfaces del framework SvelteKit, convirtiéndolo en la única fuente de verdad para el contrato de tipos en tiempo de ejecución de tu aplicación.

Puntos clave:

App.Locals tipifica event.locals en todos los hooks, funciones load y acciones de servidor sin ninguna importación ni cast manual
App.Error define la forma de todos los objetos de error; combínalo con handleError en hooks.server.ts para garantizar que los errores no capturados se ajusten a la misma forma
App.Platform hace que las APIs del destino de despliegue estén completamente tipadas; siempre protege con if (event.platform) ya que puede ser undefined en desarrollo
App.PageData solo debe contener campos que el layout raíz genuinamente popula para cada página; los datos específicos de una ruta pertenecen a los tipos específicos de esa ruta
App.PageState tipifica el estado pasado a pushState y replaceState para el enrutamiento superficial; todos los campos deben ser opcionales
Incluye siempre export {} al final del archivo o la augmentación fallará silenciosamente
Usa expresiones de tipo import() para referenciar definiciones de tipos compartidas en lugar de duplicarlas en línea

Lectura adicional

SvelteKit: Types — App namespace — Referencia oficial de las cinco interfaces en el namespace App
SvelteKit: Hooks — Cómo handle y handleError interactúan con App.Locals y App.Error
SvelteKit: Shallow routing — pushState, replaceState y App.PageState en la práctica
SvelteKit: Adapters — Cómo los diferentes adaptadores populan event.platform
TypeScript: Declaration Merging — El mecanismo subyacente de TypeScript que hace funcionar app.d.ts
@cloudflare/workers-types — Definiciones de tipos para las APIs de Cloudflare Workers referenciadas en App.Platform