Configuración de Astro

Personaliza cómo funciona Astro agregando un archivo astro.config.mjs en tu proyecto. Este es un archivo común en todos los proyectos de Astro; todos los ejemplos oficiales, sean plantillas o temas, cuentan con uno de forma predeterminada.

Lee la referencia de configuración de Astro para obtener una descripción general y completa de todas las opciones de configuración.

Archivo de configuración de Astro

Sección titulada Archivo de configuración de Astro

Un archivo de configuración de Astro válido exporta la configuración usando la exportación default, además recomendamos usar defineConfig para definir la configuración de una manera más fácil.

astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
  // tus opciones de configuración van aquí...
  // https://docs.astro.build/es/reference/configuration-reference/
})

Se recomienda usar defineConfig() para sugerencias de tipos automáticas en el IDE, pero también es opcional. Un archivo de configuración absolutamente mínimo y válido se vería así:

astro.config.mjs

// Ejemplo: Archivo de configuración mínimo y vacío
export default {}

Tipos de archivo de configuración compatibles

Sección titulada Tipos de archivo de configuración compatibles

Astro es compatible con varios formatos de JavaScript para el archivo de configuración como: astro.config.js, astro.config.mjs, astro.config.cjs y astro.config.ts. Recomendamos usar .mjs en la mayoría de los casos o .ts si deseas escribir TypeScript en el archivo de configuración.

La carga del archivo de configuración de TypeScript se maneja usando tsm el cual respetará las opciones de tsconfig de su proyecto.

Resolución del archivo de configuración

Sección titulada Resolución del archivo de configuración

Astro intentará resolver automáticamente el archivo de configuración llamado astro.config.mjs dentro de la raíz del proyecto. Si no se encuentra ningún archivo de configuración en la raíz de su proyecto, se utilizarán las opciones predeterminadas de Astro.

# Ejemplo: Lee la configuración desde ./astro.config.mjs
astro build

Puedes configurar explícitamente un archivo de configuración usando el indicador CLI --config. Este indicador CLI siempre se resuelve con relación a la carpeta de trabajo actual desde donde se ejecutó el comando CLI astro.

# Ejemplo: Lee la configuración de este archivo
astro build --config my-config-file.js

Configurar Intellisense

Sección titulada Configurar Intellisense

Astro recomienda usar defineConfig() en el archivo de configuración. defineConfig() proporciona IntelliSense automático para tu IDE. Los editores como VSCode pueden leer las definiciones de tipo TypeScript y proporcionar sugerencias de tipos JSDoc automáticas, incluso si tu archivo de configuración no está escrito en TypeScript.

astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
  // tus opciones de configuración van aquí...
  // https://docs.astro.build/es/reference/configuration-reference/
})

También puedes proporcionar definiciones de tipo manualmente a VSCode, utilizando la notación JSDoc:

astro.config.mjs

 export default /** @type {import('astro').AstroUserConfig} */ {
  // tus opciones de configuración van aquí...
  // https://docs.astro.build/es/reference/configuration-reference/
}

Referenciando archivos relativos

Sección titulada Referenciando archivos relativos

Si proporcionas una ruta relativa a root o el indicador de CLI --root, Astro lo resolverá desde la carpeta de trabajo actual donde ejecutó el comando CLI astro.

astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
    // Se resuelve a la carpeta "./foo" con relación a la carpeta de trabajo actual
    root: 'foo'
})

Astro resolverá todos los archivos y carpetas relativos a la carpeta raíz del proyecto especificada en el archivo de configuración.

astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
    // Se resuelve a la carpeta "./foo" con relación a la carpeta de trabajo actual
    root: 'foo',
    // Se resuelve a la carpeta "./foo/public" con relación a la carpeta de trabajo actual
    publicDir: 'public',
})

Para hacer referencia a un archivo o carpeta relativo al archivo de configuración, use import.meta.url (a menos que esté escribiendo un archivo common.js astro.config.cjs).

astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
    // Se resuelve a la carpeta "./foo" con relación a este archivo de configuración
    root: new URL("./foo", import.meta.url).toString(),
    // Se resuelve a la carpeta "./public" con relación a este archivo de configuración
    publicDir: new URL("./public", import.meta.url).toString(),
})

Nota

Las propiedades import.meta específicas de Vite, como import.meta.env o import.meta.glob, no son accesibles desde tu archivo de configuración. Recomendamos alternativas como dotenv o fast-glob para estos casos de uso respectivos. Además, las alias de ruta tsconfig no se resolverán. Usa rutas relativas para las importaciones de módulos en este archivo.

Personalización de nombres de archivos compilados

Sección titulada Personalización de nombres de archivos compilados

Para el código procesado por Astro, como archivos JavaScript o CSS importados, puedes personalizar los nombres de los archivos compilados usando entryFileNames, chunkFileNames y assetFileNames usando la configuración vite.build.rollupOptions en tu archivo astro.config.*.

astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          entryFileNames: 'entry.[hash].mjs',
          chunkFileNames: 'chunks/chunk.[hash].mjs',
          assetFileNames: 'assets/asset.[hash][extname]',
        }
      },
    },
  },
})

Esto puede ser útil si tienes scripts con nombres que podrían verse afectados por los bloqueadores de anuncios (por ejemplo, ads.js o google-tag-manager.js).

Variables de entorno

Sección titulada Variables de entorno

Astro evalúa los archivos de configuración antes de cargar los demás archivos. Como tal, no puedes usar import.meta.env para acceder a las variables de entorno que se establecieron en los archivos .env.

Puedes usar process.env en un archivo de configuración para acceder a otras variables de entorno, como las establecidas por la CLI.

También puedes usar el helper de Vite loadEnv para cargar los archivos .env manualmente.

Nota

pnpm no te permite importar módulos que no estén instalados directamente en tu proyecto. Si estás usando pnpm, deberás instalar vite para usar el helper loadEnv.

pnpm add vite --save-dev

astro.config.mjs

import { loadEnv } from "vite";
const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

Referencia de configuración

Sección titulada Referencia de configuración

Lee la referencia de configuración de Astro para obtener una descripción general y completa de todas las opciones de configuración.