API programática de Astro (experimental)

Si necesitas más control al ejecutar Astro, el paquete "astro" exporta APIs para ejecutar programáticamente los comandos de la CLI. También hay dos helpers de astro:config que pueden validar y fusionar configuraciones programáticamente.

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

Comandos

Los siguientes comandos de la CLI pueden ejecutarse programáticamente.

dev()

Type: (inlineConfig: AstroInlineConfig) => Promise<DevServer>

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

import { dev } from "astro";

const devServer = await dev({
  root: "./my-project",
});

// Stop the server if needed
await devServer.stop();

DevServer

export interface DevServer {
  address: AddressInfo;
  handle: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void;
  watcher: vite.FSWatcher;
  stop(): Promise<void>;
}

DevServer.address

Type: AddressInfo

La dirección en la que el servidor de desarrollo está escuchando.

Esta propiedad contiene el valor devuelto por el método net.Server#address() de Node.

DevServer.handle()

Tipo: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void

Un handler para solicitudes HTTP raw de Node. Puedes llamar a handle() con un http.IncomingMessage y un http.ServerResponse en lugar de enviar una solicitud a través de la red.

DevServer.watcher

Type: vite.FSWatcher

El file watcher de Chokidar expuesto por el servidor de desarrollo de Vite.

DevServer.stop()

Type: Promise<void>

Detiene el servidor de desarrollo. Esto cierra todas las conexiones inactivas y deja de escuchar nuevas conexiones.

Devuelve una Promise que se resuelve una vez que todas las solicitudes pendientes se hayan completado y todas las conexiones inactivas se hayan cerrado.

build()

Type: (inlineConfig: AstroInlineConfig, options?: BuildOptions) => Promise<void>

Similar a astro build, construye tu sitio para deployment.

import { build } from "astro";

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

BuildOptions

export interface BuildOptions {
  devOutput?: boolean;
  teardownCompiler?: boolean;
}

BuildOptions.devOutput

Type: boolean
Default: false

Añadido en: astro@5.4.0

Genera un build basado en desarrollo similar al código transformado en astro dev. Esto puede ser útil para testear problemas exclusivos del build con información de debugging adicional incluida.

BuildOptions.teardownCompiler

Type: boolean
Default: true

Añadido en: astro@5.4.0

Desmonta la instancia WASM del compilador después del build. Esto puede mejorar el rendimiento al construir una sola vez, pero puede causar una disminución de rendimiento si se construye múltiples veces seguidas.

Al construir múltiples proyectos en la misma ejecución (ej. durante tests), deshabilitar esta opción puede aumentar enormemente el rendimiento y reducir el uso máximo de memoria a costa de un mayor uso sostenido de memoria.

preview()

Type: (inlineConfig: AstroInlineConfig) => Promise<PreviewServer>

Similar a astro preview, inicia un servidor local para servir el output de tu build.

Si no hay ningún adaptador configurado, el servidor de preview solo servirá los archivos estáticos construidos. Si hay un adaptador configurado, el servidor de preview es proporcionado por el adaptador. Los adaptadores no están obligados a proporcionar un servidor de preview, por lo que esta característica puede no estar disponible dependiendo del adaptador que elijas.

import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// Stop the server if needed
await previewServer.stop();

sync()

Type: (inlineConfig: AstroInlineConfig) => Promise<void>

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

import { sync } from "astro";

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

Utilidades

Las siguientes utilidades pueden ser importadas desde astro/config y usadas para manipular o validar la configuración antes de pasarla a los comandos de la CLI.

mergeConfig()

Tipo: (defaults: AstroConfig, overrides: DeepPartial<AstroConfig>) => AstroConfig

Añadido en: astro@5.4.0

Toma un objeto de configuración de Astro y un objeto parcial que contiene cualquier conjunto de opciones de configuración válidas de Astro, y devuelve una configuración de Astro válida combinando ambos valores tal que:

• Los arrays se concatenan (incluyendo integraciones).
• Los objetos se fusionan recursivamente.
• Las opciones de Vite se fusionan usando la propia función mergeConfig() de Vite con el flag por defecto isRoot.
• Las opciones que pueden proporcionarse como funciones se envuelven en nuevas funciones que fusionan recursivamente los valores devueltos de ambas configuraciones con estas mismas reglas.
• Todas las demás opciones sobrescriben la configuración existente.

