Astro

Contenido

Introducción
Conocimiento previo
Referencias
Índice
1. Qué es Astro
2. Crear un proyecto Astro
3. Estructura de carpetas
4. Páginas y rutas
5. Componentes Astro
6. Estilos en Astro
7. Markdown y contenido
8. Islas interactivas
9. Build y preview
10. Errores frecuentes
11. Ejercicios

Tutorial introductorio de Astro para crear sitios web rápidos y orientados a contenido: instalación, estructura del proyecto, páginas, componentes, Markdown, islas interactivas y build de producción.

Por José Luís Ferrer Rodríguez | Actualizado: 28/06/2026

Introducción

Astro es un framework web moderno pensado para crear sitios rápidos y centrados en contenido. Es especialmente útil para documentación, blogs, sitios educativos, páginas corporativas, portfolios y proyectos donde el rendimiento y el SEO son importantes.

La idea principal de Astro es generar HTML de forma eficiente y enviar al navegador solo el JavaScript necesario. Esto permite crear páginas rápidas sin renunciar a componentes, Markdown, TypeScript o integraciones con frameworks como React, Vue, Svelte o Preact.

En este tutorial aprenderás a crear un proyecto Astro, entender su estructura y construir páginas y componentes sencillos.

Conocimiento previo

HTML
Markdown
Conceptos básicos de JavaScript y npm.

Referencias

Índice

Qué es Astro
Crear un proyecto Astro
Estructura de carpetas
Páginas y rutas
Componentes Astro
Estilos en Astro
Markdown y contenido
Islas interactivas
Build y preview
Errores frecuentes
Ejercicios

1. Qué es Astro

Astro es un framework para construir sitios web. Su enfoque se basa en tres ideas:

Generar HTML rápido y optimizado.
Enviar poco JavaScript al navegador por defecto.
Permitir usar componentes y contenido en Markdown de forma cómoda.

Astro puede funcionar como generador de sitio estático, pero también puede usar adaptadores para despliegues con renderizado bajo demanda cuando el proyecto lo necesita.

Una diferencia importante frente a otros frameworks es que un componente Astro no se hidrata automáticamente en el navegador. Si usas un componente interactivo de React, Vue o Svelte, debes indicar cuándo cargar su JavaScript con una directiva client:*.

2. Crear un proyecto Astro

Para crear un proyecto nuevo puedes usar el asistente oficial:

npm create astro@latest

El asistente preguntará el nombre del proyecto, la plantilla inicial y algunas opciones de configuración.

Después entra en la carpeta e instala dependencias si no se instalaron automáticamente:

cd nombre-del-proyecto
npm install

Arranca el servidor de desarrollo:

npm run dev

Astro mostrará una URL local, normalmente http://localhost:4321/. Abre esa dirección en el navegador para ver el proyecto.

También puedes usar otros gestores de paquetes como pnpm o yarn, si el proyecto está preparado para ello.

3. Estructura de carpetas

Un proyecto Astro suele tener una estructura parecida a esta:

proyecto-astro/
├── public/
│   └── favicon.svg
├── src/
│   ├── components/
│   ├── content/
│   ├── layouts/
│   ├── pages/
│   └── styles/
├── astro.config.mjs
├── package.json
└── tsconfig.json

Carpetas y archivos habituales:

Ruta	Uso
`src/pages/`	Define páginas y rutas del sitio.
`src/components/`	Componentes reutilizables.
`src/layouts/`	Layouts para compartir estructura entre páginas.
`src/content/`	Contenido organizado en colecciones.
`src/styles/`	Hojas de estilo globales o compartidas.
`public/`	Archivos estáticos copiados sin procesar.
`astro.config.mjs`	Configuración principal del proyecto.
`tsconfig.json`	Configuración de TypeScript.

La carpeta obligatoria para crear rutas es src/pages/.

4. Páginas y rutas

En Astro, cada archivo dentro de src/pages/ genera una ruta.

Ejemplos:

Archivo	Ruta generada
`src/pages/index.astro`	`/`
`src/pages/about.astro`	`/about`
`src/pages/blog/index.astro`	`/blog`
`src/pages/blog/primer-post.md`	`/blog/primer-post`

Ejemplo de página Astro:

---
const title = 'Mi primera página Astro';
---

<!doctype html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <title>{title}</title>
  </head>
  <body>
    <h1>{title}</h1>
    <p>Esta página se ha creado con Astro.</p>
  </body>
</html>

La parte entre --- se llama frontmatter del componente. Ahí puedes escribir JavaScript o TypeScript que se ejecuta durante el renderizado.

