Saltearse al contenido
Astro Astro

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.

Comandos astro

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:

Terminal window
# empieza el servidor de desarrollo
npx astro dev

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

Terminal window
npx astro --help

El siguiente mensaje se mostrará en tu terminal:

Terminal window
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.

Scripts package.json

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.

Terminal window
# 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

astro dev

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.

Banderas

Usa estas banderas para personalizar el comportamiento del servidor de desarrollo de Astro. Para banderas compartidas con otros comandos de Astro, puedes ver banderas comunes más abajo.

--port <number>

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

--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>

astro build

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.

astro preview

Inicia un servidor local para servir tus archivos estáticos compilados en dist/.

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.

astro check

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.

📚 Lee más sobre la compatibilidad con TypeScript en Astro.

astro sync

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.

astro add

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

astro docs

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

astro info

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

Terminal window
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

astro telemetry

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:

Terminal window
astro telemetry disable

La telemetría se puede volver a habilitar con:

Terminal window
astro telemetry enable

El comando clear restablece los datos de telemetría:

Terminal window
astro telemetry clear

Banderas Comunes

--root path

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.

Terminal window
astro --root miCarpetaRaiz/miCarpetaDeProyecto dev

--config <path>

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.

Terminal window
astro --config config/astro.config.mjs dev

--outDir <path>

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.

--site <url>

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.

--base <pathname>

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.

--verbose

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

--silent

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

Banderas Globales

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

--version

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

--open

Abre automáticamente la aplicación en el navegador al iniciar el servidor.

--help

Imprime un mensaje de ayuda.

APIs avanzadas (Experimental)

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.

AstroInlineConfig

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";
}

configFile

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.

mode

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”.

logLevel

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.

dev()

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();

build()

Tipo: (inlineConfig: AstroInlineConfig) => void

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

import { build } from "astro";


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

preview()

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();

sync()

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)