Saltearse al contenido

Comandos del CLI

Puedes usar la Interfaz de Línea de Comandos (CLI) proporcionada por Astro para desarrollar, construir y previsualizar tu proyecto desde una ventana de la terminal.

Usa el CLI ejecutando alguno de los comandos documentados en esta página con tu gestor de paquetes preferido, opcionalmente seguido por alguna flag. Las banderas personalizan el comportamiento de un comando.

Uno de los comandos que usarás con mayor frecuencia es astro dev. Este comando inicia el servidor de desarrollo y te da una vista previa en vivo y actualizada de tu sitio en un navegador mientras trabajas:

Ventana de terminal
# empieza el servidor de desarrollo
npx astro dev

Puedes escribir astro --help en tu terminal para mostrar una lista de todos los comandos disponibles:

Ventana de terminal
npx astro --help

El siguiente mensaje se mostrará en tu terminal:

Ventana de terminal
astro [command] [...flags]
Commands
add Add an integration.
build Build your project and write it to disk.
check Check your project for errors.
dev Start the development server.
docs Open documentation in your web browser.
info List info about your current Astro setup.
preview Preview your build locally.
sync Generate content collection types.
telemetry Configure telemetry settings.
Global Flags
--config <path> Specify your config file.
--root <path> Specify your project root folder.
--site <url> Specify your project site.
--base <pathname> Specify your project base.
--verbose Enable verbose logging.
--silent Disable all logging.
--version Show the version number and exit.
--open Abre la aplicación en el navegador al iniciar el servidor.
--help Show this help message.

También puedes usar scripts en el package.json para versiones más cortas de estos comandos. Usar un script te permite usar los mismos comandos que podrías estar familiarizado de otros proyectos, como npm run build.

El siguiente script para los comandos más comunes de astro (astro dev, astro build y astro preview) se agrega automáticamente cuando creas un proyecto usando el asistente create astro.

Cuando sigues las instrucciones para instalar Astro manualmente, se te indica que agregues estos scripts tú mismo. También puedes agregar más scripts a esta lista manualmente para cualquier comando que uses con frecuencia.

package.json
{
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro build",
"preview": "astro preview"
}
}

Seguido usarás estos comandos astro o los scripts que los ejecutan, sin ninguna flag. Agrega las banderas al comando cuando quieras personalizar el comportamiento del comando. Por ejemplo, es posible que desees iniciar el servidor de desarrollo en un puerto diferente, o construir tu sitio con registros detallados para la depuración.

Ventana de terminal
# ejecuta el servidor de desarrollo en el puerto 8080 usando el script `start` en `package.json`
npm run start -- --port 8080
# compila tu sitio con registros detallados usando el script `build` en `package.json`
npm run build -- --verbose

Corre el servidor de desarrollo de Astro. Es un servidor HTTP local que no empaqueta recursos. Usa Hot Module Replacement (HMR) para actualizar tu navegador a medida que guardas los cambios en tu editor.

Construye tu proyecto para producción. Por defecto, Astro generará archivos estáticos y los colocará en el directorio dist/. Si SSR está habilitado, Astro generará los archivos necesarios para que el servidor renderice tu proyecto.

Se puede combinar con la bandera común documentada a continuación.

Inicia un servidor local para servir el contenido de su directorio estático (dist/ por defecto) creado al ejecutar astro build.

Este comando es útil para obtener una vista previa de tu proyecto usando los archivos generados en la compilación final, antes de ser desplegado. Este comando no está diseñado para ejecutarse en producción. Para obtener ayuda con el despliegue a producción, consulta nuestra guía de despliegue de un sitio web de Astro.

Desde Astro 1.5.0, astro preview también funciona para compilaciones con SSR si usas un adaptador que lo soporte. Actualmente, solo el adaptador de Node soporta astro preview.

Puede combinarse con las banderas comunes documentadas más abajo.

