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:

# empieza el servidor de desarrollo
npx astro dev

# empieza el servidor de desarrollo
pnpm astro dev

# empieza el servidor de desarrollo
yarn astro dev

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

npx astro --help

pnpm astro --help

yarn astro --help

El siguiente mensaje se mostrará en tu 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.

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.

{
  "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.

# 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

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

# ejecuta el servidor de desarrollo en el puerto 8080 usando el script `start` en `package.json`
yarn start --port 8080
# compila tu sitio con registros detallados usando el script `build` en `package.json`
yarn 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.

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

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

Flags

Utilice estas flags para personalizar el comportamiento del comando.

`--watch`

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

Leer más sobre verificación de tipos 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 los módulos para características que dependen de tipos generados:

El módulo astro:content para la API de Colecciones de Contenido.
El módulo astro:db para Astro DB.

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

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

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:

astro preferences disable devToolbar

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

astro preferences disable --global devToolbar

La devToolbar se puede activar más tarde con:

astro preferences enable devToolbar

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

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.

astro preferences list

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

astro telemetry disable

La telemetría se puede volver a habilitar con:

astro telemetry enable

El comando reset restablece los datos de telemetría:

astro telemetry reset

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.

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.

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.

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

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

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

CLI de Astro Studio

`astro login`

Autenticarse con Astro Studio. Esto es necesario para ejecutar todos los comandos de gestión de bases de datos, incluido astro link.

`astro link`

Enlaza tu base de datos alojada en Studio. Esto es necesario para ejecutar comandos de Astro DB para la gestión de bases de datos. Para enlazar una base de datos, se te pedirá que selecciones una base de datos existente o que crees una nueva.

`astro logout`

Cierra la sesión de Astro Studio y elimina cualquier clave de autenticación almacenada localmente.

Comandos del CLI

Comandos astro

Scripts package.json

astro dev

astro build

astro preview

astro check

Flags

--watch

astro sync

astro add

astro docs

astro info

astro preferences

astro telemetry

Banderas Comunes

--root path

--config <path>

--outDir <path>

--site <url>

--base <pathname>

--port <number>

--host [dirección de host opcional]

--verbose

--silent