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, consulta nuestra guía sobre configuración de Astro.

import { defineConfig } from 'astro/config'

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

Opciones de nivel superior

site

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',
}

base

Tipo: string

La ruta base en la que se desplegará. Astro usará esta ruta como la raíz para tus páginas y activos en desarrollo y producción.

En el ejemplo de abajo, astro dev empezará tu servidor en /docs.

{
  base: '/docs',
}

Cuando utilices esta opción, todas tus importaciones de activos estáticos y URL deben agregar la base como prefijo. Puedes acceder a este valor a través de import.meta.env.BASE_URL.

El valor de import.meta.env.BASE_URL se determinará según la configuración de trailingSlash, sin importar el valor que hayas establecido para base.

Se incluirá una barra diagonal al final siempre que se establezca trailingSlash: "always". Si se establece trailingSlash: "never", BASE_URL no incluirá una barra diagonal al final, incluso si base la incluye.

Además, Astro manipulará internamente el valor configurado de config.base antes de ponerlo a disposición de las integraciones. El valor de config.base tal como lo leen las integraciones también se determinará según la configuración de trailingSlash de la misma manera.

En el siguiente ejemplo, los valores de import.meta.env.BASE_URL y config.base, al ser procesados, serán ambos /docs:

{
   base: '/docs/',
   trailingSlash: "never"
}

En el siguiente ejemplo, los valores de import.meta.env.BASE_URL y config.base, al ser procesados, serán ambos /docs/:

{
   base: '/docs',
   trailingSlash: "always"
}

trailingSlash

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',
}

Ver también:

build.format

redirects

Tipo: Record.<string, RedirectConfig>
Por defecto: {}

Agregado en: astro@2.9.0

Especifica un mapeo de redirecciones donde la clave es la ruta a coincidir y el valor es la ruta a la que se redirige.

Puedes redirigir tanto rutas estáticas como dinámicas, pero solo a un tipo de ruta similar. Por ejemplo, no puedes tener una redirección '/article': '/blog/[...slug]'.

{
  redirects: {
    '/old': '/new',
    '/blog/[...slug]': '/articles/[...slug]',
  }
}

Para sitios generados estáticamente sin un adaptador instalado, esto producirá una redirección del cliente utilizando una etiqueta <meta http-equiv="refresh"> y no admitirá códigos de estado.

Cuando se utiliza SSR o un adaptador estático en el modo output: static, se admiten los códigos de estado. Astro servirá las solicitudes GET redirigidas con un estado 301 y utilizará un estado 308 para cualquier otro método de solicitud.

Puedes personalizar el código de estado de redirección utilizando un objeto en la configuración de redirección:

{
  redirects: {
    '/other': {
      status: 302,
      destination: '/place',
    },
  }
}

output

Tipo: 'static' | 'server' | 'hybrid'
Por defecto: 'static'

Especifica el tipo de la compilación.

'static': Construye un sitio estático para ser implementado en cualquier host estático.
'server': Construye una aplicación que se implementará en un host compatible con SSR (renderizado en el servidor).
'hybrid' : Construye un sitio estático con algunas páginas renderizadas en el lado del servidor.

import { defineConfig } from 'astro/config';

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

Ver también:

adapter

adapter

Tipo: AstroIntegration

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

Consulta 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';
{
 // Ejemplo: Compila para desplegar en Netlify serverless
 adapter: netlify(),
}

Ver también:

output

integraciones

Tipo: AstroIntegration[]

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

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()],
}

root

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.

Ejemplos

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

$ astro build --root ./my-project-directory

srcDir

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',
}

publicDir

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',
}

outDir

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',
}

Ver también:

build.server

cacheDir

Tipo: string
Por defecto: "./node_modules/.astro"

Establece el directorio para almacenar en caché los artefactos de compilación. Los archivos de este directorio se utilizarán en compilaciones posteriores para acelerar el tiempo de compilación.

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

{
  cacheDir: './my-custom-cache-directory'
}

compressHTML

Tipo: boolean
Por defecto: true

Esta es una opción para minificar tu salida HTML y reducir el tamaño de tus archivos HTML. Por defecto, Astro elimina todos los espacios en blanco de tu HTML, incluyendo los saltos de línea, en los componentes .astro. Esto ocurre tanto en el modo de desarrollo como en la compilación final. Para desactivar la compresión del HTML, establece el parámetro compressHTML en false.

{
  compressHTML: false
}

scopedStyleStrategy

Tipo: 'where' | 'class' | 'attribute'
Por defecto: 'attribute'

