Vamos a comenzar con la simple instalación de astro. Para ello te dejo la web oficial de Astro en dónde también nos iremos guiando a lo largo de este curso.
Instalación de Astro
Lo primero que tenemos que hacer es abrir la terminal de tu preferencia, en mi caso, y a lo largo de este curso, me verás usando WSL2 o linux/Debian. Abre la terminal y navega al directorio donde sueles guardar tus proyectos. En mi caso, es l ~/lab . A continuación pega el siguiente comando —El mismo que encuentras en la web de Astro.
npm create astro@latest
BashVerás que se lanza el asistente de Astro, Huston.
Deberás elegir una template para comenzar. Para este curso elegiremos una template vacía, por lo que debes elegir, Use minimal (empty) template
Dale un nombre a tu proyecto, instala las dependencias e inicializa git si así lo quieres, en i caso responderé que no.
Verás que al terminar el proyecto te da los siguientes pasos
Así que solo tienes que entrar a tu proyecto y ya estamos listos para comenzar. En mi caso me verás usando vscode o Antigravity. así que ejecutaré el comando code .
Antes de comenzar a picar código. Ve abuscar la extensión oficialk de astro en tu IDE de confianza
Estructura de directorios de un proyecto Astro
Cuando empiezas con Astro, lo primero que conviene hacer es entender como se organiza el proyecto. A diferencia de otros frameworks que esconden la magia detrás de configuraciones complejas, Astro apuesta por una estructura de carpetas que es, en esencia, la propia forma en la que funciona el framework. Por eso, familiarizarse con el arbol de directorios no es solo memorizar donde van los archivos: es entender el modelo mental de Astro.
La idea central es sencilla y elegante. Astro separa lo que es contenido estático (que se sirve tal cual) de lo que es código fuente (que se compila y optimiza). Esa separación se traduce en dos grandes zonas: la carpeta public/, donde depositas todo lo que no necesita procesamiento, y la carpeta src/, que es el corazon del proyecto donde vive tu código. Dentro de src/, la convención mas importante es pages/; aquí el sistema de archivos es tu enrutador. No necesitas definir rutas a mano; cada archivo que crees se convierte automaticamente en una URL. Es un principio de «convention over configuration» que te ahorra mucho trabajo y te mantiene enfocado en crear contenido en lugar de pelear con la configuración.
Más alla de eso, Astro te propone (aunque no te obliga) organizar tus componentes, plantillas, estilos y contenido en subcarpetas bien diferenciadas. El framework es lo suficientemente flexible para que puedas mover las cosas a tu gusto, pero seguir estas convenciones te hará la vida mas fácil cuando el proyecto crezca o cuando otra persona tenga que leer tu código. En las siguientes secciones verás el arbol completo del proyecto test-astro con comentarios sobre cada carpeta, así como una tabla resumen para consulta rápida.
test-astro/
├── public/ # Archivos estaticos servidos tal cual (sin procesar)
│ ├── favicon.ico # Icono del sitio (el que aparece en la pestana del navegador)
│ └── favicon.svg # Version SVG del favicon
│ # -> Todo lo que pongas aqui se copia directo a la carpeta
│ # final de build sin que Astro lo toque (imagenes,
│ # fuentes, robots.txt, etc.)
│
├── src/ # Codigo fuente de la app (lo que Astro compila)
│ ├── pages/ # Enrutamiento basado en archivos: cada archivo es una ruta
│ │ └── index.astro # Pagina de inicio ("/"). Astro usa el sistema de archivos
│ │ # para crear rutas: pages/about.astro => /about
│ │ # Aqui van .astro, .md, .mdx o componentes de framework
│ │
│ ├── components/ (opcional, no creado aun) # Componentes reutilizables .astro
│ ├── layouts/ (opcional, no creado aun) # Plantillas comunes (header/footer)
│ ├── styles/ (opcional, no creado aun) # Estilos globales / CSS compartido
│ └── content/ (opcional, no creado aun) # Colecciones de contenido (Markdown/MDX)
│
├── astro.config.mjs # Configuracion principal de Astro (integraciones, salida, etc.)
├── tsconfig.json # Configuracion de TypeScript para el proyecto
├── package.json # Dependencias y scripts (dev, build, preview)
├── .gitignore # Archivos que git ignora (node_modules, dist, .astro...)
├── README.md # Documentacion del proyecto
├── AGENTS.md # Instrucciones para herramientas de IA / colaboradores
└── .vscode/ # Configuracion del editor Visual Studio Code
├── extensions.json # Extensiones recomendadas
└── launch.json # Configuracion de depuracion (debug)
Bash| Directorio / archivo | Para que sirve en Astro |
|---|
public/ | Archivos estaticos que se sirven sin transformar |
src/pages/ | Define las rutas del sitio (file-based routing) |
src/components/ | Componentes .astro reutilizables |
src/layouts/ | Plantillas que encapsulan la estructura comun de paginas |
src/styles/ | Hojas de estilo globales o compartidas |
src/content/ | Colecciones de contenido tipo Markdown/MDX |
astro.config.mjs | Configuracion del proyecto (integraciones, build) |
tsconfig.json | Ajustes de TypeScript |
package.json | Scripts y dependencias del proyecto |
Tu primera página en Astro
Crear páginas en Astro es tan simple como crear archivos dentro de src/pages/. Cada archivo se convierte automáticamente en una ruta. Veamos los ejemplos básicos.
Página simple: about.astro
Crea el archivo src/pages/about.astro con este contenido:
---
// Aquí va el código de Astro (frontmatter)
---
<h1>Hola mundo desde Astro</h1>
AstroCon esto ya tienes la ruta /about.
Página dentro de un directorio: /dashboard
Si necesitas agrupar páginas, crea carpetas. Por ejemplo, src/pages/dashboard/page.astro genera la ruta /dashboard.
---
// Página en src/pages/dashboard/page.astro
---
<h1>Hola mundo desde el Dashboard</h1>
AstroOtras formas de crear páginas
Astro es flexible y admite varios tipos de archivos como páginas que veremos más adelante:
- Markdown y MDX:
src/pages/blog/post.md crea /blog/post. Ideal para contenido escrito.
- Componentes de framework: puedes usar archivos
.jsx, .tsx, .vue, .svelte, etc., si instalas la integración correspondiente.
- Rutas dinámicas:
src/pages/producto/[id].astro genera páginas dinámicas como /producto/123 usando getStaticPaths().
- Rutas de índice:
src/pages/dashboard/index.astro también crea /dashboard, igual que page.astro en el ejemplo anterior.
La regla de oro: lo que esté en src/pages/ se vuelve una URL. Lo demás es código reutilizable.