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.

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

Type: 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 la barra de herramientas de desarrollo

devToolbar.enabled

Tipo: boolean
Por defecto: true

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

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 Nuevo

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

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

Tipo: boolean
Por defecto: false

Agregado en: astro@4.3.0

Habilita el soporte de dominios para la estrategia de enrutamiento domains experimental que te permite configurar el patrón de URL de uno o más idiomas admitidos para usar un dominio personalizado (o subdominio).

Cuando un idioma se asigna a un dominio, no se utilizará un prefijo de ruta /[locale]/. Sin embargo, las carpetas localizadas dentro de src/pages/ siguen siendo necesarias, incluido tu defaultLocale configurado.

Cualquier otro idioma no configurado se asignará a una URL basada en la ruta localizada según tu estrategia prefixDefaultLocale (p. ej. https://example.com/[locale]/blog).

export default defineConfig({
  site: "https://example.com",
  output: "server", // requerido, sin páginas prerenderizadas
  adapter: node({
    mode: 'standalone',
  }),
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    prefixDefaultLocale: false,
    domains: {
      fr: "https://fr.example.com",
      es: "https://example.es",
    },
  },
  experimental: {
    i18nDomains: true,
  },
});

Ambas rutas de página construidas y URLs devueltas por las funciones auxiliares astro:i18n getAbsoluteLocaleUrl() y getAbsoluteLocaleUrlList() utilizarán las opciones establecidas en i18n.domains. Ver la Guía de Internacionalización para más detalles, incluyendo las limitaciones de esta característica experimental.