import { mergeConfig } from "astro/config";

mergeConfig(
  {
    output: "static",
    site: "https://example.com",
    integrations: [partytown()],
    server: ({command}) => ({
      port: command === "dev" ? 4321 : 1234,
    }),
    build: {
      client: "./custom-client",
    },
  },
  {
    output: "server",
    base: "/astro",
    integrations: [mdx()],
    server: ({command}) => ({
      host: command === "dev" ? "localhost" : "site.localhost",
    }),
    build: {
      server: "./custom-server",
    },
  }
);

// Result is equivalent to:
{
  output: "server",
  site: "https://example.com",
  base: "/astro",
  integrations: [partytown(), mdx()],
  server: ({command}) => ({
    port: command === "dev" ? 4321 : 1234,
    host: command === "dev" ? "localhost" : "site.localhost",
  }),
  build: {
    client: "./custom-client",
    server: "./custom-server",
  },
}

validateConfig()

Type: (userConfig: any, root: string, cmd: string) => Promise<AstroConfig>

Añadido en: astro@5.4.0

Valida un objeto como si fuera exportado desde astro.config.mjs e importado por Astro. Esto toma los siguientes argumentos:

• La configuración a validar.
• El directorio raíz del proyecto.
• El comando de Astro que se está ejecutando (ej. build, dev, sync)

La promesa devuelta se resuelve con la configuración validada, rellena con todos los valores por defecto apropiados para el comando de Astro dado.

import { validateConfig } from "astro/config";

const config = await validateConfig({
  integrations: [partytown()],
}, "./my-project", "build");

// defaults are applied
await rm(config.outDir, { recursive: true, force: true });

Tipos de astro

import type {
  AstroInlineConfig,
  PreviewServer,
} from "astro";

AstroInlineConfig

El tipo AstroInlineConfig es usado por todas las APIs de comandos. Se extiende del tipo de configuración de Astro del usuario:

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

AstroInlineConfig.configFile

Type: string | false
Default: undefined

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

Si este valor es undefined (por defecto) o no está establecido, Astro buscará un archivo astro.config.(js,mjs,ts,mts) relativo al root y cargará el archivo de configuración si lo encuentra.

Si se establece una ruta relativa, se resolverá basándose en la opción root.

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

La configuración inline pasada en este objeto tendrá la máxima prioridad al fusionarse con la configuración de usuario cargada.

AstroInlineConfig.mode

Tipo: string
Por defecto: "development" al ejecutar astro dev, "production" al ejecutar astro build

Añadido en: astro@5.0.0

El modo usado al desarrollar o construir tu sitio (ej. "production", "testing").

Este valor se pasa a Vite usando el flag --mode cuando se ejecutan los comandos astro build o astro dev para determinar el valor de import.meta.env.MODE. Esto también determina qué archivos .env se cargan, y por tanto los valores de astro:env. Ver la página de variables de entorno para más detalles.

Para generar un build basado en desarrollo, puedes ejecutar astro build con el flag --devOutput.

AstroInlineConfig.logLevel

Type: "debug" | "info" | "warn" | "error" | "silent"
Default: "info"

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

• "debug": Registra todo, incluyendo diagnósticos de debugging ruidosos.
• "info": Registra mensajes informativos, advertencias y errores.
• "warn": Registra advertencias y errores.
• "error": Registra solo errores.
• "silent": Sin logging.

PreviewServer

export interface PreviewServer {
  host?: string;
  port: number;
  closed(): Promise<void>;
  stop(): Promise<void>;
}

PreviewServer.host

Type: string

El host donde el servidor está escuchando conexiones.

Los adaptadores pueden dejar este campo sin establecer. El valor de host es específico de la implementación.

PreviewServer.port

Type: number

El puerto donde el servidor está escuchando conexiones.

PreviewServer.stop()

Type: Promise<void>

Pide al servidor de preview que se cierre, deje de aceptar solicitudes, y suelte las conexiones inactivas.

La Promise devuelta se resuelve cuando la solicitud de cierre ha sido enviada. Esto no significa que el servidor se haya cerrado todavía. Usa el método closed() si necesitas asegurar que el servidor se ha cerrado completamente.

PreviewServer.closed()

Type: Promise<void>

Devuelve una Promise que se resolverá una vez que el servidor esté cerrado y se rechazará si ocurre un error en el servidor.