Estructura de un proyecto Astro

Cuando creas un proyecto con

1npm create astro@latest

Astro genera una estructura simple pero muy bien pensada. Vamos a ver qué hace cada carpeta y archivo, sin tecnicismos innecesarios.

1. Carpetas principales #

La estructura típica es:

mi-proyecto/
├── public/
├── src/
│   ├── components/
│   ├── layouts/
│   └── pages/
├── astro.config.mjs
├── package.json
└── tsconfig.json (si usas TypeScript)

Veamos qué hace cada una 👇

public/ #

• Contiene archivos estáticos que no pasan por Astro.
• Ejemplos: imágenes, íconos, fuentes, PDF, etc.
• Todo lo que pongas aquí se copia tal cual al sitio final.

Ejemplo: Si pones un archivo

public/logo.png

podrás acceder a él desde tu web en:

/logo.png

src/pages/ #

• Es la carpeta más importante de tu proyecto.
• Aquí van tus páginas (index.astro, about.astro, contact.astro, etc.).
• Cada archivo .astro dentro de pages se convierte automáticamente en una ruta.

Ejemplo:

src/pages/index.astro    →  https://tusitio.com/
src/pages/about.astro    →  https://tusitio.com/about
src/pages/blog/post.astro → https://tusitio.com/blog/post

✅ No necesitas configurar rutas manualmente. Astro lo hace por ti.

src/components/ #

• Aquí guardas componentes reutilizables: cabeceras, botones, tarjetas, menús, etc.
• Son como mini-bloques de HTML que puedes usar en varias páginas.

Ejemplo:

src/components/Header.astro
src/components/Footer.astro

Luego puedes usarlos en cualquier página:

1---
2import Header from '../components/Header.astro'
3import Footer from '../components/Footer.astro'
4---
5
6<Header />
7<h1>Bienvenido a mi sitio</h1>
8<Footer />

src/layouts/ #

• Guarda tus layouts (plantillas base).
• Un layout define la estructura general de tu web: encabezado, pie, menú, zona de contenido.

Ejemplo:

src/layouts/BaseLayout.astro

Y en una página:

1---
2import BaseLayout from '../layouts/BaseLayout.astro'
3---
4
5<BaseLayout>
6  <h1>Página de contacto</h1>
7  <p>Escríbenos cuando quieras.</p>
8</BaseLayout>

💡 Dentro del layout se usa un “slot” para que el contenido se inserte dinámicamente. Veremos eso en detalle en el Módulo 4.

2. Archivos base importantes #

astro.config.mjs #

Es el archivo de configuración del proyecto. Aquí puedes definir:

• La URL base del sitio.
• Integraciones (Tailwind, Markdown, etc.).
• Opciones de compilación.

Ejemplo:

1import { defineConfig } from 'astro/config';
2
3export default defineConfig({
4  site: 'https://miweb.com',
5  integrations: [],
6});

package.json #

Define las dependencias y scripts del proyecto.

Ejemplo:

1{
2  "name": "mi-proyecto",
3  "scripts": {
4    "dev": "astro dev",
5    "build": "astro build",
6    "preview": "astro preview"
7  },
8  "dependencies": {
9    "astro": "^4.0.0"
10  }
11}

3. Cómo funciona el enrutado automático #

Astro crea una ruta por cada archivo en src/pages/.

Ejemplo de estructura:

src/pages/
├── index.astro
├── about.astro
└── blog/
    ├── index.astro
    └── post.astro

Resultado en el navegador:

/               → index.astro
/about          → about.astro
/blog           → blog/index.astro
/blog/post      → blog/post.astro

🟢 Simple, sin configuraciones complicadas. 🟢 Soporta carpetas anidadas. 🟢 También puedes usar rutas dinámicas (por ejemplo /blog/[id].astro) que veremos en el módulo de contenido dinámico.

4. Cómo servir archivos estáticos #

Cualquier archivo en public/ se sirve directamente. Por ejemplo:

public/
├── logo.png
├── favicon.ico
└── resume.pdf

Puedes usarlo en tu HTML o Astro así:

1<img src="/logo.png" alt="Logo" />
2<a href="/resume.pdf">Descargar CV</a>

No necesitas importar ni compilar esos archivos.