Seguridad de Tipos en SvelteKit

Una de las características más poderosas de SvelteKit es su generación automática de tipos. Si estás usando TypeScript, SvelteKit garantiza que los datos que retornas desde tu función load son exactamente lo que tu componente recibe — con IntelliSense completo y verificación de errores en tiempo de compilación.

La razón por la que esto es valioso en la práctica: sin tipos generados, cambiar la forma de retorno de una función load es silencioso. Renombras un campo, y la plantilla del componente sigue referenciando el nombre antiguo. Nada se queja en tiempo de compilación. Envías el bug a producción y aparece como un error en tiempo de ejecución cuando un usuario visita esa página.

Con los tipos generados de SvelteKit, renombrar un campo en una función load resalta inmediatamente cada componente que referencia el nombre antiguo. El sistema de tipos se convierte en un asistente de refactorización — haces un cambio y sigues las líneas rojas hasta que todo es consistente de nuevo.

La seguridad de tipos no se trata solo de atrapar bugs — se trata de la confianza del desarrollador. Cuando refactorizas una función load, TypeScript te mostrará instantáneamente cada componente que necesita actualizarse. Esta es la diferencia entre "espero no haber roto nada" y "sé exactamente qué cambié."

La Magia de `$types`

Cuando ejecutas tu servidor de desarrollo (npm run dev), SvelteKit observa tus archivos de ruta. Cada vez que guardas un +page.js, +page.server.js, o un archivo de layout, analiza lo que estás retornando y genera definiciones de tipos automáticamente.

Accedes a estos tipos generados desde un módulo virtual especial: ./$types.

// src/routes/blog/+page.ts
import type { PageLoad } from './$types' // ← Generated by SvelteKit

export const load: PageLoad = async ({ params }) => {
	return {
		title: 'Hello',
		count: 42
	}
}

Por Qué Esto Captura Bugs Reales

Aquí hay un escenario concreto. Tienes una página de blog funcionando:

// +page.ts
export const load: PageLoad = async () => {
	return { posts: await fetchPosts() }
}

<!-- +page.svelte -->
<script lang="ts">
	let { data }: PageProps = $props()
</script>

<h1>{data.posts.length} posts</h1>

Ahora refactorizas y renombras el campo:

// +page.ts — renamed 'posts' to 'articles'
export const load: PageLoad = async () => {
	return { articles: await fetchPosts() }
}

Sin tipos, esto compila bien. El componente falla silenciosamente en tiempo de ejecución — data.posts ahora es undefined, y tus usuarios ven un error. Con los tipos generados de SvelteKit, tu editor muestra inmediatamente:

<h1>{data.posts.length} posts</h1>
<!--        ^^^^^ Property 'posts' does not exist on type '{ articles: Post[] }' -->

Encuentras el error en segundos, antes de que se envíe a producción. Esta es la propuesta de valor central: los tipos hacen que la refactorización sea segura.

Cómo Funciona

Paso 1: Tipear tu Función Load

El tipo PageLoad te da autocompletado completo para todos los parámetros disponibles, incluyendo la forma exacta de params inferida desde los nombres de tus carpetas:

// src/routes/blog/[slug]/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params, fetch, url }) => {
	// TypeScript knows:
	// - params.slug exists (from the [slug] folder name)
	// - fetch is the special SvelteKit fetch
	// - url is a URL object

	const response = await fetch(`/api/posts/${params.slug}`)

	return {
		post: await response.json(),
		relatedPosts: []
	}
}

Paso 2: Tipear tu Componente

El tipo PageProps sabe exactamente lo que retorna tu función load:

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

	let { data }: PageProps = $props()

	// TypeScript knows:
	// - data.post exists
	// - data.relatedPosts exists
	// - data.post is the return type from your API
</script>

<h1>{data.post.title}</h1>

El Flujo de Extremo a Extremo

flowchart
    A["+page.ts returns { title, posts }"] --> B["SvelteKit generates types"]
    B --> C["PageProps knows data.title, data.posts"]
    C --> D["Component gets autocomplete"]

    style A fill:#fff3e0, color:#000
    style B fill:#e1f5fe, color:#000
    style C fill:#f3e5f5, color:#000
    style D fill:#e8f5e9, color:#000

Si cambias tu función load:

// Before
return { title: 'Hello', posts: [] }

// After - removed 'title'
return { posts: [] }

Tu componente muestra inmediatamente un error:

<h1>{data.title}</h1>
<!--        ^^^^^ Property 'title' does not exist -->

¡Detectas los bugs antes de ejecutar el código!

Este ciclo de retroalimentación instantánea es por qué TypeScript brilla en SvelteKit. Cambia un tipo en un lugar, ve todo el código afectado resaltado inmediatamente.

Tipos Disponibles

Tipos de Página

// src/routes/blog/+page.ts
import type { PageLoad } from './$types'

// src/routes/blog/+page.server.ts
import type { PageServerLoad } from './$types'

// src/routes/blog/+page.svelte
import type { PageProps } from './$types'

Tipos de Layout

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

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

// src/routes/+layout.svelte
import type { LayoutProps } from './$types'

Tipos de Endpoint del Servidor

// src/routes/api/posts/+server.ts
import type { RequestHandler } from './$types'

export const GET: RequestHandler = async ({ params, url }) => {
	// ...
}

Los Parámetros de Ruta Están Tipados

SvelteKit infiere los tipos de parámetros desde la estructura de tus carpetas:

src/routes/blog/[slug]/+page.ts
              ^^^^^^
              params.slug: string

src/routes/users/[id]/posts/[postId]/+page.ts
                ^^^^        ^^^^^^^^
                params.id: string
                params.postId: string

// src/routes/users/[id]/posts/[postId]/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ params }) => {
	// TypeScript knows both params exist
	const userId = params.id // Correct - string
	const postId = params.postId // Correct - string
	const other = params.other // Error: Property 'other' does not exist
}

Los Datos del Padre Están Tipados

Al acceder a datos del padre, TypeScript sabe qué está disponible:

// src/routes/+layout.server.ts
export const load = async () => {
	return {
		user: { name: 'John', email: 'john@example.com' }
	}
}

// src/routes/dashboard/+page.ts
import type { PageLoad } from './$types'

export const load: PageLoad = async ({ parent }) => {
	const parentData = await parent()

	// TypeScript knows parentData.user exists!
	console.log(parentData.user.name)

	return {
		dashboardData: []
	}
}

Tipos de Acciones de Formulario

Las acciones de formulario también obtienen seguridad de tipos completa:

// src/routes/login/+page.server.ts
import type { Actions, PageServerLoad } from './$types'
import { fail } from '@sveltejs/kit'

export const load: PageServerLoad = async () => {
	return { message: 'Please log in' }
}

export const actions: Actions = {
	default: async ({ request }) => {
		const data = await request.formData()
		const email = data.get('email')

		if (!email) {
			return fail(400, {
				error: 'Email is required',
				email: '' // Return for form repopulation
			})
		}

		return { success: true }
	}
}

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

	let { data, form }: PageProps = $props()

	// TypeScript knows:
	// - data.message: string
	// - form?.error: string | undefined
	// - form?.success: boolean | undefined
</script>

