Fundamentos

Bienvenido a la serie de Routing de SvelteKit—una guía exhaustiva al estilo de documentación que va más allá de los conceptos básicos. Tanto si vienes de React Router, Vue Router, o estás construyendo tu primera aplicación web moderna, esta serie te dará el entendimiento profundo que distingue a los desarrolladores junior de los ingenieros senior.

A lo largo de esta serie, aprenderás sobre rutas, páginas, layouts, carga de datos, manejo de errores y más. Cada artículo profundiza en un archivo o concepto específico del sistema de enrutamiento de SvelteKit, explicando no solo el "cómo" sino el crucial "por qué" detrás de cada decisión de diseño.

Explorarás:

Páginas Dinámicas — Construye páginas que respondan a parámetros de URL
Páginas del Servidor — Carga datos de forma segura en el servidor
Endpoints de API — Construye un backend completo dentro de tu aplicación SvelteKit
Layouts — Comparte UI y datos entre múltiples rutas

Al final de este artículo, entenderás el "por qué" filosófico detrás de las decisiones de enrutamiento de SvelteKit y tendrás un modelo mental claro de cómo todo encaja.

Entender por qué un framework toma ciertas decisiones es más valioso que memorizar cómo usarlo. Cuando comprendes la filosofía subyacente, puedes predecir el comportamiento, depurar más rápido y tomar mejores decisiones arquitectónicas.

¿Qué es el Enrutamiento Basado en el Sistema de Archivos?

Antes de escribir cualquier código, entendamos por qué SvelteKit eligió el enrutamiento basado en el sistema de archivos. Esto no es solo un detalle técnico—es una filosofía que moldeará cómo piensas sobre toda tu aplicación.

El Enfoque Tradicional (Y Sus Problemas)

En muchos frameworks, defines las rutas en un archivo de configuración:

// Traditional routing configuration (NOT SvelteKit)
const routes = [
	{ path: '/', component: HomePage },
	{ path: '/about', component: AboutPage },
	{ path: '/blog', component: BlogPage },
	{ path: '/blog/:slug', component: BlogPostPage },
	{ path: '/contact', component: ContactPage }
]

Este enfoque tiene un problema fundamental: la separación de responsabilidades se convierte en separación del entendimiento. Las definiciones de tus rutas viven en un lugar, tus componentes viven en otro, y la lógica de carga de datos puede estar dispersa en múltiples archivos. Cuando necesitas modificar la página /about, debes:

Encontrar la configuración de rutas para entender qué componente se renderiza
Navegar a ese archivo de componente
Buscar cualquier lógica de carga de datos asociada
Esperar no haber pasado por alto ningún código relacionado del lado del servidor

La Filosofía de SvelteKit: Co-ubicación

SvelteKit elimina esta carga cognitiva a través de la co-ubicación—el principio de que el código relacionado debe vivir junto.

En SvelteKit, la estructura de carpetas ES el enrutador. Si quieres una ruta en /about, simplemente creas una carpeta llamada about. No necesitas registrar esta carpeta en ningún lugar; su mera existencia crea la ruta.

Cuando colocas un archivo +page.svelte dentro de esa carpeta (src/routes/about/+page.svelte), simultáneamente has:

Declarado una ruta que responde a /about (por el nombre de la carpeta).
Creado el componente que se renderiza para esa ruta (el archivo +page.svelte).
Establecido la ubicación para cualquier lógica de carga de datos (+page.js va justo al lado).
Definido dónde vive el código del servidor (+page.server.js también está ahí).

Esto no es solo conveniente—es transformador. En lugar de saltar entre un archivo de configuración de rutas, una carpeta de componentes y una carpeta de API, todo lo relacionado con la página "About" vive en un solo lugar. ¿Necesitas cambiar la página about? Ve a src/routes/about/. Todo lo que necesitas está ahí. Sin búsquedas, sin suposiciones.

El Directorio `src/routes`: El Mapa de Tu Aplicación

Toda aplicación SvelteKit tiene un directorio src/routes. Este directorio ES tu configuración de enrutamiento. Veamos cómo los directorios se mapean a URLs:

