src/pages y el enrutado por ficheros

En casi todos los frameworks tradicionales las rutas se declaran en una tabla: un fichero central que asocia URLs a manejadores. Astro elimina esa tabla. En su lugar, el sistema de ficheros es la tabla de rutas: cada archivo que colocas en src/pages se convierte, sin más ceremonia, en una URL navegable. Entender esta equivalencia —fichero igual a ruta— es entender el eje entero sobre el que gira la navegación de un proyecto.

El sistema de ficheros como tabla de rutas

En un framework de enrutado imperativo declaras cada ruta a mano: un array de objetos, un fichero de configuración, una llamada por endpoint. Astro invierte el planteamiento. No hay tabla de rutas que mantener porque la carpeta src/pages es la tabla: Astro la recorre en el build y, por cada fichero que encuentra, deriva una URL a partir de su ruta relativa. La correspondencia es directa y mecánica —quita el prefijo src/pages, quita la extensión, y lo que queda es la URL—.

• src/pages/index.astro produce la ruta raíz, /.
• src/pages/about.astro produce /about.
• src/pages/contacto.astro produce /contacto.

Esta equivalencia tiene una consecuencia liberadora: para saber qué URL sirve un fichero no consultas ninguna configuración, solo miras dónde vive. Y a la inversa, para saber qué fichero atiende una URL reconstruyes la ruta en tu cabeza. El mapa y el territorio coinciden.

Bajo el capó, Astro recorre src/pages durante el build y compila un manifiesto de rutas: la lista de todas las URLs que tu sitio conoce, derivada del árbol de ficheros. No lo escribes ni lo mantienes tú; se regenera en cada compilación a partir de la única fuente de verdad que hay, la carpeta. Por eso no existe el clásico desajuste entre la ruta declarada y el fichero que la sirve: la declaración es el fichero. Cuando en la próxima lección veas los distintos tipos de página, recuerda que todos alimentan este mismo manifiesto.

index: la raíz de cada carpeta

El nombre index recibe un trato especial, heredado de la web clásica: representa la raíz de la carpeta que lo contiene, no un segmento propio. Por eso src/pages/index.astro no sirve /index sino /. Esta regla se propaga a cualquier profundidad.

• src/pages/blog/index.astro sirve /blog, no /blog/index.
• src/pages/docs/guia/index.astro sirve /docs/guia.

Aquí aparece una de las decisiones de diseño más frecuentes: para la portada de una sección, ¿usas blog.astro o blog/index.astro? Ambas sirven /blog, pero comunican intenciones distintas. blog/index.astro anuncia que habrá hermanos —blog/[slug].astro, blog/archivo.astro— y agrupa la sección en su propia carpeta. blog.astro sugiere una página aislada sin descendencia. Elegir bien no cambia la URL, pero sí la legibilidad del árbol.

src/pages/
├─ index.astro          ->  /
├─ about.astro          ->  /about
└─ blog/
   ├─ index.astro       ->  /blog
   ├─ primero.astro     ->  /blog/primero
   └─ segundo.astro     ->  /blog/segundo

El anidamiento no tiene un límite práctico: src/pages/docs/api/v2/index.astro sirve /docs/api/v2 sin que Astro pestañee. La profundidad del árbol es la profundidad de tus URLs, así que conviene que ambas reflejen la jerarquía real del contenido y no accidentes de organización. Una URL profunda cuenta una historia —dónde encaja esta página dentro del todo— y esa historia debería ser cierta.

Subcarpetas y la jerarquía de URLs

Si index marca la raíz de una carpeta, las subcarpetas construyen los segmentos intermedios de la dirección. Cada nivel de anidamiento en src/pages añade un tramo separado por barras en la URL final. La jerarquía del sistema de ficheros se proyecta, tramo a tramo, sobre la jerarquía de la URL.