Ejecuta diagnósticos (como verificación de tipos dentro de archivos .astro) en tu proyecto y reporta errores en la consola. Si se encuentran errores, el proceso finalizará con el código 1.

Este comando está diseñado para usarse en workflows de CI.

Flags

Utilice estas flags para personalizar el comportamiento del comando.

El comando observará cualquier cambio en su proyecto e informará cualquier error.

Agregado en: astro@2.0.0

Genera tipos de TypeScript para todos los módulos de Astro. Esto establece un archivo src/env.d.ts para inferencia de tipos y define el módulo astro:content para la API de colecciones de contenido.

Agrega una integración a tu configuración. Lee más en la guía de integraciones.

Inicia el sitio web de la documentación de Astro directamente desde la terminal.

Proporciona información útil sobre tu entorno de Astro actual. Útil para proporcionar información al abrir un issue.

Ventana de terminal
astro info

Ejemplo de salida:

Astro v3.0.12
Node v20.5.1
System macOS (arm64)
Package Manager pnpm
Output server
Adapter @astrojs/vercel/serverless
Integrations none

Gestiona las preferencias de usuario con el comando astro preferences. Las preferencias de usuario son específicas para los usuarios individuales de Astro, a diferencia del archivo astro.config.mjs que cambia el comportamiento de todos los que trabajan en un proyecto.

Por defecto, las preferencias del usuario se limitan al proyecto actual y se almacenan en un archivo local .astro/settings.json.

Usando el indicador --global, las preferencias del usuario también se pueden aplicar a cada proyecto de Astro en la máquina actual. Las preferencias globales del usuario se almacenan en una ubicación específica del sistema operativo.

Por ejemplo, para desactivar la devToolbar en un proyecto Astro específico:

Ventana de terminal
astro preferences disable devToolbar

Para desactivar la devToolbar en todos los proyectos Astro en la máquina actual:

Ventana de terminal
astro preferences disable --global devToolbar

La devToolbar se puede activar más tarde con:

Ventana de terminal
astro preferences enable devToolbar

El comando reset restablece una preferencia a su valor por defecto:

Ventana de terminal
astro preferences reset devToolbar

El comando list imprime la configuración actual de todas las preferencias de usuario configurables. También admite una salida --json legible por máquina.

Ventana de terminal
astro preferences list

Establece la configuración de telemetría para el usuario de la CLI actual. La telemetría son datos anónimos que proporcionan información al equipo de Astro sobre qué características de Astro se utilizan con más frecuencia. Para obtener más información, consulta la página de telemetría de Astro.

La telemetría se puede desactivar con este comando:

Ventana de terminal
astro telemetry disable

La telemetría se puede volver a habilitar con:

Ventana de terminal
astro telemetry enable

El comando reset restablece los datos de telemetría:

Ventana de terminal
astro telemetry reset

Especifica la ruta a la raíz del proyecto. Si no se especifica, se asume que la carpeta de trabajo actual es la raíz.

La raíz se utiliza para encontrar el archivo de configuración de Astro.

Ventana de terminal
astro --root miCarpetaRaiz/miCarpetaDeProyecto dev

Especifica la ruta relativa al archivo de configuración desde la raíz del directorio. El valor predeterminado es astro.config.mjs. Usa esta opción si usas un nombre diferente en el archivo de configuración o si tienes tu archivo de configuración en otra carpeta.

Ventana de terminal
astro --config config/astro.config.mjs dev

Agregado en: astro@3.3.0

Configura el outDir para tu proyecto. Pasar esta bandera anulará el valor de outDir en tu archivo astro.config.mjs, si existe.

Configura el valor de site para tu proyecto. Usando este flag sobreescribirá el valor actual de site en tu archivo astro.config.mjs, si es que existe.

Agregado en: astro@1.4.1

Configura el valor de base para tu proyecto. Usando este flag sobreescribirá el valor actual de base en tu archivo astro.config.mjs, si es que existe.