src/routes/                    →  /
src/routes/about/              →  /about
src/routes/blog/               →  /blog
src/routes/contact/            →  /contact
src/routes/products/           →  /products
src/routes/products/shoes/     →  /products/shoes

El patrón es elegantemente simple: cada directorio se convierte en un segmento de URL.

Rutas Dinámicas

¿Pero qué pasa si tienes cientos de publicaciones de blog? No querrás crear una carpeta para cada una. SvelteKit usa corchetes para crear parámetros de ruta dinámicos:

src/routes/blog/[slug]/+page.svelte     →  /blog/hello-world
                                        →  /blog/my-first-post
                                        →  /blog/anything-here

La carpeta [slug] coincide con cualquier valor, y ese valor queda disponible en tus funciones de carga y componentes.

Entendiendo los Patrones de Rutas Dinámicas

SvelteKit soporta varios patrones de rutas dinámicas, cada uno diseñado para casos de uso específicos:

Patrón	Ejemplo	Coincide con
`[slug]`	`/blog/[slug]`	`/blog/hello` (requerido)
`[[lang]]`	`/[[lang]]/about`	`/about` o `/en/about` (opcional)
`[...path]`	`/files/[...path]`	`/files/a/b/c` (rest/catch-all)
`[id=integer]`	`/posts/[id=integer]`	`/posts/123` (con validación)

Los parámetros requeridos [slug] son los más comunes—coinciden con cualquier segmento único. Una ruta como /blog/[slug] coincidirá con /blog/hello pero no con /blog o /blog/hello/world.

Los parámetros opcionales [[lang]] permiten que una sola ruta maneje múltiples patrones de URL. Por ejemplo, [[lang]]/about coincide tanto con /about como con /en/about. Esto es perfecto para internacionalización donde quieres un idioma predeterminado en la raíz y versiones localizadas bajo códigos de idioma. Exploraremos los parámetros opcionales en profundidad en un artículo dedicado más adelante en esta serie.

Los parámetros rest [...path] capturan todo lo que sigue a un punto determinado en la URL. Una ruta como /files/[...path] coincide con /files/a, /files/a/b y /files/a/b/c/d. El valor capturado se convierte en "a", "a/b" o "a/b/c/d" respectivamente. Son esenciales para construir exploradores de archivos, sitios de documentación, o cualquier funcionalidad donde la profundidad de la URL es desconocida. Los parámetros rest también permiten el manejo personalizado de errores 404 dentro de secciones específicas de tu aplicación—cubriremos este patrón en nuestro artículo de Enrutamiento Avanzado.

Los matchers [id=integer] agregan validación a los segmentos dinámicos. En lugar de aceptar cualquier valor, solo coinciden cuando el parámetro pasa una prueba que tú defines. Por ejemplo, [id=integer] solo coincide con IDs numéricos como /posts/123, no con /posts/hello. Los matchers se definen en tu directorio src/params y ayudan a crear rutas con tipo seguro. Exploraremos cómo crear matchers personalizados cuando cubramos los patrones de Enrutamiento Avanzado.

Cada uno de estos patrones tiene un propósito específico para construir una lógica de enrutamiento robusta. A medida que avances en esta serie, verás ejemplos prácticos de cuándo y por qué usar cada uno.

Prioridad de Coincidencia de Rutas

Cuando múltiples rutas podrían potencialmente coincidir con una URL, SvelteKit necesita decidir cuál usar. Entender este sistema de prioridad previene errores confusos y te ayuda a estructurar las rutas de manera efectiva.

La regla de oro: las rutas más específicas ganan. SvelteKit ordena las rutas de más específica a menos específica, luego las intenta en orden hasta que una coincide. Esto es lo que significa "específica":

Las rutas estáticas superan a las rutas dinámicas. /blog/about gana sobre /blog/[slug]
Las rutas con matchers superan a las rutas sin ellos. /posts/[id=integer] gana sobre /posts/[slug]
Los parámetros requeridos superan a los parámetros opcionales y rest. /[slug] gana sobre /[[optional]] o /[...rest]

Considera estas rutas:

src/routes/blog/latest/+page.svelte          ← Highest priority (static)
src/routes/blog/[slug=integer]/+page.svelte  ← Second (has matcher)
src/routes/blog/[slug]/+page.svelte          ← Third (dynamic, no matcher)
src/routes/blog/[[id]]/+page.svelte          ← Fourth (optional)
src/routes/[...catchall]/+page.svelte        ← Lowest priority (rest)

