Referencia de configuración

La siguiente referencia cubre todas las opciones de configuración compatibles en Astro. Para obtener más información sobre la configuración de Astro, lea nuestra guía sobre configuración de Astro.

astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
  // tus opciones de configuración aquí...
})

Tipo: string
CLI: --root
Por defecto: "." (carpeta de trabajo actual)

Solo debes proporcionar esta opción si ejecutas los comandos CLI astro en una carpeta que no sea la carpeta raíz del proyecto. Por lo general, esta opción se proporciona a través de la CLI en lugar del archivo de configuración de Astro, ya que Astro necesita conocer la raíz de tu proyecto antes de que pueda localizar su archivo de configuración.

Si proporcionas una ruta relativa (p. ej., --root: './my-project'), Astro la resolverá en tu directorio de trabajo actual.

{
  root: './my-project-directory',
}
$ astro build --root ./my-project-directory

Tipo: string
Por defecto: "./src"

Establece la carpeta desde el cual Astro leerá tu proyecto.

El valor puede ser una ruta absoluta del sistema de archivos o una ruta relativa a la raíz del proyecto.

{
  srcDir: './www',
}

Tipo: string
Por defecto: "./public"

Establece la carpeta para los activos estáticos. Los archivos en esta carpeta se sirven desde / durante el desarrollo y se copian en la carpeta de compilación durante la compilación. Estos archivos siempre se sirven o se copian tal cual, sin transformación ni empaquetamiento.

El valor puede ser una ruta absoluta del sistema de archivos o una ruta relativa a la raíz del proyecto.

{
  publicDir: './my-custom-publicDir-directory',
}

Tipo: string
Por defecto: "./dist"

Establece la carpeta en la que astro build escribe la compilación final.

El valor puede ser una ruta absoluta del sistema de archivos o una ruta relativa a la raíz del proyecto.

{
  outDir: './my-custom-build-directory',
}

Tipo: string

La URL final donde se desplegará. Astro usa esta URL completa para generar el sitemap y las URL canónicas en la compilación final. Se recomienda establecer esta configuración para aprovechar al máximo Astro.

{
  site: 'https://www.my-site.dev',
}

Tipo: string

La ruta base en la que se desplegará. Astro coincidirá esta ruta durante el desarrollo para que tu experiencia de desarrollo coincida con el entorno de desarrollo lo más cercano posible. En el siguiente ejemplo, astro dev iniciará el servidor en /docs.

{
  base: '/docs',
}

Tipo: 'always' | 'never' | 'ignore'
Por defecto: 'ignore'

Establece el comportamiento de coincidencia de rutas del servidor de desarrollo. Elige entre las siguientes opciones:

  • 'always': solo coincide con las URL que incluyen una barra inclinada al final (por ejemplo: “/foo/“)
  • 'never': nunca haga coincidir las URL que incluyen una barra inclinada al final (por ejemplo: “/foo”)
  • 'ignore': coincide con las URL independientemente de si existe un ”/” final

Utiliza esta opción de configuración si tu host de producción tiene un manejo estricto de cómo funcionan o no las barras inclinadas finales.

También puedes configurar esto si prefieres ser más estricto, de modo que las URL con o sin barras diagonales finales no funcionen durante el desarrollo.

{
  // Ejemplo: Requiera una barra inclinada final durante el desarrollo
  trailingSlash: 'always',
}

Vea también:

  • build.format

Tipo: AstroIntegration

Despliega a tu servidor favorito, serverless o edge host con adaptadores de compilación. Importe uno de nuestros adaptadores propios para Netlify, Vercel, y más para incluir a Astro SSR.

Consulte nuestra guía de renderizado en el servidor para obtener más información sobre SSR, y nuestras guías de despliegue para obtener una lista completa de hosts.

import netlify from '@astrojs/netlify/functions';
{
  // Ejemplo: Compila para desplegar en Netlify serverless
   adapter: netlify(),
}

Vea también:

  • output

Tipo: 'static' | 'server'
Default: 'static'

Especifica el tipo de la compilacion.

  • ‘static’: construye un sitio estático para implementarlo en cualquier host estático.
  • ‘server’: construye una aplicación que se implementará en un host compatible con SSR (renderizado en el servidor).
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
})

Vea también:

  • adapter

Tipo: ('file' | 'directory')
Por defecto: 'directory'

Controla el formato del archivo compilado de cada página.

  • Si es ‘file’, Astro generará un archivo HTML (por ejemplo: “/foo.html”) para cada página.
  • Si es ‘directory’, Astro generará un directorio con un archivo index.html anidado (por ejemplo: “/foo/index.html”) para cada página.
{
  build: {
    // Ejemplo: Genera `page.html` en lugar de `page/index.html` durante la compilación.
    format: 'file',
  }
}

La opción build.format indica el valor que Astro.url obtendrá durante la compilación. Si es:

  • directory - Astro.url.pathname incluirá una barra final para imitar el comportamiento de carpetas. Ej.: /foo/.
  • file - Astro.url.pathname incluirá .hmtl. Ej.: /foo.html.

Esto significa que cuando crees URLs relativas usando new URL('./relativa', Astro.url), tendrás un comportamiento consistente entre desarrollo y compilación.

Personaliza el entorno de desarrollo de Astro, utilizado por astro dev y astro preview.

{
  server: { port: 1234, host: true},
}