Agregado en: astro@2.4.0

Especifica la estrategia utilizada para delimitar los estilos dentro de los componentes de Astro. Elige entre:

'where' - Utilizar selectores :where, sin que aumente la especificidad.
'class' - Utilizar selectores basados en clases, lo que provoca un aumento de la especificidad de +1.
'attribute' - Utilizar atributos data-, sin aumentar la especificidad a +1.

Utilizar 'class' es útil cuando quieres asegurar que los selectores de elementos dentro de un componente de Astro anulan los valores predeterminados de estilo global (p. ej. de una hoja de estilos global). Utilizar 'where' te brinda más control sobre la especificidad, pero requiere que utilices selectores de mayor especificidad, capas y otras herramientas para controlar qué selectores se aplican. Utilizar 'attribute' es útil cuando estás manipulando el atributo class de elementos y necesitas evitar conflictos entre tu lógica de estilo y la aplicación de estilos de Astro.

security

Tipo: boolean
Por defecto: {}

Agregado en: astro@4.9.0

Activa medidas de seguridad para un sitio web Astro.

Estas funciones solo existen para páginas renderizadas bajo demanda (SSR) usando el modo server o páginas que optan por no prerrenderizarse en modo hybrid.

export default defineConfig({
  output: "server",
  security: {
    checkOrigin: true
  }
})

security.checkOrigin

Tipo: boolean
Por defecto: ‘false’

Agregado en: astro@4.9.0

Cuando está habilitado, realiza una verificación para asegurar que el encabezado “origin”, que es automáticamente proporcionado por todos los navegadores modernos, coincida con la URL enviada por cada Request. Esto se utiliza para proporcionar protección contra Cross-Site Request Forgery (CSRF). La verificación del encabezado “origin” se ejecuta únicamente para páginas renderizadas bajo demanda, y solo para las solicitudes POST, PATCH, DELETE y PUT que utilicen uno de los siguientes encabezados content-type: 'application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain'.

Si el encabezado “origin” no coincide con el pathname de la solicitud, Astro devolverá un código de estado 403 y no renderizará la página.

vite

Tipo: ViteUserConfig

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 vite.dev.

Ejemplos

{
  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()],
  }
}

Opciones de Build

build.format

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

Controla el formato del archivo compilado de cada página. Este valor puede ser establecido por un adaptador para ti.

'file': Astro generará un archivo HTML con el nombre de cada ruta de página. (p. ej. src/pages/about.astro y src/pages/about/index.astro generan el archivo /about.html)
'directory': Astro generará un directorio con un archivo index.html anidado para cada página. (p. ej. src/pages/about.astro y src/pages/about/index.astro generan el archivo /about/index.html)
'preserve': Astro generará archivos HTML exactamente como aparecen en tu carpeta de origen. (p. ej. src/pages/about.astro genera /about.html y src/pages/about/index.astro genera el archivo /about/index.html)

{
  build: {
    // Ejemplo: Genera `page.html` en lugar de `page/index.html` durante la compilación.
    format: 'file',
  }
}

Efecto en Astro.url

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.

Para evitar inconsistencias con el comportamiento de la barra diagonal final en desarrollo, puedes restringir la opción trailingSlash a 'always' o 'never' dependiendo del formato de compilación:

directory - Establece trailingSlash: 'always'
file - Establece trailingSlash: 'never'

build.client

Tipo: string
Por defecto: './dist/client'

Controla el directorio de salida del CSS y JavaScript del lado del cliente solamente cuando esté configurado output: 'server' o output: 'hybrid'. outDir controla dónde se compila el código.

Este valor es relativo al outDir.

{
  output: 'server', // o 'hybrid'
  build: {
    client: './client'
  }
}

build.server

Tipo: string
Por defecto: './dist/server'

Controla el directorio de salida del JavaScript del servidor cuando compila a SSR.

Este valor es relativo al outDir.

{
  build: {
    server: './server'
  }
}

build.assets

Tipo: string
Por defecto: '_astro'

Agregado en: astro@2.0.0

Especifica el directorio en la salida de compilación donde los activos generados por Astro (por ejemplo, JS y CSS empaquetados) deben ir.

{
  build: {
    assets: '_custom'
  }
}

Ver también:

outDir

build.assetsPrefix

Tipo: string | Record.<string, string>
Por defecto: undefined

Agregado en: astro@2.2.0

Especifica el prefijo para los enlaces de activos generados por Astro. Esto se puede usar si los activos se sirven desde un dominio diferente al del sitio actual.