Cuando un usuario visita /blog/latest, SvelteKit intenta las rutas en orden y se detiene en la primera coincidencia—la ruta estática. Cuando visitan /blog/123, omite la ruta estática (no coincide con "latest"), luego coincide con la ruta validada por entero. Para /blog/hello-world, baja hasta la ruta [slug] simple.

Este ordenamiento ocurre automáticamente. No lo configuras, pero sí necesitas entenderlo al diseñar la estructura de tus rutas. Si estás obteniendo coincidencias inesperadas, verifica si una ruta más general está capturando las solicitudes antes de que lleguen a tu ruta prevista. Exploraremos los casos límite de coincidencia de rutas y estrategias de depuración en nuestro artículo de Enrutamiento Avanzado.

El Prefijo Especial `+`

Dentro de cualquier directorio de ruta, SvelteKit reconoce archivos especiales por su prefijo +. El + no fue elegido al azar — es un carácter que se ordena al principio de los listados de directorios en la mayoría de los exploradores de archivos, manteniendo los archivos de ruta agrupados visualmente y separados de los archivos que no son de ruta. Más importante aún, crea una convención inequívoca: todo lo que comienza con + le pertenece al enrutador de SvelteKit, todo lo que no tiene el prefijo es tuyo para organizar libremente.

Este diseño resuelve un problema real: en un enrutador basado en el sistema de archivos, es posible que quieras co-ubicar utilidades, componentes o archivos de prueba junto a tus rutas. Sin una convención clara, el enrutador tendría que prohibirlo (obligándote a separarlos) o usar heurísticas para adivinar qué archivos son rutas. El prefijo + hace que la distinción sea explícita y consistente.

Aquí hay un resumen de los archivos que encontrarás. Cada uno tiene un artículo dedicado en esta serie:

Archivo	Propósito	Entorno de Ejecución	Artículo
`+page.svelte`	Renderiza la UI de la página	Servidor (SSR) + Cliente	+page.svelte
`+page.js`	Carga de datos universal	Servidor + Cliente	+page.js
`+page.server.js`	Carga de datos solo en el servidor	Solo servidor	+page.server.js
`+layout.svelte`	Wrapper de layout compartido	Servidor (SSR) + Cliente	+layout.svelte
`+layout.js`	Carga de datos universal del layout	Servidor + Cliente	+layout.js
`+layout.server.js`	Carga de datos del layout solo en el servidor	Solo servidor	+layout.server.js
`+error.svelte`	UI del límite de error	Servidor (SSR) + Cliente	+error.svelte
`+server.js`	Manejadores de endpoints de API	Solo servidor	+server.js

Notarás dos archivos de carga de datos para cada nivel (+page.js y +page.server.js, +layout.js y +layout.server.js). Esta es una de las decisiones arquitectónicas más importantes de SvelteKit. Las variantes .server se ejecutan exclusivamente en el servidor y tienen acceso a bases de datos, claves de API privadas y cookies — ninguno de su código llega al navegador. Las variantes sin .server se ejecutan tanto en el servidor como en el navegador, lo que permite la navegación instantánea del lado del cliente (sin viaje de ida y vuelta al servidor al cambiar de página), pero significa que solo pueden usar código que funcione en ambos entornos. La elección entre ellos se reduce a: ¿requiere este dato capacidades exclusivas del servidor? Si es así, usa .server. Si los datos son públicos y seguros de calcular en el navegador, usa la versión universal.

Los archivos sin el prefijo + son ignorados por el enrutador de SvelteKit — puedes co-ubicar funciones auxiliares, componentes o utilidades justo al lado de tus rutas de forma segura.

Por ejemplo, esta estructura es perfectamente válida:

src/routes/blog/
├── +page.svelte         # Route file (SvelteKit recognizes this)
├── +page.js             # Route file (SvelteKit recognizes this)
├── BlogCard.svelte      # Component (ignored by router)
├── utils.js             # Helper functions (ignored by router)
└── formatDate.js        # Utility (ignored by router)