Para establecer una configuración diferente basada en el comando ejecutar (“dev”, “preview”), también puedes pasar una función a esta opción de configuración.

{
  // Ejemplo: Usa una función para personalizar según el comando
  server: (command) => ({ port: command === 'dev' ? 3000 : 4000 }),
}

Tipo: string | boolean
Por defecto: false

Agregado en: v0.24.0

Establece en qué direcciones de IP el servidor debe escuchar (es decir, direcciones IP no locales).

  • false - no exponer una dirección IP
  • true - escuchar todas las direcciones, incluidas LAN y direcciones públicas
  • [dirección personalizada] - exponer una dirección IP en [dirección personalizada] (por ejemplo, 192.168.0.1)

Tipo: number
Por defecto: 3000

Establece en qué puerto debe escuchar el servidor.

Si el puerto dado ya está en uso, Astro probará automáticamente el siguiente puerto disponible.

{
  server: { port: 8080 },
}

Tipo: boolean
Por defecto: false

Controla si las páginas Markdown de borrador deben incluirse en la compilación.

Una página de Markdown se considera un borrador si incluye draft: true en el frontmatter. Las páginas de borrador siempre se incluyen y son visibles durante el desarrollo (astro dev), pero de forma predeterminada no se incluirán en la compilación final.

{
  markdown: {
    // Ejemplo: Incluye todos los borradores en la compilación final
    drafts: true,
  }
}

Tipo: Partial<ShikiConfig>

Opciones de configuración de Shiki. Consulta la documentación de configuración de Markdown para conocer su uso.

Tipo: 'shiki' | 'prism' | false
Por defecto: shiki

Qué resaltador de sintaxis usar, si lo hay.

  • shiki - usa el resaltador Shiki
  • prism - usa el resaltador Prism
  • false - no aplicar resaltado de sintaxis.
{
  markdown: {
    // Ejemplo: Cambia el resaltado de sintaxis a prism en Markdown
    syntaxHighlight: 'prism',
  }
}

Tipo: RemarkPlugins

Pasa plugins de remark para personalizar la construcción del Markdown. Puedes importar y aplicar la función del plugin (recomendado), o pasar el nombre del plugin como string.

import remarkToc from 'remark-toc';
{
  markdown: {
    remarkPlugins: [remarkToc],
  }
}

Tipo: RehypePlugins

Pasa plugins de rehype para personalizar cómo el HTML generado en compilación es procesado. Puedes importar y aplicar la función del plugin (recomendado), o pasar el nombre del plugin como string.

import rehypeMinifyHtml from 'rehype-minify';
{
  markdown: {
    rehypePlugins: [rehypeMinifyHtml],
  }
}

Tipo: boolean
Por defecto: false

Astro aplica los plugins GitHub-flavored Markdown y Smartypants por defecto. Si deseas añadir tus propios plugins de remark o rehype, puedes mantener los incluidos por defecto, puedes hacerlo estableciendo la flag extendDefaultPlugins con el valor true:

{
  markdown: {
    extendDefaultPlugins: true,
     remarkPlugins: [exampleRemarkPlugin],
    rehypePlugins: [exampleRehypePlugin],
  }
}

Tipo: RemarkRehype

Puedes pasar opciones a remark-rehype.

{
  markdown: {
    // Ejemplo: Traduce el texto de las notas de pie a otro idioma, por ejemplo aquí están en Español
    remarkRehype: { footnoteLabel: "Notas de pie", footnoteBackLabel: "Volver al contenido"},
  }
}

Extiende Astro con integraciones personalizadas. Las integraciones sirven para agregar soporte a frameworks (como Solid.js), nuevas funcionalidades (sitemaps) y nuevas bibliotecas (como Partytown y Turbolinks).

Consulta nuestra guía de integraciones para obtener ayuda para comenzar con integraciones de Astro.

import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // Ejemplo: Agrega compatibilidad con React + Tailwind a Astro
  integrations: [react(), tailwind()],
}

Pasa opciones de configuración adicionales a Vite. Útil cuando Astro no admite alguna configuración avanzada que pueda necesitar.

Consulta la documentación completa del objeto de configuración vite en vitejs.dev.

{
  vite: {
    ssr: {
      // Ejemplo: Obliga a un paquete roto a omitir el procesamiento de SSR, si es necesario
      external: ['broken-npm-package'],
    }
  }
}
{
  vite: {
    // Ejemplo: Agrega plugins de vite personalizados directamente a tu proyecto de Astro
    plugins: [myPlugin()],
  }
}

Para ayudar a algunos usuarios a migrar entre versiones de Astro, ocasionalmente introducimos flags legacy. Estas flags te permiten optar por algunos comportamientos desactualizados u obsoletos de Astro en la última versión, para que pueda continuar actualizándose y aprovechar los nuevos lanzamientos de Astro.

Tipo: boolean
Por defecto: false

Agregado en: v1.0.0-rc.1

Habilita el soporte anterior a v1.0 de Astro para componentes y expresiones JSX en archivos Markdown .md. En Astro 1.0.0-rc, este comportamiento original se eliminó como predeterminado, a favor de nuestra nueva integración MDX (EN).

Para habilitar este comportamiento, establece legacy.astroFlavoredMarkdown en true en el archivo de configuración astro.config.mjs.

{
  legacy: {
    // Ejemplo: Agrega soporte para funcionalidades de Markdown obsoletas
    astroFlavoredMarkdown: true,
  }
}