Para ello, es necesario cargar los activos de la carpeta local ./dist/_astro en la carpeta correspondiente /_astro/ del dominio remoto.

Para cambiar el nombre de la ruta _astro, especifique un nuevo directorio en build.assets.

Para recuperar todos los assets cargados en el mismo dominio (por ejemplo, https://cdn.example.com/_astro/...), establece assetsPrefix en el dominio raíz como un string (independientemente de tu configuración base):

{
  build: {
    assetsPrefix: 'https://cdn.example.com'
  }
}

Añadido en: astro@4.5.0

También puedes pasar un objeto a assetsPrefix para especificar un dominio diferente para cada tipo de fichero. En este caso, se requiere una propiedad fallback que se utilizará por defecto para cualquier otro archivo.

{
  build: {
    assetsPrefix: {
      'js': 'https://js.cdn.example.com',
      'mjs': 'https://js.cdn.example.com',
      'css': 'https://css.cdn.example.com',
      'fallback': 'https://cdn.example.com'
    }
  }
}

build.serverEntry

Tipo: string
Por defecto: 'entry.mjs'

Especifica el nombre de archivo del punto de entrada al servidor cuando compila a SSR. Este punto de entrada suele depender del host al que estés desplegando y será configurado por el adaptador que estés utilizando.

Ten en cuenta que se recomienda que este archivo tenga la extensión .mjs así el runtime detecta que el archivo es un módulo de JavaScript.

{
  build: {
    serverEntry: 'main.mjs'
  }
}

build.redirects

Tipo: boolean
Por defecto: true

Agregado en: astro@2.6.0

Especifica si las redirecciones se generarán en HTML durante la compilación. Esta opción solo se aplica al modo output: 'static'; en SSR, las redirecciones se tratan de la misma manera que todas las respuestas.

Esta opción está destinada principalmente a ser utilizada por adaptadores que tienen archivos de configuración especiales para redirecciones y no necesitan/desean redirecciones basadas en HTML.

{
  build: {
    redirects: false
  }
}

build.inlineStylesheets

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

Agregado en: astro@2.6.0

Controla si los estilos del proyecto se envían al navegador en un archivo CSS separado o se incrustan en etiquetas <style>. Elige entre las siguientes opciones:

'always' - los estilos del proyecto se incrustan en etiquetas <style>.
'auto' - solo las hojas de estilo más pequeñas que ViteConfig.build.assetsInlineLimit (por defecto: 4 kB) se incrustan. De lo contrario, los estilos se envían en hojas de estilo externas.
'never' - los estilos del proyecto se envían en hojas de estilo externas.

{
  build: {
    inlineStylesheets: `never`,
  },
}

Opciones del Servidor

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' ? 4321 : 4000 }),
}

server.host

Tipo: string | boolean
Por defecto: false

Agregado en: astro@0.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)

server.port

Tipo: number
Por defecto: 4321

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

server.open

Tipo: string | boolean
Por defecto: false

Agregado en: astro@4.1.0

Controla si el servidor de desarrollo debe abrirse en la ventana de tu navegador al iniciar.