A SvelteKit solo le importan los archivos con el prefijo +. Todo lo demás es tuyo para organizar de la manera que tenga más sentido para tu proyecto. Esta co-ubicación de código relacionado es una de las características más poderosas de SvelteKit—tus componentes, utilidades y lógica de rutas pueden vivir juntos, haciendo que la refactorización y el mantenimiento sean mucho más fáciles.

Un Directorio de Ruta Típico

Para ver cómo estos archivos trabajan juntos, veamos una estructura de ruta típica:

src/routes/blog/
├── +page.svelte         # The UI users see
├── +page.ts             # Loads data for the page
├── +layout.svelte       # Wraps this and child pages
├── helpers.ts           # Ignored by router (no + prefix)
└── [slug]/
    ├── +page.svelte     # Individual blog post UI
    └── +page.server.ts  # Server-only data loading

Cuando un usuario visita /blog:

SvelteKit encuentra src/routes/blog/
Verifica si existe +page.js para cargar datos para la página
Renderiza +page.svelte dentro de +layout.svelte

Este es un ejemplo simplificado, pero el patrón es predecible y consistente. Todo está co-ubicado.

Entendiendo el Layout Raíz

El layout raíz en src/routes/+layout.svelte merece atención especial porque envuelve tu aplicación completa. Cada página, cada layout anidado, cada ruta se renderiza dentro de este layout raíz.

Si no creas un layout raíz, SvelteKit proporciona uno mínimo por defecto:

<script>
	let { children } = $props()
</script>

{@render children()}

Este valor predeterminado simplemente renderiza tus páginas sin ningún wrapper. Pero en la mayoría de las aplicaciones reales, querrás agregar tu propio layout raíz para incluir elementos de todo el sitio como navegación, pies de página, analytics o estilos globales.

El layout raíz también es especial en términos de manejo de errores. Si ocurre un error en la función de carga del propio layout raíz — no en una página, sino en el layout en sí — SvelteKit no puede renderizar el layout raíz para mostrar el error, porque el layout raíz es el que renderiza las páginas de error. En este caso, SvelteKit recurre a un archivo estático src/error.html. Esta es la única situación en la que SvelteKit omite toda la jerarquía de componentes y renderiza un archivo HTML sin procesar. Entender este caso límite importa para producción: mantén la función de carga de tu layout raíz mínima y robusta, porque un fallo ahí produce la experiencia de usuario más disruptiva posible.

Exploraremos las jerarquías de layouts y los límites de manejo de errores en detalle en la sección de Layouts de esta serie.

Cómo Se Resuelven las Rutas: El Panorama Completo

Entender cómo SvelteKit resuelve una URL en una página renderizada te ayuda a predecir el comportamiento y depurar problemas. Veamos qué sucede cuando un usuario visita /blog/hello-world:

Paso 1: Coincidencia de Ruta

SvelteKit examina tu directorio src/routes y encuentra la mejor coincidencia:

src/routes/blog/[slug]/+page.svelte  ← Matches!

El parámetro [slug] captura "hello-world" y lo pone disponible como params.slug.

Paso 2: Carga de Datos (De Arriba hacia Abajo)

Antes de renderizar cualquier cosa, SvelteKit ejecuta todas las funciones de carga en la jerarquía de layouts, comenzando desde la raíz:

1. src/routes/+layout.server.js           (if it exists)
2. src/routes/blog/+layout.server.js      (if it exists)
3. src/routes/blog/[slug]/+page.server.js (if it exists)

Cada función de carga recibe datos de las funciones de carga padre a través de parent(). Esto permite que las rutas hijas construyan sobre los datos cargados en niveles superiores. Las funciones de carga del servidor se ejecutan solo en el servidor y tienen acceso a bases de datos, variables de entorno y otros recursos exclusivos del servidor.

Paso 3: Renderizado de la Jerarquía (De Afuera hacia Adentro)

Una vez que todos los datos están cargados, SvelteKit renderiza la jerarquía de layouts desde el layout más externo hasta la página más interna:

src/routes/+layout.svelte
  └── wraps src/routes/blog/+layout.svelte
      └── wraps src/routes/blog/[slug]/+page.svelte

Cada layout recibe data de su función de carga correspondiente y children que contiene el siguiente nivel. El componente más interno es tu +page.svelte, que renderiza el contenido real de la página.

