El CLI de Astro · Astro 7

Toda la interacción con Astro pasa por un puñado de comandos de terminal. No son intercambiables: dev sirve para desarrollar, build para producir, preview para verificar, y hay utilidades —add, check, sync— que resuelven tareas concretas del ciclo de vida. Saber cuál invocar y cuándo es la diferencia entre pelearte con la herramienta y fluir con ella.

🎯 Al terminar esta lección sabrás

Dominar el ciclo diario dev, build y preview y qué produce cada uno.
Usar astro add para instalar y configurar integraciones sin editar a mano.
Ejecutar astro check como puerta de calidad de tipos antes de desplegar.
Entender astro sync y cuándo se dispara la generación de tipos del proyecto.

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.

Comando	Para qué sirve
`astro dev`	Levanta el servidor de desarrollo con HMR en el puerto 4321. Es el modo en que trabajas.
`astro build`	Construye el sitio de producción en la carpeta `dist`. El artefacto que despliegas.
`astro preview`	Sirve localmente lo que hay en `dist`. Un ensayo de producción antes de publicar.

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:4321
npm run build     # producir: genera dist/ listo para desplegar
npm run preview   # verificar: sirve dist/ como lo hara produccion

⚠️

preview no es un servidor de producción

astro preview existe para verificar tu build en local, no para servirlo en producción. Para un sitio estático sirve los ficheros de dist; para uno con renderizado bajo demanda, depende de que tu adapter soporte el comando. En producción real usas el hosting o el runtime del adapter, no preview. Confundirlos lleva a desplegar algo que nunca fue pensado para aguantar tráfico.

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.

📝

astro dev es el comando por defecto

Ejecutar astro sin subcomando equivale a astro dev: desarrollar es lo que más haces, así que es el comportamiento por defecto. Los scripts de tu package.json explicitan el subcomando —astro dev, astro build— por claridad, pero en la terminal basta teclear astro para arrancar.

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 errores
npx 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.

💡

check en integración continua

El sitio ideal para astro check es tu pipeline de CI, como paso previo a build. Un build puede completarse con errores de tipos latentes que solo estallan en runtime; check los caza antes de fusionar. Encadena astro check && astro build y conviertes los tipos en una barrera que ningún despliegue puede saltarse.

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.

🔄

astro sync

Regenera los tipos en .astro. Se dispara solo antes de dev y build; lánzalo a mano para refrescar tipos obsoletos.

ℹ️

astro info

Vuelca tu entorno —versiones, adapter, integraciones—. Lo que pegas al abrir un reporte de bug.

📚

astro docs

Abre la documentación oficial en el navegador desde la terminal.

⚙️

astro preferences

Gestiona preferencias del usuario, como la telemetría, sin editar ficheros.

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 check
npm run astro -- sync      # ejecuta astro sync
npm 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.

flowchart LR
DEV[astro dev] --> CODE[iteras con HMR]
CODE --> CHK[astro check]
CHK --> BUILD[astro build]
BUILD --> DIST[carpeta dist]
DIST --> PREV[astro preview]
PREV --> DEPLOY[despliegue]
style DEV fill:#89b4fa,color:#11111b
style DEPLOY fill:#a6e3a1,color:#11111b

⚡

Cada comando encarna una fase mental, no solo una acción

El CLI de Astro parece una lista de verbos, pero en realidad es un modelo del ciclo de vida de un sitio, y aprenderlo bien es aprender a pensar en fases separadas. dev es el modo de exploración: rápido, tolerante, optimizado para que cambies cien veces por minuto. build es el modo de compromiso: toma tu código y lo cristaliza en el artefacto exacto que verá el mundo, con todas las optimizaciones activadas. preview es el modo de desconfianza sana: no te fías del build a ciegas, lo ejecutas en local como lo hará producción. Y las utilidades —add, check, sync— existen para que las tareas mecánicas y peligrosas no las hagas a mano: add edita tu configuración sin erratas, check valida tipos que un build ignoraría, sync mantiene coherente el puente entre tu contenido y tus tipos. El error del principiante es vivir siempre en dev y descubrir los problemas al desplegar; el profesional recorre la secuencia entera —desarrolla, valida, construye, verifica— porque sabe que cada comando existe para cazar una clase distinta de fallo en el momento más barato para arreglarlo. El CLI no es un teclado de atajos: es una disciplina de trabajo hecha comandos.

⚔️ Recorre el ciclo completo

Arranca npm run dev, haz un cambio y observa el HMR; luego para el servidor.
Ejecuta npm run build y explora la carpeta dist: identifica el HTML generado y los assets con hash en el nombre.
Lanza npm run preview y compara la experiencia con la de dev: no hay HMR, y ves exactamente lo que se desplegaría.
Prueba npx astro add sitemap, revisa el diff que propone antes de aceptarlo y confirma cómo quedó tu astro.config.mjs.