Clase 01 · Módulo 05
Crear el proyecto y entender sus carpetas
Crear el proyecto y entender sus carpetas
Qué logras en esta clase
Terminas con un proyecto real corriendo en tu computador y sabiendo dónde está cada cosa.
- Un proyecto Astro creado y abierto en el navegador.
- Tailwind CSS instalado y funcionando.
- El mapa de carpetas claro: qué tocas y qué no.
- El primer commit hecho.
02
Un proyecto es una carpeta con reglas
Astro no es un programa que abres: es una carpeta con archivos ordenados de una forma que la herramienta sabe leer.
03
Antes de crear nada, comprueba
- Abre la terminal en la carpeta donde guardas tus proyectos.
- Escribe
node --version. Astro 7 pide Node22.23.4o superior, y no admite versiones impares como la 23. - Escribe
git --versionpara confirmar que Git responde.
04
Quién escribe el comando
| Opción | Conviene cuando | Costo |
|---|---|---|
| Lo escribes tú | Quieres entender cada paso | Respondes las preguntas a mano |
| Se lo pides a Claude Code | Ya hiciste un proyecto antes | Debes revisar qué instaló |
Para tu primer proyecto, hazlo tú. Es un solo comando y ver el proceso completo te ahorra dudas después.
05
Crear el proyecto
- Escribe
npm create astro@latest. - El asistente pregunta dónde crear el proyecto: dale un nombre de carpeta corto, en minúsculas y sin espacios.
- Elige la plantilla más simple que ofrezca.
- Acepta instalar las dependencias.
- Entra a la carpeta con
cd nombre-de-tu-carpeta.
06
Verlo en el navegador
- Dentro de la carpeta del proyecto, escribe
npm run dev. - La terminal imprime una dirección local. El puerto por defecto es el 4321.
- Ábrela en el navegador: verás la página de inicio de la plantilla.
- Para detener el servidor, vuelve a la terminal y presiona
Ctrl+C.
Mientras el servidor corre, cada archivo que guardas se refleja en el navegador casi al instante.
07
Esa dirección solo existe en tu computador
El servidor local es un borrador privado: nadie más puede ver tu web hasta que la publiques en el módulo 10.
08
Guarda este punto con un commit
Antes de cambiar nada, deja registrado el proyecto recién creado.
git statuspara ver si la carpeta ya es un repositorio. Si no lo es,git init.git add .git commit -m "Proyecto Astro inicial"
09
Agregar Tailwind CSS
Según la guía oficial de Tailwind para Astro, son cuatro movimientos:
- Instalar los paquetes:
npm install tailwindcss @tailwindcss/vite. - Registrar el plugin en
astro.config.mjs. - Crear
src/styles/global.csscon la línea@import "tailwindcss";. - Importar ese archivo CSS desde la página o plantilla que lo usa.
Puedes hacerlo a mano o pedírselo a Claude Code en modo plan, indicándole que siga esa guía.
10
Así queda la configuración
import { defineConfig } from "astro/config";
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
vite: {
plugins: [tailwindcss()],
},
});astro.config.mjs es el archivo donde se declaran los complementos del proyecto. No necesitas escribirlo de memoria: necesitas reconocerlo cuando Claude lo modifique.
11
Comprueba que Tailwind funciona
- Con
npm run devcorriendo, abresrc/pages/index.astro. - Agrega a cualquier título una clase visible, por ejemplo
class="text-3xl font-bold underline". - Guarda y mira el navegador.
Si el título cambia, Tailwind está activo. Si no cambia, lo más habitual es que falte importar global.css en esa página.
12
Dónde van tus tokens de diseño
Los colores, fuentes y espacios que definiste en el módulo 4 viven en src/styles/global.css, dentro del bloque @theme, debajo de la línea que importa Tailwind.
Es un solo archivo para todo el sitio. Cuando Claude construya una sección, debe usar esos nombres y no inventar colores sueltos.
13
El mapa de un proyecto Astro
public/
src/
components/
layouts/
pages/
index.astro
styles/
global.css
astro.config.mjs
package.json
tsconfig.jsonTu plantilla puede traer menos carpetas. Las que falten se crean cuando hagan falta.
14
Para qué sirve cada carpeta
| Carpeta | Qué guarda |
|---|---|
src/pages | Las páginas: cada archivo es una dirección del sitio |
src/layouts | Plantillas que comparten varias páginas |
src/components | Piezas reutilizables: botones, tarjetas, secciones |
src/styles | El CSS global y tus tokens |
public | Archivos que se copian tal cual |
Solo src/pages es obligatoria para Astro. Las demás son costumbre, y conviene respetarla.
15
Cada archivo de pages es una dirección
| Archivo | Dirección en el sitio |
|---|---|
src/pages/index.astro | / |
src/pages/servicios.astro | /servicios |
src/pages/contacto.astro | /contacto |
src/pages/blog/index.astro | /blog |
No hay un archivo aparte de rutas. Para crear una página nueva basta crear el archivo. Tu mapa del sitio del módulo 3 se convierte, casi literal, en esta carpeta.
16
La página de error también es un archivo
Si creas src/pages/404.astro, Astro la usa como página de error: es lo que ve quien llega a una dirección que no existe en tu sitio.
Ponle tu layout, una frase clara y un enlace al inicio. Sin ella, el visitante recibe un error genérico y se va.
Que el alojamiento la muestre en producción pide un ajuste que verás en el módulo 10.
17
public o src
public: lo que debe llegar idéntico al visitante, como el ícono del sitio, un PDF descargable orobots.txt.src: todo lo que Astro procesa, como páginas, estilos y las imágenes que quieres optimizadas.
18
Lo que no editas a mano
| Archivo o carpeta | Qué es |
|---|---|
package.json | Lista de dependencias y comandos del proyecto |
node_modules | Las dependencias descargadas; se regenera con npm install |
dist | El sitio ya construido; se regenera con cada build |
tsconfig.json | Configuración de TypeScript |
node_modules y dist no se suben a GitHub: revisa que estén en tu .gitignore.
19
Tres comandos para todo el curso
| Comando | Qué hace | Cuándo |
|---|---|---|
npm run dev | Servidor local con recarga | Mientras construyes |
npm run build | Genera el sitio final en dist | Antes de dar algo por terminado |
npm run preview | Sirve lo generado por el build | Para revisar el resultado real |
El servidor de desarrollo perdona cosas que el build no. Un sitio que solo probaste con dev no está probado.
20
Cómo leer un archivo .astro
---
const titulo = "Café del Barrio";
---
<h1>{titulo}</h1>
<p>Tostamos cada semana.</p>Arriba, entre las dos líneas de guiones, va el código que prepara datos. Abajo va el HTML, que puede mostrar esos datos entre llaves. El código de arriba se ejecuta al construir el sitio y no viaja al navegador.
21
Deja que Claude conozca el proyecto
Con el proyecto creado, abre Claude Code en esa carpeta y usa /init para generar el CLAUDE.md, como viste en el módulo 2.
Revisa que mencione lo esencial:
- Qué es el sitio y para quién.
- Los comandos
dev,buildypreview. - Dónde están los tokens y la regla de usarlos siempre.
- El orden de carpetas que quieres mantener.
22
Abrir Claude en la carpeta equivocada
Antes de empezar una sesión, comprueba con pwd que estás en la carpeta donde vive package.json.
23
Lo que te llevas
- Un proyecto Astro se crea con
npm create astro@latesty se ve connpm run dev. - Tailwind se suma con dos paquetes, un plugin y un archivo CSS global.
- Cada archivo de
src/pageses una dirección del sitio. srcse procesa;publicse copia tal cual.deves para construir;buildypreviewmuestran el resultado real.
24
Hazlo ahora
En 15 minutos:
- Crea tu proyecto y ábrelo en el navegador.
- Haz el commit inicial.
- Instala Tailwind y comprueba que una clase cambia un título.
- Pega tus tokens del módulo 4 en
global.css. - Crea
src/pages/prueba.astrocon un título y visita/prueba. - Ejecuta
npm run buildy confirma que termina sin errores. - Haz un segundo commit.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026
- Astro Docs: instalar y configurar Astrodocs.astro.build ↗
- Astro Docs: estructura del proyectodocs.astro.build ↗
- Astro Docs: referencia de la línea de comandosdocs.astro.build ↗
- Tailwind CSS: instalación en Astrotailwindcss.com ↗
- Claude Code: memoria del proyecto (CLAUDE.md)code.claude.com ↗
- Astro Docs: páginas (página 404 personalizada)docs.astro.build ↗