Paso 4: Hidratación (Del Servidor al Cliente)

En la carga inicial de la página, toda esta jerarquía se renderiza en el servidor (SSR) y se envía como HTML. Cuando se carga el JavaScript, Svelte "hidrata" la página—adjuntando listeners de eventos y haciéndola interactiva. En las navegaciones posteriores, SvelteKit solo ejecuta las funciones de carga del lado del cliente e intercambia la página sin una recarga completa.

Este proceso de resolución ocurre para cada ruta en tu aplicación. Entenderlo te ayuda a razonar sobre el flujo de datos, decidir dónde colocar las funciones de carga y estructurar tus layouts de manera efectiva. Profundizaremos en estrategias de carga de datos, composición de layouts y navegación del lado del cliente en artículos próximos.

El Modelo Mental

Piensa en tu directorio src/routes como un árbol:

src/routes/
├── +layout.svelte       (root - wraps everything)
├── +page.svelte         (home page)
├── about/
│   └── +page.svelte
└── blog/
    ├── +layout.svelte   (wraps blog pages)
    ├── +page.svelte     (blog index)
    └── [slug]/
        └── +page.svelte (individual posts)

Conclusión

El sistema de enrutamiento de SvelteKit representa un cambio fundamental en cómo pensamos sobre la construcción de aplicaciones web. Al hacer del sistema de archivos la fuente de verdad para la estructura de URLs de tu aplicación, elimina la desconexión entre rutas y código que afecta a las configuraciones tradicionales de enrutadores. Cada carpeta se convierte en un segmento de URL, cada +page.svelte se convierte en una ruta, y las relaciones entre layouts, páginas y archivos de datos emergen naturalmente de la estructura de directorios.

Este enfoque basado en el sistema de archivos no es solo una cuestión de conveniencia—se trata de crear aplicaciones que sean más fáciles de entender, más fáciles de mantener y más fáciles de escalar. Cuando las rutas se definen por la ubicación del archivo en lugar de por configuración, los nuevos desarrolladores pueden navegar tu base de código de forma intuitiva, la refactorización se convierte en una cuestión de mover archivos, y la relación entre la estructura de URLs y la organización del código permanece clara incluso cuando las aplicaciones crecen. Al dominar estos conceptos fundamentales, construyes el modelo mental necesario para aprovechar todo el poder de SvelteKit.

Conclusiones Clave

El enrutamiento basado en sistema de archivos usa la estructura de carpetas para definir segmentos de URL - src/routes/blog/[slug] crea el patrón de ruta /blog/:slug automáticamente
+page.svelte define rutas renderizables - las carpetas sin este archivo sirven como segmentos de URL pero no renderizan páginas por sí mismas
+layout.svelte envuelve las rutas descendientes creando una interfaz compartida que persiste entre navegaciones, con layouts anidados formando una jerarquía de componentes
Los archivos de datos proveen datos del servidor/cliente - +page.js (universal), +page.server.js (solo servidor), y los archivos de layout correspondientes cargan datos para sus componentes
Los segmentos dinámicos usan corchetes - [param] captura segmentos de URL como parámetros, [...rest] coincide con las rutas restantes, y [[optional]] hace que los segmentos sean opcionales
El layout raíz envuelve todo - src/routes/+layout.svelte provee la estructura HTML y la interfaz global para toda tu aplicación
La filosofía de convención sobre configuración elimina los archivos de configuración de rutas y hace explícita la relación entre URLs y código a través de la estructura de archivos
Los archivos de ruta co-ubicados habilitan la modularidad - páginas, layouts, carga de datos y endpoints de API conviven juntos, haciendo que las funcionalidades sean autocontenidas y fáciles de refactorizar

Ver También

Documentación Oficial de SvelteKit - Enrutamiento - La guía oficial del sistema de enrutamiento de SvelteKit y las convenciones de archivos
Estructura de Proyecto SvelteKit - Comprendiendo el directorio src/routes
Parámetros Dinámicos - Coincidentes de parámetros y patrones avanzados
Comparación de Enrutamiento por Sistema de Archivos - Cómo otros frameworks abordan el enrutamiento por sistema de archivos