Pasa un string de URL completo (p. ej. ”http://example.com”) o una ruta (p. ej. “/about”) para especificar el URL a abrir.

{
  server: { open: "/about" }
}

server.headers

Tipo: OutgoingHttpHeaders
Por defecto: {}

Agregado en: astro@1.7.0

Establece encabezados de respuesta HTTP personalizados para enviar en astro dev y astro preview.

Opciones de la barra de herramientas de desarrollo

devToolbar.enabled

Tipo: boolean
Por defecto: true

Si deseas activar la barra de herramientas de Astro Dev. Esta barra de herramientas te permite inspeccionar las islas de tu página, ver auditorías útiles sobre rendimiento y accesibilidad, y mucho más.

Esta opción se aplica a todo el proyecto, para desactivar la barra de herramientas sólo para ti, ejecuta npm run astro preferences disable devToolbar. Para desactivar la barra de herramientas para todos tus proyectos de Astro, ejecuta npm run astro preferences disable devToolbar --global.

Opciones de Precarga

Tipo: boolean | object

Habilita la precarga de enlaces en tu sitio para proporcionar transiciones de página más rápidas. (Activado de forma predeterminada en las páginas que utilizan el router <ViewTransitions />. Establece prefetch: false para optar por no utilizar este comportamiento.)

Esta configuración agrega automáticamente un script de precarga a cada página del proyecto dandote acceso al atributo data-astro-prefetch. Agrega este atributo a cualquier enlace <a /> en tu página para habilitar el prefetching para esa página.

<a href="/about" data-astro-prefetch>Acerca</a>

Para personalizar aún más el comportamiento predeterminado de precarga puedes usar las opciones prefetch.defaultStrategy y prefetch.prefetchAll.

Consulta la guía de Prefetch para obtener más información.

prefetch.prefetchAll

Tipo: boolean

Habilita la precarga para todos los enlaces, incluidos aquellos sin el atributo data-astro-prefetch. El valor predeterminado es true cuando se utiliza el router <ViewTransitions />. De lo contrario, el valor predeterminado es false.

prefetch: {
  prefetchAll: true
}

Cuando se establece en true, puedes deshabilitar el prefetching individualmente estableciendo data-astro-prefetch="false" en cualquier enlace individual.

<a href="/about" data-astro-prefetch="false">About</a>

prefetch.defaultStrategy

Tipo: 'tap' | 'hover' | 'viewport' | 'load'
Por defecto: 'hover'

La estrategia de precarga predeterminada para utilizar cuando el atributo data-astro-prefetch está establecido en un enlace sin valor.

'tap': Precarga justo antes de hacer clic en el enlace.
'hover': Precarga cuando pasas el cursor o te enfocas en el enlace. (predeterminada)
'viewport': Precarga cuando los enlaces entran en el viewport.
'load': Precarga todos los enlaces en la página después de que la página se ha cargado.

Puedes reemplazar este valor predeterminado y seleccionar una estrategia diferente para cualquier enlace individual estableciendo un valor en el atributo.

<a href="/about" data-astro-prefetch="viewport">Acerca de</a>

Opciones de Imagen

image.endpoint

Tipo: string
Por defecto: undefined

Agregado en: astro@3.1.0

Configura el endpoint a utilizar para la optimización de imágenes en desarrollo y SSR. Establece undefined para utilizar el endpoint por defecto.

El endpoint siempre se inyectará en /_image.

{
  image: {
    // Ejemplo: Usa un endpoint de imagen personalizado
    endpoint: './src/image-endpoint.ts',
  },
}

image.service

Tipo: Object
Por defecto: {entrypoint: 'astro/assets/services/sharp', config?: {}}

Agregado en: astro@2.1.0

Establece qué servicio de imágenes se utiliza para el soporte de assets de Astro.

El valor debe ser un objeto con un punto de entrada para el servicio de imagen a utilizar y, opcionalmente, un objeto configuración para pasar al servicio.

El punto de entrada del servicio puede ser uno de los servicios incluidos o un paquete de terceros.

{
  image: {
    // Example: Habilita el servicio de imágenes basado en Sharp con una configuración personalizada
    service: {
       entrypoint: 'astro/assets/services/sharp',
       config: {
         limitInputPixels: false,
      },
     },
  },
}

image.service.config.limitInputPixels

Tipo: number | boolean
Por defecto: true

Agregado en: astro@4.1.0

Limitar o no el tamaño de las imágenes que procesará el servicio de imágenes Sharp.

Establece false para omitir el límite de tamaño de imagen por defecto para el servicio de imágenes Sharp y procesar imágenes grandes.

image.domains

Tipo: Array.<string>
Por defecto: {domains: []}

Agregado en: astro@2.10.10

Define una lista de dominios de origen de imágenes permitidos para la optimización de imágenes remotas. No se optimizarán otras imágenes remotas por Astro.

Esta opción require un arreglo de nombres de dominio individuales como strings. Los comodines no están permitidos. En su lugar, usa image.remotePatterns para definir una lista de patrones de URL de origen permitidos.

{
  image: {
    // Ejemplo: Permite la optimización de imágenes remotas desde un solo dominio
    domains: ['astro.build'],
  },
}

image.remotePatterns

Tipo: Array.<RemotePattern>
Por defecto: {remotePatterns: []}

Agregado en: astro@2.10.10

Define una lista de patrones de URL de origen permitidos para la optimización de imágenes remotas.

remotePatterns pueden ser configurados con cuatro propiedades:

protocol
hostname
port
pathname

{
  image: {
    // Ejemplo: permite el procesamiento de todas las imágenes de tu bucket de aws s3
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}

Puedes usar comodines para definir los valores hostname y pathname permitidos como se describe a continuación. De lo contrario, solo se configurarán los valores exactos proporcionados: hostname:

Empiezar con ’**.’ para permitir todos los subdominios (‘endsWith’).
Empiezar con ’*.’ para permitir solo un nivel de subdominio.

pathname:

Terminar con ’/**’ para permitir todas las sub-rutas (‘startsWith’).
Terminar con ’/*’ para permitir solo un nivel de sub-ruta.

Opciones de Markdown

markdown.shikiConfig

Tipo: Partial<ShikiConfig>

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

markdown.syntaxHighlight

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',
  }
}

markdown.remarkPlugins

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],
  }
}

markdown.rehypePlugins

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 { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis]
  }
}

markdown.gfm

Tipo: boolean
Por defecto: true

Agregado en: astro@2.0.0

Astro usa GitHub-flavored Markdown por defecto. Para deshabilitarlo, establece la flag gfm a false:

{
  markdown: {
    gfm: false,
  }
}

markdown.smartypants

Tipo: boolean
Por defecto: true

Agregado en: astro@2.0.0

Astro usa el formateador SmartyPants por defecto. Para deshabilitarlo, establezca la propiedad smartypants a false:

{
  markdown: {
    smartypants: false,
  }
}

markdown.remarkRehype

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 a la referencia 1"},
  }
}

i18n

Tipo: object

Agregado en: astro@3.5.0

Configura el enrutamiento i18n y te permite especificar algunas opciones de personalización.

Consulta nuestra guía para obtener más información sobre la internacionalización en Astro

i18n.defaultLocale

Tipo: string

Agregado en: astro@3.5.0

El idioma predeterminado de tu sitio/aplicación. Este es un campo obligatorio.

Ningún formato o sintaxis de idioma en particular está obligado, pero sugerimos usar minúsculas y guiones según sea necesario (por ejemplo, “es”, “pt-br”) para una mayor compatibilidad.

i18n.locales

Tipo: Locales

Agregado en: astro@3.5.0

Una lista de todos los idiomas admitidos por el sitio web, incluyendo el defaultLocale. Este es un campo obligatorio.

Los idiomas pueden enumerarse como códigos individuales (por ejemplo, ['en', 'es', 'pt-br']) o asignarse a una ruta compartida de códigos (por ejemplo, { path: "english", code: ["en", "en-US"]}). Estos códigos se utilizarán para determinar la estructura de URL de tu sitio desplegado.

No se impone ningún formato o sintaxis de código de idioma en particular, pero las carpetas de tu proyecto que contengan tus archivos de contenido deben coincidir exactamente con los elementos locales de la lista. En caso de que varios códigos apunten a un prefijo de ruta URL personalizado, almacena los archivos de contenido en una carpeta con el mismo nombre que la ruta configurada.

i18n.fallback

Tipo: Record.<string, string>

Agregado en: astro@3.5.0

La estrategia de reserva cuando se navega a páginas que no existen (por ejemplo, no se ha creado una página traducida).

Usa este objeto para declarar una ruta de locale de reserva para cada idioma que admitas. Si no se especifica una reserva, las páginas no disponibles devolverán un 404.

Ejemplo

El siguiente ejemplo configura tu estrategia de reserva de contenido para redirigir las páginas no disponibles en /pt-br/ a su versión es, y las páginas no disponibles en /fr/ a su versión en. Las páginas no disponibles en /es/ devolverán un 404.

export default defineConfig({
  experimental: {
    i18n: {
      defaultLocale: "en",
      locales: ["en", "fr", "pt-br", "es"],
      fallback: {
        pt: "es",
        fr: "en"
      }
    }
  }
})

i18n.routing

Tipo: Routing

Agregado en: astro@3.7.0

Controla la estrategia de enrutamiento para determinar las URLs de tu sitio. Establécelo en función de la configuración de la ruta de la carpeta/URL para tu idioma predeterminado.

i18n.routing.prefixDefaultLocale

Tipo: boolean
Por defecto: false

Agregado en: astro@3.7.0

Cuando es false, sólo los idiomas no predeterminados mostrarán un prefijo de idioma. El defaultLocale no mostrará un prefijo de idioma y los archivos de contenido no existen en una carpeta localizada. Las URLs tendrán la forma example.com/[lang]/content/ para todos los idiomas no predeterminados, pero example.com/content/ para la configuración regional predeterminada.

Cuando es true, todas las URLs mostrarán un prefijo de idioma. Las URLs serán de la forma example.com/[lang]/content/ para cada ruta, incluyendo el idioma por defecto. Se utilizan carpetas localizadas para cada idioma, incluido el predeterminado.

i18n.routing.redirectToDefaultLocale

Tipo: boolean
Por defecto: true

Agregado en: astro@4.2.0

Configura si la URL de inicio (/) generada por src/pages/index.astro se redireccionará a /[defaultLocale] cuando prefixDefaultLocale: true está configurado.

Establece redirectToDefaultLocale: false para desactivar esta redirección automática en la raíz de tu sitio:

export default defineConfig({
  i18n:{
    defaultLocale: "en",
    locales: ["en", "fr"],
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: false
    }
  }
})

i18n.routing.manual

Tipo: string

Agregado en: astro@4.6.0

Cuando esta opción está habilitada, Astro desactivará su middleware de internacionalización (i18n) para que puedas implementar tu propia lógica. No se pueden configurar otras opciones de routing (Ejemplo: prefixDefaultLocale) cuando se utiliza routing: "manual".

Serás responsable de escribir tu propia lógica de enrutamiento o ejecutar manualmente el middleware de internacionalización (i18n) de Astro junto con tu propia implementación.

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    routing: {
      prefixDefaultLocale: true,
    }
  }
})

Banderas legacy

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

Banderas Experimentales

Astro ofrece banderas experimentales para dar a los usuarios acceso temprano a nuevas características. No se garantiza que estas banderas sean estables.

experimental.directRenderScript

Tipo: boolean
Por defecto: false

Agregado en: astro@4.5.0

Permite una estrategia más fiable para evitar que los scripts se ejecuten en páginas en las que no se utilizan.

Los scripts se renderizarán directamente como se declaren en los archivos Astro (incluyendo características existentes como TypeScript, importación de node_modules, y la deduplicación de scripts). Ahora también puedes renderizar scripts condicionalmente en tu archivo Astro. Sin embargo, esto significa que los scripts ya no se colocan en el <head> y que varios scripts de una página ya no se empaquetan juntos. Si activas esta opción, comprueba que todas las etiquetas <script> se comportan como es debido.

Esta opción se activará por defecto en Astro 5.0.

{
  experimental: {
    directRenderScript: true,
  },
}

experimental.actions

Tipo: boolean
Por defecto: false

Agregado en: astro@4.8.0

Las Acciones te ayudan a escribir funciones de backend seguras que puedes llamar desde cualquier lugar. Habilita el renderizado en servidor usando la propiedad output y añade la bandera actions al objeto experimental:

{
  output: 'hybrid', // or 'server'
  experimental: {
    actions: true,
  },
}

Declara todas tus acciones en src/actions/index.ts. Este archivo es el manejador global de acciones.

Declara una acción utilizando defineAction() del módulo astro:actions. Una acción acepta la propiedad handler para definir tu manejador en el lado del servidor. Si tu acción acepta argumentos, aplica la propiedad input para validar los parámetros con Zod.

Este ejemplo define dos acciones: like y comment. La acción like acepta un objeto JSON con una cadena postId, mientras que la acción comment acepta un objeto FormData con las cadenas postId, author, y body. Cada handler actualiza tu base de datos y devuelve una respuesta de tipo segura.

import { defineAction, z } from "astro:actions";

export const server = {
  like: defineAction({
    input: z.object({ postId: z.string() }),
    handler: async ({ postId }) => {
      // actualiza likes en la base de datos

      return likes;
    },
  }),
  comment: defineAction({
    accept: 'form',
    input: z.object({
      postId: z.string(),
      author: z.string(),
      body: z.string(),
    }),
    handler: async ({ postId }) => {
      // añade comentarios en la base de datos

      return comment;
    },
  }),
};

Luego, llama a una acción desde los componentes cliente usando el objeto actions del módulo astro:actions. Puedes pasar un objeto de tipo seguro cuando uses JSON,o un objeto FormData cuando uses accept: 'form' en la definición de tu acción.

Este ejemplo llama a las acciones like y commentdesde un componente de React:

import { actions } from "astro:actions";
import { useState } from "react";

export function Like({ postId }: { postId: string }) {
  const [likes, setLikes] = useState(0);
  return (
    <button
      onClick={async () => {
        const newLikes = await actions.like({ postId });
        setLikes(newLikes);
      }}
    >
      {likes} likes
    </button>
  );
}

export function Comment({ postId }: { postId: string }) {
  return (
    <form
      onSubmit={async (e) => {
        e.preventDefault();
        const formData = new FormData(e.target as HTMLFormElement);
        const result = await actions.blog.comment(formData);
        // manejar el resultado
      }}
    >
      <input type="hidden" name="postId" value={postId} />
      <label htmlFor="author">Author</label>
      <input id="author" type="text" name="author" />
      <textarea rows={10} name="body"></textarea>
      <button type="submit">Post</button>
    </form>
  );
}

Para obtener una visión completa, y proporcionar comentarios sobre esta API experimental, consulta Actions RFC.

experimental.contentCollectionCache

Tipo: boolean
Default: false

Agregado en: astro@3.5.0

Habilita un caché persistente para las colecciones de contenido cuando se compila en modo estático.

{
  experimental: {
    contentCollectionCache: true,
  },
}

experimental.contentCollectionJsonSchema

Tipo: boolean
Por defecto: false

Agregado en: astro@4.5.0

Esta característica auto-generará un esquema JSON para colecciones de contenido de type: 'data' que puede ser usado como el valor $schema para autocompletar/consejos al estilo TypeScript en herramientas como VSCode.

Para activar esta función, añada el indicador experimental:

import { defineConfig } from 'astro/config';
export default defineConfig({
  experimental: {
    contentCollectionJsonSchema: true
  }
});

Esta implementación experimental requiere referenciar manualmente el esquema en cada fichero de entrada de datos de la colección:

{
  "$schema": "../../../.astro/collections/test.schema.json",
  "test": "test"
}

Alternativamente, puedes establecer esto en tu configuración de VSCode json.schemas:

"json.schemas": [
  {
    "fileMatch": [
      "/src/content/test/**"
    ],
    "url": "./.astro/collections/test.schema.json"
  }
]

Ten en cuenta que esta implementación inicial utiliza una biblioteca con problemas conocidos para esquemas Zod avanzados, por lo que puede que desees consultar estas limitaciones antes de activar la bandera experimental.

experimental.clientPrerender

Tipo: boolean
Por defecto: false

Agregado en: astro@4.2.0

Permite la pre-renderización de tus páginas precargadas en el cliente en navegadores compatibles.

Esta característica utiliza la API experimental de Reglas de Especulación Web y mejora el comportamiento predeterminado de prefetch a nivel global para pre-renderizar enlaces en el cliente. Puede que desees revisar los posibles riesgos al pre-renderizar en el cliente antes de habilitar esta característica.

Habilita la pre-renderización en el lado del cliente en tu archivo astro.config.mjs, junto con cualquier opción de configuración de prefetch deseada:

{
  prefetch: {
    prefetchAll: true,
    defaultStrategy: 'viewport',
  },
  experimental: {
    clientPrerender: true,
  },
}

Continua utilizando el atributo data-astro-prefetch en cualquier enlace <a /> en tu sitio para optar por la precarga. En lugar de añadir una etiqueta <link> a la cabecera del documento o recuperar la página con JavaScript, se agregará una etiqueta <script> con las reglas de especulación correspondientes.

La pre-renderización en el lado del cliente requiere el soporte del navegador. Si la API de Reglas de Especulación no es compatible, prefetch volverá a la estrategia compatible.

Consulta la [Guía de Precargar] para más opciones y uso de prefetch.

experimental.globalRoutePriority

Tipo: boolean
Por defecto: false

Agregado en: astro@4.2.0

Da la misma prioridad a las redirecciones y las rutas inyectadas junto con las rutas del proyecto basadas en archivos, siguiendo las mismas reglas de orden de prioridad de rutas para todas las rutas.

Esto permite más control sobre el enrutamiento en tu proyecto al no priorizar automáticamente ciertos tipos de rutas, y estandariza el orden de prioridad para todas las rutas.

El siguiente ejemplo muestra que ruta construirá ciertas URLs de páginas cuando se combinan rutas basadas en archivos, rutas inyectadas y redirecciones como se muestra a continuación:

Ruta basada en archivos: /blog/post/[pid]
Ruta basada en archivos: /[page]
Ruta inyectada: /blog/[...slug]
Redirección: /blog/tags/[tag] -> /[tag]
Redirección: /posts -> /blog

Con experimental.globalRoutingPriority habilitado (en lugar del orden de prioridad de rutas por defecto de Astro 4.0):

/blog/tags/astro se construye mediante la redirección a /tags/[tag] (en lugar de la ruta inyectada /blog/[...slug])
/blog/post/0 se construye mediante la ruta basada en archivos /blog/post/[pid] (en lugar de la ruta inyectada /blog/[...slug])
/posts se construye mediante la redirección a /blog (en lugar de la ruta basada en archivos /[page])

En caso de colisión de rutas, cuando dos rutas con la misma prioridad intentan construir la misma URL, Astro registrará una advertencia identificando las rutas en conflicto.

experimental.rewriting

Tipo: boolean
Por defecto: false

Agregado en: astro@4.8.0

Habilita una característica de enrutamiento para reescribir solicitudes en páginas de Astro, puntos finales y middleware de Astro, brindándote control programático sobre tus rutas.

{
  experimental: {
    rewriting: true,
  },
}

Usa Astro.rewrite en tus archivos .astro para redireccionar a una página diferente:

---
if (!Astro.props.allowed) {
  return Astro.rewrite("/")
}
---

Usa context.rewrite en tus archivos de puntos finales para redirigir a una página diferente:

export function GET(ctx) {
  if (!ctx.locals.allowed) {
    return ctx.rewrite("/")
  }
}

Usa next("/") en tus archivos de middleware para redirigir a una página diferente, y luego llama a la siguiente función de middleware:

export function onRequest(ctx, next) {
  if (!ctx.cookies.get("allowed")) {
    return next("/") // new signature
  }
  return next();
}

Para obtener una visión completa, y proporcionar comentarios sobre esta API experimental, consulta Rerouting RFC.

experimental.env

Tipo: object
Por defecto: undefined

Agregado en: astro@4.10.0

Habilita las características experimentales de astro:env.

La API astro:env te permite configurar un esquema seguro para tus variables de entorno, y especificar si deben estar disponibles en el servidor o en el cliente. Importa y utiliza sus variables definidas desde el módulo /client o /server correspondiente:

---
import { APP_ID } from "astro:env/client"
import { API_URL, API_TOKEN, getSecret } from "astro:env/server"
const NODE_ENV = getSecret("NODE_ENV")

const data = await fetch(`${API_URL}/users`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_TOKEN}`
  },
  body: JSON.stringify({ appId: APP_ID, nodeEnv: NODE_ENV })
})
---

Para definir el tipo de datos y las propiedades de tus variables de entorno, declara un esquema en la configuración de Astro en experimental.env.schema. El ayudante envField te permite definir tu variable como una cadena (string), número (number), o booleano (boolean) y pasar propiedades en un objeto:

import { defineConfig, envField } from "astro/config"

export default defineConfig({
    experimental: {
        env: {
            schema: {
                API_URL: envField.string({ context: "client", access: "public", optional: true }),
                PORT: envField.number({ context: "server", access: "public", default: 4321 }),
                API_SECRET: envField.string({ context: "server", access: "secret" }),
            }
        }
    }
})

Actualmente, hay cuatro tipos de datos compatibles: cadenas (strings), números (numbers), booleanos (booleans) y enumeraciones (enums).

Hay tres tipos de variables de entorno, determinadas por la combinación de las configuraciones context (cliente o servidor) y access (secreto o público) definidas en tu env.schema:

Variables públicas del cliente: Estas variables terminan en los paquetes finales tanto del cliente como del servidor, y pueden ser accedidas desde ambos a través del módulo astro:env/client:
```
import { API_URL } from "astro:env/client"
```
Variables públicas del servidor: Estas variables terminan en tu paquete final del servidor y pueden ser accedidas en el servidor a través del módulo astro:env/server:
```
import { PORT } from "astro:env/server"
```
Variables secretas del servidor: Estas variables no forman parte de tu paquete final y pueden ser accedidas en el servidor a través del módulo astro:env/server. La función auxiliar getSecret() puede ser utilizada para recuperar secretos que no están especificados en el esquema:
```
import { API_SECRET, getSecret } from "astro:env/server"

const SECRET_NOT_IN_SCHEMA = getSecret("SECRET_NOT_IN_SCHEMA") // string | undefined
```

Nota: Las variables secretas del cliente no son compatibles porque no hay una manera segura de enviar estos datos al cliente. Por lo tanto, no es posible configurar tanto context: "client" como access: "secret" en tu esquema.

Para obtener una visión completa y proporcionar comentarios sobre esta API experimental, consulta Astro Env RFC.

experimental.env.schema

Tipo: EnvSchema
Por defecto: undefined

Agregado en: astro@4.10.0

Un objeto que usa envField para definir el tipo de datos (string, number, or boolean) y las propiedades de tus variables de entorno: context (cliente o servidor), access (pública o secreta), un valor default a utilizar, y si esta variable de entorno es optional (opcional) o no (por defecto es false).

import { defineConfig, envField } from "astro/config"

export default defineConfig({
  experimental: {
    env: {
      schema: {
        API_URL: envField.string({ context: "client", access: "public", optional: true }),
        PORT: envField.number({ context: "server", access: "public", default: 4321 }),
        API_SECRET: envField.string({ context: "server", access: "secret" }),
      }
    }
  }
})

Contribuir

Comunidad