Cuando empiezas un proyecto con Astro.js, verás que se genera una estructura de carpetas bastante completa.
Astro tiene una estructura de carpetas opinada pero flexible. Es decir, que no todos los proyectos Astro son idénticos, y la organización puede variar según si usas Markdown, componentes React o integraciones con Tailwind.
Pero en líneas generales, un proyecto típico puede tener una estructura similar a esta:
Proyecto/ ├── public/ ├── src/ │ ├── components/ │ ├── layouts/ │ └── pages/ ├── astro.config.mjs ├── package.json └── tsconfig.json
Veamos qué hace cada parte, y cómo se organiza una app en Astro 👇.
Archivos raíz del proyecto
| Archivo/Directorio | Función |
|---|---|
astro.config.mjs | Configuración principal de Astro (rutas, integraciones, build, etc.) |
package.json | Dependencias, scripts y metadatos del proyecto |
tsconfig.json | Configuración de TypeScript (si lo usas) |
.gitignore | Archivos que Git debe ignorar |
README.md | Documentación del proyecto |
En la raíz del proyecto tenemos los archivos que controlan cómo se comporta Astro.
Es el fichero principal de configuración de nuestro proyecto. Aquí es donde configuramos las integraciones y opciones de compilación.
Por defecto viene muy limpio:
import { defineConfig } from 'astro/config';
// https://astro.build/config
export default defineConfig({
// Aquí pondremos nuestras configuraciones
});
En este archivo es donde:
- Añadiremos integraciones como Tailwind, React o Vue.
- Configuraremos si queremos que la web sea estática (SSG) o renderizada en el servidor (SSR).
- Definiremos nuestro dominio final (
site: 'https://miweb.com') para que el SEO funcione correctamente.
Si elegiste TypeScript, estos archivos controlan el tipado. Astro genera automáticamente un archivo .astro/types.d.ts (que verás referenciado).
Esto hace que tengamos autocompletado inteligente incluso para cosas complejas como las colecciones de contenido, que veremos más adelante.
Carpeta src/
Aquí es donde trabajaremos el 99% del tiempo. Es donde vive tu código fuente. Astro procesará, optimizará y compilará todo lo que haya aquí dentro.
Esta es la carpeta más importante. Astro utiliza un sistema de enrutamiento basado en archivos (file-based routing).
- Si creas un archivo
src/pages/index.astro, esa será tu página de inicio (/). - Si creas
src/pages/contacto.astro, tendrás automáticamente una ruta en/contacto. - Si creas
src/pages/blog/articulo-1.md, tendrás una ruta en/blog/articulo-1.
Astro soporta archivos .astro, .md, .mdx, .html e incluso .js/.ts (para endpoints de API) dentro de la carpeta pages.
Aquí guardamos los trozos reutilizables de código. Botones, tarjetas, barras de navegación…
A diferencia de pages, los archivos aquí no generan rutas automáticas. Son piezas de Lego que importaremos dentro de nuestras páginas.
Los layouts son un tipo especial de componente diseñados para envolver páginas.
Por ejemplo, aquí crearíamos un BaseLayout.astro que contenga el <html>, <head>, y <body>. Así no tenemos que repetir las metaetiquetas en cada una de las páginas de nuestra web.
La carpeta public/
Aquí van los archivos que no necesitan ser procesados por Astro y que deben copiarse tal cual a la raíz del sitio web final.
- El
favicon.svg. - El archivo
robots.txt. - Imágenes que no quieres que Astro optimice o toque.
¿Diferencia entre public y src/assets?
Si pones una imagen en public/imagen.png, accederás a ella como tusitio.com/imagen.png. Astro no la toca.
Si la pones en src/assets/, Astro puede procesarla, cambiarle el tamaño y optimizarla. Generalmente, preferimos src/assets para imágenes de la web.
El archivo .astro
Antes de cerrar, echemos un vistazo rápido a un archivo .astro, por ejemplo src/pages/index.astro. Verás que tiene una estructura muy particular:
---
const titulo = "Mi primera web en Astro";
---
<html lang="es">
<head>
<title>{titulo}</title>
</head>
<body>
<h1>{titulo}</h1>
<p>¡Hola mundo!</p>
</body>
</html>
Esta es la sintaxis del sistema de componentes de Astro, que son el núcleo de Astro. Lo veremos con mayor profundidad en los siguientes artículos.