{#if form?.error}
	<p class="error">{form.error}</p>
{/if}

{#if form?.success}
	<p class="success">Logged in!</p>
{/if}

El Directorio `.svelte-kit`

SvelteKit genera tipos en un directorio oculto .svelte-kit/types. No necesitas revisar estos archivos, pero entender que existen ayuda a explicar la magia:

.svelte-kit/
└── types/
    └── src/
        └── routes/
            ├── $types.d.ts           ← Root route types
            ├── blog/
            │   ├── $types.d.ts       ← /blog types
            │   └── [slug]/
            │       └── $types.d.ts   ← /blog/[slug] types

Estos se generan automáticamente y deberían estar en tu .gitignore.

Configuración de TypeScript

El tsconfig.json de SvelteKit está preconfigurado para entender $types:

{
	"extends": "./.svelte-kit/tsconfig.json",
	"compilerOptions": {
		"strict": true
	}
}

La configuración extendida incluye alias de rutas que hacen que ./$types funcione.

Patrones Comunes

Tipado de Respuestas de API

// src/lib/types.ts
export interface Post {
	id: string
	title: string
	content: string
	createdAt: string
}

// src/routes/blog/+page.ts
import type { PageLoad } from './$types'
import type { Post } from '$lib/types'

export const load: PageLoad = async ({ fetch }) => {
	const response = await fetch('/api/posts')
	const posts: Post[] = await response.json()

	return { posts }
}

Tipos Compartidos Entre Rutas

// src/lib/types.ts
export interface User {
	id: string
	name: string
	email: string
}

export interface LayoutData {
	user: User | null
}

Type Guards para Manejo de Errores

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

	let { data }: PageProps = $props()

	// Type guard for optional data
	function hasPost(d: typeof data): d is typeof data & { post: NonNullable<typeof data.post> } {
		return d.post !== null
	}
</script>

{#if hasPost(data)}
	<h1>{data.post.title}</h1>
{:else}
	<p>No post found</p>
{/if}

Solución de Problemas

¿Los Tipos No se Actualizan?

Asegúrate de que tu servidor de desarrollo esté corriendo (pnpm dev)
Intenta reiniciar el servidor de desarrollo
Ejecuta pnpm check para regenerar los tipos

¿Errores de Importación?

Asegúrate de importar desde ./$types, no desde $types:

// AVOID
import type { PageLoad } from '$types'

// PREFERRED
import type { PageLoad } from './$types'

¿Líneas Rojas en Archivos Nuevos?

Después de crear una nueva ruta, guarda el archivo y espera un momento para que se generen los tipos. A veces necesitas cerrar y volver a abrir el archivo en tu editor.

Conclusión

La generación automática de tipos de SvelteKit transforma TypeScript de algo agradable de tener en un acelerador fundamental del desarrollo. Al analizar tus archivos de rutas y generar tipos comprehensivos, elimina toda una categoría de bugs relacionados con incompatibilidades de props, tipos de parámetros incorrectos y violaciones de contratos de API.

Los tipos PageData, PageServerData y LayoutData fluyen automáticamente desde las funciones de carga hacia los componentes sin necesidad de definiciones de tipos manuales ni aserciones de tipos propensas a errores.

Dominar la seguridad de tipos en SvelteKit significa adoptar la convención ./$types, entender cómo funciona el estrechamiento de tipos con uniones discriminadas, y aprovechar los tipos generados para formularios y acciones. Cuando los tipos fluyen automáticamente del servidor al cliente, de las funciones de carga a los componentes, y de los formularios a los manejadores de acciones, construyes aplicaciones donde clases enteras de errores en tiempo de ejecución se convierten en advertencias en tiempo de compilación.

Esto no se trata solo de detectar bugs — se trata de construir con confianza, refactorizar sin miedo, y dejar que el sistema de tipos guíe el desarrollo.

Puntos Clave

SvelteKit auto-genera tipos a partir de los archivos de rutas en .svelte-kit/types — impórtalos mediante ./$types para obtener parámetros de funciones de carga y props de componentes con seguridad de tipos
Los tipos PageProps fluyen automáticamente desde los valores de retorno de las funciones de carga hacia las props del componente: let { data }: PageProps = $props() en Svelte 5 te da seguridad de tipos completa basada en lo que retorna tu función de carga
Las uniones discriminadas habilitan el estrechamiento de tipos — usa type guards para diferenciar entre PageData y PageServerData según condiciones en tiempo de ejecución
Las acciones de formulario se tipan mediante ActionData — los valores de retorno de las acciones de formulario se tipan automáticamente en la prop form y en page.form
El operador satisfies valida sin ampliar — usa satisfies PageLoad o satisfies PageServerLoad para detectar errores preservando los tipos de retorno inferidos
Ejecuta el comando sync tras cambios en archivos — npm run dev o svelte-kit sync regenera los tipos cuando agregas o modificas archivos de rutas
Los tipos generados incluyen helpers de acciones — el tipo Actions de ./$types provee autocompletado y validación para las exportaciones de acciones de formulario
TypeScript detecta errores de enrutamiento en tiempo de compilación — parámetros incorrectos, formas de datos incompatibles y respuestas de acciones inválidas se detectan antes del despliegue

Ver También

Documentación Oficial de SvelteKit - Seguridad de Tipos
Tipos Generados - Entendiendo las importaciones de ./$types
Acciones de Formulario - Manejadores de acciones tipados
TypeScript satisfies - Validación sin ampliación de tipos
Uniones Discriminadas - Patrones de estrechamiento de tipos