El CLI de Astro

El ciclo diario: dev, build, preview

Tres comandos cubren el noventa por ciento de tu trabajo, y forman una secuencia natural: desarrollas, construyes y verificas antes de desplegar.

La distinción crucial es entre dev y build. astro dev optimiza para la iteración rápida: recarga en caliente, sin minificar, sin el trabajo pesado de un build real. astro build hace lo contrario: prerenderiza páginas, agrupa y minifica assets, versiona ficheros con un hash y deja en dist exactamente lo que servirá tu hosting. Nunca despliegues lo que ves en dev; despliega siempre el resultado de build.

npm run dev       # desarrollar: servidor con HMR en localhost:4321npm run build     # producir: genera dist/ listo para desplegarnpm run preview   # verificar: sirve dist/ como lo hara produccion

Todos estos comandos comparten un conjunto de banderas globales que ajustan su comportamiento sin tocar la configuración. Las que más usarás:

• --host expone el servidor en tu red local, para probar desde el móvil.
• --port fija el puerto en lugar del 4321 por defecto.
• --config apunta a un fichero de configuración alternativo.
• --root cambia la raíz del proyecto si no lo ejecutas desde su carpeta.
• --verbose y --silent suben o bajan el detalle de los logs.

add: integraciones sin fricción

astro add automatiza la tarea más propensa a errores: incorporar una integración o un adapter. En vez de instalar el paquete, importarlo y editar el array integrations a mano, un solo comando lo hace todo y te enseña el diff antes de aplicarlo.

npx astro add react# 1. instala @astrojs/react y sus dependencias con tu gestor# 2. edita astro.config.mjs para registrar la integracion# 3. ajusta tsconfig.json con los tipos necesarios# antes de tocar nada, te muestra los cambios y pide confirmacion

Acepta varios argumentos a la vez —astro add react tailwind vercel— y entiende tanto integraciones como adapters: al añadir un adapter, además configura output por ti. Es la vía recomendada precisamente porque edita tu configuración mediante manipulación del árbol de sintaxis, no con pegado de texto: no rompe el formato ni introduce erratas.

Si la integración ya estaba configurada, astro add lo detecta y no duplica nada: es seguro relanzarlo. Y como te enseña el diff antes de escribir, siempre ves y apruebas los cambios; nunca actúa a tus espaldas.

check: la puerta de calidad

astro check ejecuta un diagnóstico de tipos sobre todo el proyecto, incluidos los ficheros .astro —que TypeScript por sí solo no entiende—. Detecta props mal tipadas, imports rotos y errores que el editor marca en rojo pero que un build normal no siempre frena. Requiere el paquete @astrojs/check y TypeScript instalados.

npx astro check            # analiza una vez y reporta erroresnpx astro check --watch    # re-analiza en cada cambio, util al desarrollar

Conviene entender su alcance: astro check valida tipos y plantillas, pero no ejecuta tu sitio ni comprueba la lógica en runtime. Es un análisis estático, hermano de lo que ya ves subrayado en el editor —ambos usan el mismo servidor de lenguaje de Astro—, con la diferencia de que check lo corre de una vez sobre todo el proyecto y devuelve un código de salida que un pipeline puede leer.

sync y utilidades: los comandos de apoyo

astro sync genera los tipos de TypeScript de tu proyecto: los de las colecciones de contenido a partir de tus esquemas, los de las variables de entorno tipadas y los de otros módulos virtuales. Los escribe en la carpeta .astro. Astro lo ejecuta automáticamente antes de dev y de build, así que rara vez lo lanzas a mano; lo haces cuando tu editor muestra tipos obsoletos tras cambiar un esquema y quieres refrescarlos sin arrancar el servidor. Esa carpeta es un artefacto generado: va en tu .gitignore y nunca se edita a mano.

Cuando abras un reporte de error, astro info ahorra ida y vuelta: vuelca de una vez tu sistema, tu gestor de paquetes, la versión de Astro y las integraciones activas.

npm run astro -- info# imprime SO, gestor de paquetes, version de Astro,# adapter e integraciones activas para pegar en un reporte

Todos estos comandos se invocan igual desde los scripts de npm. Los tres del ciclo diario ya vienen como dev, build y preview en tu package.json; para el resto, npm run astro -- <comando> reenvía lo que sigue al -- directamente al CLI de Astro.

npm run astro -- check     # ejecuta astro checknpm run astro -- sync      # ejecuta astro syncnpm run astro -- add react # ejecuta astro add react

El doble guion es la frontera: lo que va antes lo interpreta npm; lo que va después, Astro. Con ese patrón alcanzas cualquier subcomando sin añadir un script por cada uno.