Especifica en qué puerto se ejecuta el servidor. El valor predeterminado es 4321.

--host [dirección de host opcional]

Sección titulada --host [dirección de host opcional]

Establece qué direcciones IP de red debe escuchar el servidor de desarrollo (es decir, direcciones IP que no son de localhost). Esto puede ser útil para probar tu proyecto en dispositivos locales tales como un teléfono durante el desarrollo.

  • --host - escucha todas las direcciones, incluidas LAN y direcciones públicas
  • --host <dirección-personalizada> - expone la dirección IP especificada en <dirección-personalizada>

Habilita el registro detallado, que es útil al debuggear un problema.

Habilita el registro silencioso, que correrá el servidor sin ninguna salida en la consola.

Usa estas banderas para obtener información sobre la CLI de astro.

Imprime el número de versión de Astro y finaliza el proceso.

Abre automáticamente la aplicación en el navegador al iniciar el servidor. Se le puede pasar un string de URL completo (p. ej. --open http://example.com) o una ruta (p. ej. --open /about) para especificar la URL a abrir.

Imprime un mensaje de ayuda.

Si necesitas más control al ejecutar Astro, el paquete "astro" también exporta APIs para ejecutar los comandos de la CLI de manera programática.

Estas APIs son experimentales y su firma de API puede cambiar. Cualquier actualización se mencionará en el registro de cambios de Astro y la información a continuación siempre mostrará la información actual y actualizada.

El tipo AstroInlineConfig es utilizado por todas las APIs de comandos que se detallan a continuación. Este extiende de la configuración de Astro del usuario:

interface AstroInlineConfig extends AstroUserConfig {
configFile?: string | false;
mode?: "development" | "production";
logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

Tipo: string | false
Por defecto: undefined

Una ruta personalizada al archivo de configuración de Astro.

Si este valor es undefined (predeterminado) o no se establece, Astro buscará un archivo astro.config.(js,mjs,ts) en relación con la root y cargará el archivo de configuración si se encuentra.

Si se establece una ruta relativa, se resolverá en función del directorio de trabajo actual.

Establece a false para deshabilitar la carga de cualquier archivo de configuración.

La configuración en línea proporcionada en este objeto tendrá la mayor prioridad al fusionarse con la configuración de usuario cargada.

Tipo: "development" | "production"
Por defecto: "development" cuando se ejecuta astro dev, "production" cuando se ejecuta astro build

El modo utilizado al compilar tu sitio para generar código “development” o “production”.

Tipo: "debug" | "info" | "warn" | "error" | "silent"
Por defecto: "info"

El nivel de registro para filtrar los mensajes registrados por Astro.

  • "debug": Registrar todo, incluyendo diagnósticos ruidosos de depuración.
  • "info": Registrar mensajes informativos, advertencias y errores.
  • "warn": Registrar advertencias y errores.
  • "error": Registrar solo errores.
  • "silent": Sin registros.

Tipo: (inlineConfig: AstroInlineConfig) => AstroDevServer

Similar a astro dev, ejecuta el servidor de desarrollo de Astro.

import { dev } from "astro";
const devServer = await dev({
root: "./my-project",
});
// Detén el servidor si es necesario
await devServer.stop();

Tipo: (inlineConfig: AstroInlineConfig) => void

Similar a astro build, compila tu sitio para el despliegue.

import { build } from "astro";
await build({
root: "./my-project",
});

Tipo: (inlineConfig: AstroInlineConfig) => AstroPreviewServer

Similar a astro preview, inicia un servidor local para servir el directorio estático dist/.

import { preview } from "astro";
const previewServer = await preview({
root: "./my-project",
});
// Detén el servidor si es necesario
await previewServer.stop();

Tipo: (inlineConfig: AstroInlineConfig) => number

Similar a astro sync, genera tipos de TypeScript para todos los módulos de Astro.

import { sync } from "astro";
const exitCode = await sync({
root: "./my-project",
});
process.exit(exitCode)