flowchart TD
P[src pages] --> I[index]
P --> A[about]
P --> B[blog]
B --> BI[blog index]
B --> BP[blog post]
I --> IU[URL raiz]
A --> AU[URL about]
BI --> BIU[URL blog]
BP --> BPU[URL blog post]
style P fill:#89b4fa,color:#11111b
style IU fill:#a6e3a1,color:#11111b
style AU fill:#a6e3a1,color:#11111b
style BIU fill:#a6e3a1,color:#11111b
style BPU fill:#a6e3a1,color:#11111b

Esta proyección es un isomorfismo: a cada árbol de ficheros le corresponde exactamente un árbol de URLs, y viceversa. No hay reescrituras ocultas ni alias silenciosos entre lo que ves en el editor y lo que teclea el visitante. Esa transparencia es el gran valor del enrutado por ficheros: la estructura del proyecto se autodocumenta, y cualquiera que abra src/pages entiende el mapa del sitio sin leer una línea de configuración.

Compáralo con un router imperativo, donde la ruta y el fichero que la sirve viven en lugares distintos y se enlazan por una cadena que hay que mantener a mano. Ahí caben tres estados de error: una ruta sin fichero, un fichero sin ruta y una ruta que apunta al fichero equivocado. En el enrutado por ficheros esos tres estados sencillamente no pueden existir, porque no hay dos cosas separadas que sincronizar. Eliminar categorías enteras de error —y no solo reducir su frecuencia— es la marca de una abstracción bien elegida.

Hay un corolario práctico que conviene interiorizar pronto: mover un fichero es cambiar su URL. Renombrar contacto.astro a hablemos.astro reescribe la dirección pública y rompe cualquier enlace que apuntara a la anterior. En el enrutado por ficheros no existe una capa de indirección que te proteja de esto; la ruta física y la ruta pública están soldadas. Es el precio —justo— de eliminar la tabla de rutas.

Por eso, en un proyecto que madura, conviene tratar las URLs con el mismo cuidado que una API pública: son un contrato con quien enlaza, marca o comparte tus páginas. No se renombran a la ligera, y cuando hay que hacerlo, la mudanza se acompaña de una redirección desde la dirección antigua. El enrutado por ficheros vuelve ese contrato muy tangible —la dirección es el fichero— y precisamente por eso merece respeto.

Astro admite además segmentos dinámicos con corchetes —[slug].astro, [...ruta].astro— que generan familias enteras de URLs a partir de datos. Son la extensión natural de todo lo anterior y merecen su propio tratamiento; por ahora basta con saber que conviven en la misma carpeta y siguen la misma lógica de proyección.

La disciplina que exige el enrutado por ficheros

La comodidad de que el sistema de ficheros sea el router tiene una contrapartida: te impone una disciplina que ningún linter vigila por ti. La primera regla es de higiene —mantén src/pages habitado solo por páginas—. Todo lo auxiliar vive fuera: los componentes en src/components, la lógica en src/lib, las plantillas en src/layouts. Un fichero mal ubicado no da error; simplemente aparece como una URL que nadie quería publicar.

La segunda es de nomenclatura. Como el nombre del fichero es el segmento de la URL, elígelo pensando en el visitante, no en ti: minúsculas, sin espacios ni acentos, con guiones en lugar de guiones bajos. Un Mi Página.astro produce una URL fea y frágil; un mi-pagina.astro produce /mi-pagina, limpia y estable. Y cuidado con las mayúsculas: algunos sistemas de ficheros las distinguen y otros no, así que dos ficheros que solo difieran en la caja son una trampa esperando al despliegue.

La tercera es aceptar el acoplamiento físico. Como la ubicación es la URL, no hay una capa que te permita reorganizar carpetas sin mover direcciones. Reestructurar src/pages es reestructurar tu sitio de cara al público, con todo lo que eso implica para enlaces externos y buscadores. No es un defecto: es la misma transparencia que te da el modelo, vista desde su lado exigente.