5. Componentes Astro

Los componentes Astro tienen extensión .astro y permiten separar partes reutilizables de la interfaz.

Archivo src/components/Card.astro:

---
const { title, body } = Astro.props;
---

<article class="card">
  <h2>{title}</h2>
  <p>{body}</p>
</article>

<style>
  .card {
    border: 1px solid #ddd;
    border-radius: 0.5rem;
    padding: 1rem;
  }
</style>

Uso del componente en una página:

---
import Card from '../components/Card.astro';
---

<Card title="Astro" body="Framework web orientado a contenido." />

Un componente Astro puede recibir props, importar otros componentes, incluir estilos y generar HTML.

6. Estilos en Astro

Puedes escribir estilos dentro de un componente:

<h1>Hola Astro</h1>

<style>
  h1 {
    color: rebeccapurple;
  }
</style>

Estos estilos quedan asociados al componente. Para estilos globales, puedes importar un archivo CSS en un layout o página:

---
import '../styles/global.css';
---

Esta separación ayuda a mantener estilos locales cuando pertenecen a un componente y estilos globales cuando afectan a todo el sitio.

7. Markdown y contenido

Astro permite crear páginas directamente con Markdown dentro de src/pages/.

Archivo src/pages/blog/primer-post.md:

---
title: "Mi primer post"
pubDate: "2026-06-28"
---

# Mi primer post

Este contenido está escrito en Markdown.

Para proyectos con mucho contenido, Astro ofrece Content Collections, que permiten organizar entradas en src/content/ y validar sus metadatos con un archivo de configuración como src/content.config.ts.

Las colecciones son útiles cuando necesitas tipado, validación y listados de contenido.

8. Islas interactivas

Astro genera HTML por defecto y no envía JavaScript innecesario al navegador. Cuando necesitas interactividad, puedes usar componentes de frameworks como React, Vue, Svelte o Preact y activarlos con directivas client:*.

Ejemplo conceptual:

---
import Counter from '../components/Counter.jsx';
---

<Counter client:load />

Directivas habituales:

Directiva	Cuándo carga JavaScript
`client:load`	Al cargar la página.
`client:idle`	Cuando el navegador está libre.
`client:visible`	Cuando el componente entra en pantalla.
`client:media`	Cuando se cumple una media query.
`client:only`	Solo renderiza en cliente.

Este modelo se conoce como arquitectura de islas: la página puede ser mayoritariamente HTML estático, con pequeñas zonas interactivas cuando hacen falta.

9. Build y preview

Para generar la versión de producción:

npm run build

Astro generará normalmente la carpeta dist/ con el sitio listo para desplegar.

Para revisar localmente el resultado de producción:

npm run preview

Si el proyecto es estático, puedes desplegar dist/ en un hosting estático. Si necesitas renderizado en servidor, funciones o edge, puedes añadir un adaptador según la plataforma de despliegue.

10. Errores frecuentes

Error	Causa habitual	Solución
Crear una página fuera de `src/pages/`	Astro no genera ruta	mover el archivo a `src/pages/`
Esperar interactividad sin `client:*`	el componente se renderiza como HTML	añadir una directiva de cliente si procede
Poner assets procesables en `public/`	`public/` se copia sin transformar	usar `src/` para assets que deba procesar Astro
Olvidar reiniciar tras cambiar configuración	cambios de config no aplicados	reiniciar `npm run dev`
No validar antes de build	errores detectados tarde	ejecutar `npm run check` si el proyecto lo incluye

11. Ejercicios

Ejercicio 1: Crear un proyecto Astro

Crea un proyecto Astro con npm create astro@latest.

Ejercicio 2: Añadir una página

Añade una página src/pages/about.astro con un título y un párrafo.

Ejercicio 3: Crear un componente

Crea un componente Card.astro y úsalo desde una página.

Ejercicio 4: Añadir contenido Markdown

Añade un archivo Markdown en src/pages/blog/primer-post.md.

Ejercicio 5: Crear un layout

Crea un layout básico y úsalo en dos páginas.

Ejercicio 6: Generar la versión de producción

Ejecuta npm run build y revisa la carpeta dist/.

Ejercicio 7: Revisar el sitio generado

Ejecuta npm run preview y comprueba el sitio generado.

Astro es una buena herramienta para proyectos donde el contenido es importante y la interactividad debe añadirse de forma selectiva. Comprender páginas, componentes, Markdown e islas interactivas te permitirá crear sitios rápidos y mantenibles.