Referencia de configuración

La siguiente referencia cubre todas las opciones de configuración soportadas en Astro. Para obtener más información sobre cómo configurar Astro, lee nuestra guía sobre Configuración de Astro.

import { defineConfig } from 'astro/config'

export default defineConfig({
  // your configuration options here...
})

Opciones globales

site

Type: string

Tu URL final desplegada. Astro usa esta URL completa para generar tu sitemap y URLs canónicas en tu construcción final. Se recomienda encarecidamente que establezcas esta configuración para aprovechar al máximo Astro.

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

base

Type: string

La ruta base a la cual realizar el despliegue. Astro usará esta ruta como la raíz para tus páginas y recursos tanto en desarrollo como en la construcción de producción.

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

{
  base: '/docs'
}

Al usar esta opción, todas tus importaciones de recursos estáticos y URLs deben agregar la base como un prefijo. Puedes acceder a este valor a través de import.meta.env.BASE_URL.

El valor de import.meta.env.BASE_URL estará determinado por tu configuración de trailingSlash, sin importar qué valor hayas establecido para base.

Siempre se incluye una barra diagonal final si se establece trailingSlash: "always". Si se establece trailingSlash: "never", BASE_URL no incluirá una barra diagonal 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 según lo lean las integraciones también estará determinado por tu configuración de trailingSlash de la misma manera.

En el ejemplo de abajo, los valores de import.meta.env.BASE_URL y config.base cuando se procesen serán ambos /docs:

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

En el ejemplo de abajo, los valores de import.meta.env.BASE_URL and config.base cuando se procesen serán ambos /docs/:

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

trailingSlash

Type: 'always' | 'never' | 'ignore'
Default: 'ignore'

Establece el comportamiento de coincidencia de rutas para las barras diagonales finales (trailing slashes) en el servidor de desarrollo y en las páginas renderizadas bajo demanda. Elige entre las siguientes opciones:

'ignore' - Coincide con las URLs independientemente de si existe una “/” final o no. Las solicitudes para “/about” y “/about/” coincidirán con la misma ruta.
'always' - Solo coincide con las URLs que incluyen una barra diagonal final (por ejemplo: “/about/”). En producción, las solicitudes para URLs renderizadas bajo demanda sin una barra diagonal final se redirigirán a la URL correcta para tu comodidad. Sin embargo, en desarrollo, mostrarán una página de advertencia recordándote que tienes configurado always.
'never' - Solo coincide con las URLs que no incluyen una barra diagonal final (por ejemplo: “/about”). En producción, las solicitudes para URLs renderizadas bajo demanda con una barra diagonal final se redirigirán a la URL correcta para tu comodidad. Sin embargo, en desarrollo, mostrarán una página de advertencia recordándote que tienes configurado never.

Cuando ocurren redirecciones en producción para solicitudes GET, la redirección será una redirección 301 (permanente). Para todos los demás métodos de solicitud, será una redirección 308 (permanente y que conserva el método de solicitud).

Las barras diagonales finales en las páginas prerenderizadas son manejadas por la plataforma de hosting, y pueden no respetar la configuración elegida. Consulta la documentación de tu plataforma de hosting para obtener más información. No puedes usar las redirecciones de Astro para este caso de uso en este momento.

{
  // Example: Require a trailing slash during development
  trailingSlash: 'always'
}

See Also:

build.format

redirects

Type: Record<string, RedirectConfig>
Default: {}

Añadido 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 cual redirigir.

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

export default defineConfig({
  redirects: {
   '/old': '/new',
   '/blog/[...slug]': '/articles/[...slug]',
   '/about': 'https://example.com/about',
   '/news': {
     status: 302,
     destination: 'https://example.com/news'
   },
   // '/product1/', '/product1' // Note, this is not supported
  }
})

Para sitios generados estáticamente sin ningún adaptador instalado, esto producirá una redirección del cliente usando una etiqueta <meta http-equiv="refresh"> y no es compatible con códigos de estado.

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

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

export default defineConfig({
  redirects: {
    '/other': {
      status: 302,
      destination: '/place',
    },
  }
})

output

Type: 'static' | 'server'
Default: 'static'

Especifica el objetivo de salida para las construcciones.

'static' - Prerenderiza todas tus páginas por defecto, produciendo un sitio completamente estático si ninguna de tus páginas opta por no prerenderizarse.
'server' - Usa la renderización del lado del servidor (SSR) para todas las páginas por defecto, produciendo siempre un sitio renderizado por el servidor.

import { defineConfig } from 'astro/config';

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

See Also:

adapter

adapter

Type: AstroIntegration

Realiza el despliegue en tu servidor, serverless o hosting de edge favorito con adaptadores de construcción. Importa uno de nuestros adaptadores oficiales (Cloudflare, Netlify, Node.js, Vercel) o explora adaptadores de la comunidad para habilitar la renderización bajo demanda en tu proyecto de Astro.

Consulta nuestra guía de renderización bajo demanda para obtener más información sobre las opciones de renderización del servidor de Astro.

import netlify from '@astrojs/netlify';
{
  // Example: Build for Netlify serverless deployment
  adapter: netlify(),
}

See Also:

output

integrations

Type: AstroIntegration[]

Extiende Astro con integraciones personalizadas. Las integraciones son tu solución única para agregar soporte de frameworks (como Solid.js), nuevas características (como sitemaps) y nuevas librerías (como Partytown).

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

import react from '@astrojs/react';
import mdx from '@astrojs/mdx';
{
  // Example: Add React + MDX support to Astro
  integrations: [react(), mdx()]
}

root

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

Solo deberías proporcionar esta opción si ejecutas los comandos de la CLI de astro en un directorio diferente al directorio 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 poder localizar tu archivo de configuración.

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

Ejemplos

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

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

srcDir

Type: string
Default: "./src"

Establece el directorio desde el cual Astro leerá tu sitio.

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

{
  srcDir: './www'
}

publicDir

Type: string
Default: "./public"

Establece el directorio para tus recursos estáticos. Los archivos de este directorio se sirven en / durante el desarrollo y se copian a tu directorio de construcción durante la construcción. Estos archivos siempre se sirven o copian tal cual, sin transformar ni empaquetar.

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

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

outDir

Type: string
Default: "./dist"

Establece el directorio en el cual astro build escribe tu construcción final.

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

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

See Also:

build.server

cacheDir

Type: string
Default: "./node_modules/.astro"

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

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

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

compressHTML

Type: boolean | "jsx"
Default: 'jsx'

Controla cómo maneja Astro el espacio en blanco en tu HTML. Esto afecta tanto al modo de desarrollo como a la salida de la construcción final.

Desde la v7.0, Astro aplica por defecto las reglas de espacio en blanco de JSX utilizadas por frameworks como React. Esto elimina los espacios en blanco y los saltos de línea alrededor de los elementos, reduce el texto de varias líneas a una sola línea y preserva el espacio en blanco dentro de una sola línea (por ejemplo, un espacio entre dos elementos en línea). Para mantener un espacio que de otro modo se eliminaría, inclúyelo explícitamente en el código fuente a través de construcciones como {" "}.

Establecer esta opción en true elimina de forma limpia el espacio en blanco, incluidos los saltos de línea, de los componentes .astro. Es posible que se preserve parte del espacio en blanco según sea necesario para mantener la renderización visual de tu HTML.

Establecer esta opción en false desactiva la compresión de HTML y conserva todo el espacio en blanco.

{
  compressHTML: true
  // or:
  // compressHTML: false
}

scopedStyleStrategy

Type: 'where' | 'class' | 'attribute'
Default: 'attribute'

Añadido en: astro@2.4

Especifica la estrategia utilizada para limitar el alcance (scope) de los estilos dentro de los componentes de Astro. Elige entre:

'where' - Usa selectores :where, lo que no causa un aumento de la especificidad.
'class' - Usa selectores basados en clases, lo que provoca un aumento de especificidad de +1.
'attribute' - Usa atributos data-, lo que provoca un aumento de especificidad de +1.

Usar 'class' es útil cuando deseas asegurarte de que los selectores de elementos dentro de un componente de Astro anulen los estilos globales predeterminados (por ejemplo, de una hoja de estilos global). Usar 'where' te brinda más control sobre la especificidad, pero requiere que uses selectores de mayor especificidad, capas (layers) y otras herramientas para controlar qué selectores se aplican. Usar 'attribute' es útil cuando estás manipulando el atributo class de los elementos y necesitas evitar conflictos entre tu propia lógica de estilos y la aplicación de estilos de Astro.

prerenderConflictBehavior

Type: 'error' | 'warn' | 'ignore'
Default: 'warn'

Añadido en: astro@6.0

Determina el comportamiento por defecto cuando dos rutas generan la misma URL prerenderizada:

error: hace fallar la construcción y muestra un error, obligándote a resolver el conflicto
warn (por defecto): registra una advertencia cuando ocurren conflictos, pero construye utilizando la ruta de mayor prioridad
ignore: construye silenciosamente usando la ruta de mayor prioridad cuando ocurren conflictos

{
  prerenderConflictBehavior: 'error'
}

vite

Type: ViteUserConfig

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

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

Ejemplos

{
  vite: {
    ssr: {
      // Example: Force a broken package to skip SSR processing, if needed
      external: ['broken-npm-package'],
    }
  }
}

{
  vite: {
    // Example: Add custom vite plugins directly to your Astro project
    plugins: [myPlugin()],
  }
}

security

Type: Record<"checkOrigin", boolean> | undefined
Default: {checkOrigin: true}

Añadido en: astro@4.9.0

Habilita medidas de seguridad para un sitio web de Astro.

Estas características solo existen para páginas renderizadas bajo demanda (SSR) usando el modo server o páginas que optan por no prerenderizarse en modo static.

Por defecto, Astro comprobará automáticamente que la cabecera “origin” coincida con la URL enviada por cada solicitud en las páginas renderizadas bajo demanda. Puedes desactivar este comportamiento estableciendo checkOrigin en false:

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

security.checkOrigin

Type: boolean
Default: true

Añadido en: astro@4.9.0

Realiza una comprobación de que la cabecera “origin”, enviada automáticamente por todos los navegadores modernos, coincida con la URL enviada por cada Request. Esto se utiliza para proporcionar protección contra la Falsificación de Solicitud en Sitios Cruzados (CSRF).

La comprobación de “origin” se ejecuta solo para páginas renderizadas bajo demanda, y solo para las solicitudes POST, PATCH, DELETE y PUT con una de las siguientes cabeceras de content-type: 'application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain'.

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

security.allowedDomains

Type: Array<RemotePattern>
Default: []

Añadido en: astro@5.14.2

Define una lista de patrones de host permitidos para las solicitudes entrantes cuando se usa SSR. Cuando está configurado, Astro validará la cabecera X-Forwarded-Host contra estos patrones por seguridad. Si la cabecera no coincide con ningún patrón permitido, se ignorará y en su lugar se utilizará el host original de la solicitud.

Esto evita los ataques de inyección de cabeceras de host en los que los actores maliciosos pueden manipular el valor de Astro.url enviando cabeceras X-Forwarded-Host manipuladas.

Cada patrón puede especificar protocol, hostname y port. Los tres se validan si se proporcionan. Los patrones admiten comodines para una coincidencia de nombres de host flexible:

*.example.com - coincide exactamente con un nivel de subdominio (por ejemplo, sub.example.com pero no deep.sub.example.com)
**.example.com - coincide con cualquier profundidad de subdominio (por ejemplo, tanto sub.example.com como deep.sub.example.com)

{
  security: {
    // Example: Allow any subdomain of example.com on https
    allowedDomains: [
      {
        hostname: '**.example.com',
        protocol: 'https'
      },
      {
        hostname: 'staging.myapp.com',
        protocol: 'https',
        port: '443'
      }
    ]
  }
}

En algunos contextos específicos (por ejemplo, aplicaciones detrás de proxies inversos de confianza con dominios dinámicos), es posible que necesites permitir todos los dominios. Para hacer esto, usa un objeto vacío:

{
  security: {
    // Allow any domain - use this only when necessary
    allowedDomains: [{}]
  }
}

Cuando no está configurada, las cabeceras X-Forwarded-Host no son confiables y se ignorarán.

security.actionBodySizeLimit

Tipo: number
Por defecto: 1048576 (1 MB)

Añadido en: astro@5.18.0

Establece el tamaño máximo en bytes permitido para los cuerpos de solicitud de acciones.

Por defecto, los cuerpos de solicitud de acción están limitados a 1 MB (1048576 bytes) para evitar el abuso. Puedes aumentar este límite si tus acciones necesitan aceptar cargas más grandes, por ejemplo, al manejar subidas de archivos.

export default defineConfig({
  security: {
    actionBodySizeLimit: 10 * 1024 * 1024 // 10 MB
  }
})

security.serverIslandBodySizeLimit

Tipo: number
Por defecto: 1048576 (1 MB)

Añadido en: astro@6.0.0

Establece el tamaño máximo en bytes permitido para los cuerpos de solicitud de server island, los cuales contienen las props cifradas y el HTML del slot pasados al componente de la isla.

Por defecto, los cuerpos de solicitud de server island están limitados a 1 MB (1048576 bytes) para evitar el abuso. Puedes aumentar este límite si tus server islands necesitan aceptar cargas más grandes.

export default defineConfig({
  security: {
    serverIslandBodySizeLimit: 10 * 1024 * 1024 // 10 MB
  }
})

security.csp

Type: boolean | object
Default: false

Añadido en: astro@6.0.0

Habilita el soporte para la Política de Seguridad de Contenido (CSP) para ayudar a minimizar ciertos tipos de amenazas de seguridad controlando qué recursos tiene permitido cargar un documento. Esto proporciona protección adicional contra ataques de cross-site scripting (XSS).

Habilitar esta característica añade seguridad adicional al manejo por defecto que hace Astro de los scripts y estilos procesados y empaquetados, y te permite configurar aún más estos tipos de contenido, así como otros adicionales.

Esta característica viene con algunas limitaciones:

Los scripts externos y los estilos externos no están soportados de forma predeterminada, pero puedes proporcionar tus propios hashes.
Las view transitions de Astro que usan el <ClientRouter /> no están soportadas, pero puedes considerar migrar a la API nativa de View Transition del navegador en su lugar si no estás utilizando las mejoras de Astro a las APIs nativas de View Transitions y Navigation.
Shiki no está soportado actualmente. Por diseño, las funciones de Shiki usan estilos en línea que no pueden funcionar con la implementación de CSP de Astro. Considera usar <Prism /> cuando tu proyecto requiera tanto CSP como resaltado de sintaxis.
Las directivas unsafe-inline son incompatibles con la implementación de CSP de Astro. Por defecto, Astro emitirá hashes para todos sus scripts empaquetados (por ejemplo, client islands) y todos los navegadores modernos rechazarán automáticamente unsafe-inline cuando ocurra en una directiva con un hash o un nonce.

Cuando está habilitado, Astro agregará un elemento <meta> dentro del elemento <head> de cada página. Este elemento tendrá el atributo http-equiv="content-security-policy", y el atributo content proporcionará valores para las directivas script-src y style-src basándose en el script y los estilos utilizados en la página.

<head>
  <meta
    http-equiv="content-security-policy"
    content="
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
    "
  >
</head>

Puedes personalizar aún más el elemento <meta> habilitando esta característica con un objeto de configuración que incluye opciones adicionales.

security.csp.algorithm

Type: "SHA-256" | "SHA-384" | "SHA-512"
Default: 'SHA-256'

Añadido en: astro@6.0.0

La función hash a usar al generar los hashes de los estilos y scripts emitidos por Astro.

import { defineConfig } from 'astro/config';

export default defineConfig({
  security: {
    csp: {
     algorithm: 'SHA-512'
    }
  }
});

security.csp.directives

Type: Array<string>
Default: []

Añadido en: astro@6.0.0

Una lista de directivas CSP (más allá de script-src y style-src que se incluyen por defecto) que define orígenes válidos para tipos de contenido específicos. Estas directivas se agregan a todas las páginas.

import { defineConfig } from 'astro/config';

export default defineConfig({
  security: {
    csp: {
      directives: [
        "default-src 'self'",
        "img-src 'self' https://images.cdn.example.com"
      ]
    }
  }
});

Después de la construcción, el elemento <meta> agregará tus directivas al valor de content junto con las directivas por defecto de Astro:

<meta
  http-equiv="content-security-policy"
  content="
    default-src 'self';
    img-src 'self' 'https://images.cdn.example.com';
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>

security.csp.styleDirective

Type: CspStyleDirective
Default: undefined

Añadido en: astro@6.0.0

Un objeto de configuración que te permite anular los orígenes por defecto para la directiva style-src con la propiedad resources, o proporcionar hashes adicionales para ser renderizados.

security.csp.styleDirective.hashes

Type: Array<CspHash>
Default: []

Añadido en: astro@6.0.0

Una lista de hashes adicionales para renderizar.

Debes proporcionar hashes que comiencen con sha384-, sha512- o sha256-. Otros valores causarán un error de validación. Estos hashes se agregan a todas las páginas.

import { defineConfig } from 'astro/config';

export default defineConfig({
  security: {
    csp: {
      styleDirective: {
        hashes: [
          "sha384-styleHash",
          "sha512-styleHash",
          "sha256-styleHash"
        ]
      }
    }
  }
});

Después de la construcción, el elemento <meta> incluirá tus hashes adicionales en las directivas style-src:

<meta
  http-equiv="content-security-policy"
  content="
    style-src 'self' 'sha384-styleHash' 'sha512-styleHash' 'sha256-styleHash' 'sha256-generatedByAstro';
  "
>

security.csp.styleDirective.resources

Type: Array<string>
Default: []

Añadido en: astro@6.0.0

Una lista de orígenes válidos para las directivas style-src para anular los orígenes predeterminados de Astro. Esto no incluirá 'self' por defecto, y debe incluirse en esta lista si deseas conservarlo. Estos recursos se agregan a todas las páginas.

import { defineConfig } from 'astro/config';

export default defineConfig({
  security: {
    csp: {
      styleDirective: {
        resources: [
          "'self'",
          "https://styles.cdn.example.com"
        ]
      }
    }
  }
});

Después de la construcción, el elemento <meta> en su lugar aplicará tus orígenes a las directivas style-src:

<head>
  <meta
    http-equiv="content-security-policy"
    content="
     style-src 'self' https://styles.cdn.example.com 'sha256-somehash';
    "
  >
</head>

Cuando los recursos se insertan varias veces o desde múltiples orígenes (por ejemplo, definidos en tu configuración de csp y añadidos usando la API de tiempo de ejecución de CSP), Astro fusionará y eliminará los duplicados de todos los recursos para crear tu elemento <meta>.

security.csp.scriptDirective

Type: CspScriptDirective
Default: undefined

Añadido en: astro@6.0.0

Un objeto de configuración que te permite anular los orígenes predeterminados para la directiva script-src con la propiedad resources, o proporcionar hashes adicionales para ser renderizados.

security.csp.scriptDirective.hashes

Type: Array<CspHash>
Default: []

Añadido en: astro@6.0.0

Una lista de hashes adicionales para renderizar.

Debes proporcionar hashes que comiencen con sha384-, sha512- o sha256-. Otros valores causarán un error de validación. Estos hashes se agregan a todas las páginas.

import { defineConfig } from 'astro/config';

export default defineConfig({
  security: {
    csp: {
      scriptDirective: {
        hashes: [
          "sha384-scriptHash",
          "sha512-scriptHash",
          "sha256-scriptHash"
        ]
      }
    }
  }
});

Después de la construcción, el elemento <meta> incluirá tus hashes adicionales en las directivas script-src:

<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha384-scriptHash' 'sha512-scriptHash' 'sha256-scriptHash' 'sha256-generatedByAstro';
  "
>

security.csp.scriptDirective.resources

Type: Array<string>
Default: []

Añadido en: astro@6.0.0

Una lista de orígenes válidos para las directivas script-src para anular los orígenes predeterminados de Astro. Esto no incluirá 'self' por defecto, y debe incluirse en esta lista si deseas conservarlo. Estos recursos se agregan a todas las páginas.

import { defineConfig } from 'astro/config';

export default defineConfig({
  security: {
    csp: {
      scriptDirective: {
        resources: [
          "'self'", "https://cdn.example.com"
        ]
      }
    }
  }
});

Después de la construcción, el elemento <meta> en su lugar aplicará tus orígenes a las directivas script-src:

<head>
  <meta
    http-equiv="content-security-policy"
    content="
     script-src 'self' https://cdn.example.com 'sha256-somehash';
    "
  >
</head>

security.csp.scriptDirective.strictDynamic

Type: boolean
Default: false

Añadido en: astro@6.0.0

Habilita la palabra clave strict-dynamic para admitir la inyección dinámica de scripts.

import { defineConfig } from 'astro/config';

export default defineConfig({
  security: {
    csp: {
      scriptDirective: {
        strictDynamic: true
      }
    }
  }
});

Opciones de construcción

build.format

Type: ('file' | 'directory' | 'preserve')
Default: 'directory'

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

'file': Astro generará un archivo HTML nombrado para la ruta de cada página. (por ejemplo, tanto src/pages/about.astro como src/pages/about/index.astro construyen el archivo /about.html)
'directory': Astro generará un directorio con un archivo index.html anidado para cada página. (por ejemplo, tanto src/pages/about.astro como src/pages/about/index.astro construyen el archivo /about/index.html)
'preserve': Astro generará archivos HTML exactamente como aparecen en tu carpeta de origen. (por ejemplo, src/pages/about.astro construye /about.html y src/pages/about/index.astro construye el archivo /about/index.html)

{
  build: {
    // Example: Generate `page.html` instead of `page/index.html` during build.
    format: 'file'
  }
}

Efecto en Astro.url

Establecer build.format controla a qué se establece Astro.url durante la construcción. Cuando es:

directory - El Astro.url.pathname incluirá una barra diagonal final para imitar el comportamiento de una carpeta. (por ejemplo, /foo/)
file - El Astro.url.pathname incluirá .html. (por ejemplo, /foo.html)

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

Para evitar inconsistencias con el comportamiento de la barra diagonal final en desarrollo, puedes restringir la opción trailingSlash a 'always' o 'never' según tu formato de construcción:

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

build.client

Type: string
Default: './client'

Controla el directorio de salida de tu CSS y JavaScript del lado del cliente cuando construyes un sitio web con páginas renderizadas por el servidor. outDir controla dónde se construye el código.

Este valor es relativo a outDir.

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

build.server

Type: string
Default: './server'

Controla el directorio de salida del JavaScript del servidor cuando se construye para SSR.

Este valor es relativo a outDir.

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

build.assets

Type: string
Default: '_astro'

Agregado en: astro@2.0.0

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

{
  build: {
    assets: '_custom'
  }
}

See Also:

outDir

build.assetsPrefix

Type: string | Record<string, string>
Default: undefined

Añadido en: astro@2.2.0

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

Esto requiere subir los recursos de tu carpeta local ./dist/_astro a la carpeta correspondiente /_astro/ en el dominio remoto. Para renombrar la ruta _astro, especifica un nuevo directorio en build.assets.

Para obtener todos los recursos subidos al mismo dominio (por ejemplo, https://cdn.example.com/_astro/...), establece assetsPrefix al dominio raíz como una cadena (independientemente de tu configuración de base):

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

Added in: astro@4.5.0

También puedes pasar un objeto a assetsPrefix para especificar un dominio diferente para cada tipo de archivo. En este caso, se requiere una propiedad fallback y 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

Type: string
Default: 'entry.mjs'

Especifica el nombre de archivo del punto de entrada del servidor al construir para SSR. Este punto de entrada suele depender del host en el que realices el despliegue y será establecido por tu adaptador.

Ten en cuenta que se recomienda que este archivo termine con .mjs para que el entorno de ejecución detecte que el archivo es un módulo de JavaScript.

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

build.redirects

Type: boolean
Default: true

Añadido en: astro@2.6.0

Especifica si las redirecciones se generarán como HTML durante la construcció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á pensada principalmente para ser utilizada por adaptadores que tienen archivos de configuración especiales para las redirecciones y no necesitan/quieren redirecciones basadas en HTML.

{
  build: {
    redirects: false
  }
}

build.inlineStylesheets

Type: 'always' | 'auto' | 'never'
Default: auto

Añadido en: astro@2.6.0

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

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

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

build.concurrency

Type: number
Default: 1

Añadido en: astro@4.16.0

El número de páginas a construir en paralelo.

In most cases, you should not change the default value of 1.

Usa esta opción solo cuando otros intentos de reducir el tiempo total de renderización (por ejemplo, agrupar o almacenar en caché tareas de larga ejecución como llamadas fetch o acceso a datos) no sean posibles o sean insuficientes. Si el número se establece demasiado alto, la renderización de la página puede ralentizarse debido a recursos de memoria insuficientes y porque JS es de un solo hilo.

{
  build: {
    concurrency: 2
  }
}

Opciones del servidor

Personaliza el servidor de desarrollo de Astro, utilizado tanto por astro dev como por astro preview.

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

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

{
  // Example: Use the function syntax to customize based on command
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 })
}

server.host

Type: string | boolean
Default: false

Añadido en: astro@0.24.0

Establece en qué direcciones IP de red debe escuchar el servidor (es decir, direcciones IP que no sean localhost).

false - no exponer en una dirección IP de red
true - escuchar en todas las direcciones, incluyendo LAN y direcciones públicas
[custom-address] - exponer en una dirección IP de red en [custom-address] (ej: 192.168.0.1)

server.port

Type: number
Default: 4321

Establece en qué puerto debe escuchar el servidor.

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

{
  server: { port: 8080 }
}

server.allowedHosts

Type: Array<string> | true
Default: []

Añadido en: astro@5.4.0

Una lista de nombres de host a los que Astro tiene permitido responder. Cuando el valor se establece en true, se permite cualquier nombre de host.

{
  server: {
    allowedHosts: ['staging.example.com', 'qa.example.com']
  }
}

server.open

Type: string | boolean
Default: false

Añadido en: astro@4.1.0

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

Pasa una cadena de URL completa (por ejemplo, “http://example.com”) o una ruta (por ejemplo, “/about”) para especificar la URL a abrir.

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

server.headers

Type: OutgoingHttpHeaders
Default: {}

Añadido en: astro@1.7.0

Establece cabeceras de respuesta HTTP personalizadas para enviar en astro dev y astro preview.

fetchFile

Type: string | null
Default: 'fetch'

Añadido en: astro@7.0.0 Nuevo

Personaliza el archivo utilizado como punto de entrada de fetch dentro de srcDir. Por defecto es 'fetch', lo que significa que Astro busca src/fetch.ts (o .js / .mjs / .mts).

El archivo fetch te permite componer el flujo de solicitudes de Astro con el estándar de Web Fetch o tu propio middleware de Hono.

Si ya tienes un archivo src/fetch.ts en uso para otros propósitos, define un nombre de archivo diferente o establece el valor en null para deshabilitar el punto de entrada:

import { defineConfig } from 'astro/config';

export default defineConfig({
  fetchFile: 'handler',
});

Obtén más información sobre cómo personalizar el flujo de solicitudes en la guía de enrutamiento avanzado.

Opciones del registrador (logger)

Type: LoggerHandlerConfig
Default: undefined

Añadido en: astro@7.0.0 Nuevo

Configura cómo registra Astro los mensajes durante el desarrollo y la producción.

Por defecto, Astro utiliza un registrador integrado que muestra registros amigables para los humanos en la consola. Puedes personalizar este comportamiento proporcionando tu propio manejador de registros o utilizando uno de los manejadores de registros integrados:

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  logger: logHandlers.json({ level: 'info' })
});

Consulta la referencia de la API del registrador para obtener más información.

logger.entrypoint

Type: string

Añadido en: astro@7.0.0 Nuevo

El punto de entrada del manejador de registros. Esto puede ser una ruta a un archivo en tu proyecto o un paquete de npm:

import { defineConfig } from 'astro/config';

export default defineConfig({
  logger: {
    entrypoint: "@org/astro-logger",
  }
});

logger.config

Type: Record<string, unknown> | undefined
Default: {}

Añadido en: astro@7.0.0 Nuevo

El objeto de configuración para el manejador de registros. Las opciones dependen del registrador configurado.

import { defineConfig } from 'astro/config';

export default defineConfig({
  logger: {
    entrypoint: "@org/astro-logger",
    config: {
     level: "error"
    }
  }
});

Opciones de sesión

Añadido en: astro@5.7.0

Configura el almacenamiento de sesiones para tu proyecto de Astro. Esto se utiliza para almacenar datos de sesión de forma persistente, de modo que se pueda acceder a ellos a través de diferentes solicitudes.

Algunos adaptadores pueden proporcionar un controlador de sesión por defecto, pero puedes anularlo con tu propia configuración:

import { defineConfig, sessionDrivers } from 'astro/config';

export default defineConfig({
  session: {
    driver: sessionDrivers.redis({
      // The options are driver-dependent and some may be required.
      url: process.env.REDIS_URL
    }),
  }
});

Los controladores (drivers) de sesión se configuran en tiempo de construcción. Esto significa que las variables de entorno utilizadas en la configuración del controlador se insertan en línea. Debes crear tu propio punto de entrada del controlador para anular la configuración en tiempo de ejecución.

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

session.driver

Type: SessionDriverConfig | undefined

Añadido en: astro@5.7.0

El controlador a usar para el almacenamiento de sesiones. Los adaptadores de Node, Cloudflare y Netlify configuran automáticamente un controlador predeterminado por ti, pero puedes especificar el tuyo propio si lo prefieres o si estás utilizando un adaptador que no proporciona uno.

import { defineConfig, sessionDrivers } from 'astro/config'
import vercel from '@astrojs/vercel'

export default defineConfig({
  adapter: vercel()
  session: {
    driver: sessionDrivers.redis({
      url: process.env.REDIS_URL
    }),
  }
})

session.options

Type: Record<string, unknown> | undefined
Default: {}

Añadido en: astro@5.7.0

Las opciones específicas del controlador a usar para el almacenamiento de sesiones. Las opciones dependen del controlador que estés utilizando. Consulta la documentación de Unstorage para obtener más información sobre las opciones disponibles para cada controlador.

{
   session: {
     driver: "redis",
     options: {
       url: process.env.REDIS_URL
     },
   }
}

session.cookie

Type: string | AstroCookieSetOptions | undefined
Default: { name: "astro-session", sameSite: "lax", httpOnly: true, secure: true }

Añadido en: astro@5.7.0

La configuración de la cookie de sesión. Si se establece como una cadena, se utilizará como el nombre de la cookie. Alternativamente, puedes pasar un objeto con opciones adicionales. Estas se fusionarán con los valores predeterminados.

{
 session: {
   // If set to a string, it will be used as the cookie name.
   cookie: "my-session-cookie",
 }
}

{
 session: {
   // If set to an object, it will be used as the cookie options.
   cookie: {
     name: "my-session-cookie",
     sameSite: "lax",
     secure: true,
   }
 }
}

session.ttl

Tipo: number | undefined
Por defecto: Infinity

Añadido en: astro@5.7.0

Un período de expiración predeterminado opcional del tiempo de vida (time-to-live) para los valores de sesión, en segundos.

Por defecto, los valores de sesión persisten hasta que se eliminan o se destruye la sesión, y no expiran automáticamente porque haya transcurrido una cantidad de tiempo en particular. Establece session.ttl para agregar un período de expiración predeterminado para tus valores de sesión. Pasar una opción ttl a session.set() anulará el valor predeterminado global para esa entrada individual.

{
 session: {
   // Set a default expiration period of 1 hour (3600 seconds)
   ttl: 3600,
 }
}

devToolbar.enabled

Type: boolean
Default: true

Indica si se debe habilitar la barra de herramientas de desarrollo de Astro. Esta barra de herramientas te permite inspeccionar las islas de tu página, ver auditorías útiles sobre rendimiento y accesibilidad, y más.

Esta opción está limitada a todo el proyecto. Para desactivar la barra de herramientas solo 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.

devToolbar.placement

Type: 'bottom-left' | 'bottom-center' | 'bottom-right'
Default: 'bottom-center'

Añadido en: astro@5.17.0

La ubicación predeterminada de la barra de herramientas de desarrollo de Astro en la pantalla.

La ubicación de la barra de herramientas aún se puede cambiar a través de la interfaz de usuario de configuración de la barra de herramientas. Una vez cambiada, la preferencia del usuario se guarda en localStorage y anula este valor de configuración.

Opciones de pre-búsqueda (prefetch)

Type: boolean | object

Habilita la pre-búsqueda (prefetching) para los enlaces en tu sitio para proporcionar transiciones de página más rápidas. (Habilitado por defecto en las páginas que usan el enrutador <ClientRouter />. Establece prefetch: false para optar por no participar en este comportamiento).

Esta configuración agrega automáticamente un script de prefetch a cada página del proyecto, dándote acceso al atributo data-astro-prefetch. Agrega este atributo a cualquier enlace <a /> en tu página para habilitar la pre-búsqueda para esa página.

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

Personaliza aún más el comportamiento predeterminado de pre-búsqueda utilizando las opciones prefetch.defaultStrategy y prefetch.prefetchAll.

Consulta la guía de pre-búsqueda (prefetch) para obtener más información.

prefetch.prefetchAll

Type: boolean

Habilita la pre-búsqueda para todos los enlaces, incluidos aquellos sin el atributo data-astro-prefetch. Este valor es por defecto true cuando se utiliza el enrutador <ClientRouter />. De lo contrario, el valor por defecto es false.

prefetch: {
  prefetchAll: true
}

Cuando se establece en true, puedes desactivar la pre-búsqueda individualmente estableciendo data-astro-prefetch="false" en cualquier enlace individual.

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

prefetch.defaultStrategy

Type: 'tap' | 'hover' | 'viewport' | 'load'
Default: 'hover'

La estrategia de pre-búsqueda predeterminada a utilizar cuando el atributo data-astro-prefetch se establece en un enlace sin valor.

'tap': Realiza la pre-búsqueda justo antes de hacer clic en el enlace.
'hover': Realiza la pre-búsqueda cuando pasas el cursor o te enfocas en el enlace. (por defecto)
'viewport': Realiza la pre-búsqueda a medida que los enlaces entran en el área de visualización (viewport).
'load': Realiza la pre-búsqueda de todos los enlaces de la página después de que la página se haya cargado.

Puedes anular 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">About</a>

Opciones de imágenes

image.endpoint

Type: Object
Default: {route: '/_image', entrypoint: undefined}

Añadido en: astro@3.1.0

Establece el endpoint a usar para la optimización de imágenes en desarrollo y SSR. La propiedad entrypoint se puede establecer en undefined para usar el endpoint de imagen predeterminado.

{
  image: {
    // Example: Use a custom image endpoint at `/custom_endpoint`
    endpoint: {
       route: '/custom_endpoint',
       entrypoint: 'src/my_endpoint.ts',
    },
  },
}

image.service

Type: Object
Default: {entrypoint: 'astro/assets/services/sharp', config?: {}}

Añadido en: astro@2.1.0

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

El valor debe ser un objeto con un punto de entrada (entrypoint) para el servicio de imágenes a usar y, opcionalmente, un objeto de 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: Enable the Sharp-based image service with a custom config
    service: {
       entrypoint: 'astro/assets/services/sharp',
       config: {
         limitInputPixels: false,
         webp: {
           effort: 6,
           alphaQuality: 80,
         },
         jpeg: {
           mozjpeg: true,
         },
      },
     },
  },
}

image.service.config.limitInputPixels

Type: number | boolean
Default: true

Añadido en: astro@4.1.0

Si se deben limitar o no los tamaños de imágenes que procesará el servicio de imágenes Sharp.

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

image.service.config.kernel

Type: string | undefined
Default: undefined

Añadido en: astro@5.17.0

El kernel predeterminado utilizado para redimensionar imágenes en el servicio de imágenes Sharp.

Por defecto esto es undefined, lo cual se mapea al kernel predeterminado de Sharp de lanczos3.

image.service.config.jpeg

Type: Record<string, any> | undefined
Default: undefined

Añadido en: astro@6.1.0

Las opciones del codificador predeterminadas que se pasan a sharp().jpeg() cuando se utiliza el servicio de imágenes Sharp integrado de Astro.

Esto se puede utilizar para opciones como mozjpeg, progressive, chromaSubsampling o una quality por defecto. Los valores de quality por imagen de <Image />, <Picture /> y getImage() siguen teniendo prioridad.

image.service.config.webp

Type: Record<string, any> | undefined
Default: undefined

Añadido en: astro@6.1.0

Las opciones del codificador predeterminadas que se pasan a sharp().webp() cuando se utiliza el servicio de imágenes Sharp integrado de Astro.

Esto se puede utilizar para opciones como effort, alphaQuality, lossless, nearLossless o una quality por defecto. Los valores de quality por imagen de <Image />, <Picture /> y getImage() siguen teniendo prioridad.

image.service.config.avif

Type: Record<string, any> | undefined
Default: undefined

Añadido en: astro@6.1.0

Las opciones del codificador predeterminadas que se pasan a sharp().avif() cuando se utiliza el servicio de imágenes Sharp integrado de Astro.

Esto se puede utilizar para opciones como effort, chromaSubsampling, bitdepth, lossless o una quality por defecto. Los valores de quality por imagen de <Image />, <Picture /> y getImage() siguen teniendo prioridad.

image.service.config.png

Type: Record<string, any> | undefined
Default: undefined

Añadido en: astro@6.1.0

Las opciones del codificador predeterminadas que se pasan a sharp().png() cuando se utiliza el servicio de imágenes Sharp integrado de Astro.

Esto se puede utilizar para opciones como compressionLevel, effort, palette o una quality por defecto. Los valores de quality por imagen de <Image />, <Picture /> y getImage() siguen teniendo prioridad.

image.dangerouslyProcessSVG

Type: boolean
Default: false

Añadido en: astro@6.3.0

Permite que las imágenes de origen SVG sean procesadas por el pipeline de optimización de imágenes.

Esto está deshabilitado por defecto, ya que los SVG formados específicamente pueden ser prohibitivamente costosos de procesar y utilizados por actores maliciosos para ejecutar ataques de denegación de servicio (DoS). Solo habilita esta opción si confías en el origen de tus imágenes SVG y comprendes los riesgos de procesarlas.

image.domains

Type: Array<string>
Default: []

Añadido en: astro@2.10.10

Define una lista de dominios de origen de imágenes permitidos para la optimización de imágenes remotas. Ninguna otra imagen remota será optimizada por Astro.

Esta opción requiere un array de nombres de dominio individuales como cadenas. No se permiten comodines. En su lugar, usa image.remotePatterns para definir una lista de patrones de URL de origen permitidos.

{
  image: {
    // Example: Allow remote image optimization from a single domain
    domains: ['astro.build'],
  },
}

image.remotePatterns

Type: Array<RemotePattern>
Default: []

Añadido en: astro@2.10.10

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

remotePatterns se puede configurar con cuatro propiedades:

protocol
hostname
port
pathname

{
  image: {
    // Example: allow processing all images from your aws s3 bucket
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}

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

Patrones de hostname:

Comienzan con **. para permitir todos los subdominios (como endsWith).
Comienzan con *. para permitir solo un nivel de subdominio.

Patrones de pathname:

Terminan con /** para permitir todas las sub-rutas (como startsWith).
Terminan con /* para permitir solo un nivel de sub-ruta.

También se siguen las redirecciones HTTP cuando una URL de imagen coincide con un patrón remoto. La URL de destino final debe estar entre los patrones remotos permitidos para poder cargarse.

image.responsiveStyles

Type: boolean
Default: false

Añadido en: astro@5.10.0

Indica si se deben agregar automáticamente estilos globales para imágenes adaptables (responsive). Deberías habilitar esta opción a menos que estés aplicando estilos a las imágenes tú mismo.

Esta opción solo se usa cuando layout se establece en constrained, full-width o fixed utilizando la configuración o la propiedad layout en el componente de imagen.

Consulta la documentación de imágenes para obtener más información.

image.layout

Type: ImageLayout
Default: undefined

Añadido en: astro@5.10.0

El tipo de diseño (layout) predeterminado para imágenes adaptables. Puede ser anulado por la propiedad layout en el componente de imagen.

constrained - La imagen se escalará para adaptarse al contenedor, manteniendo su relación de aspecto, pero no superará las dimensiones especificadas.
fixed - La imagen mantendrá sus dimensiones originales.
full-width - La imagen se escalará para adaptarse al contenedor, manteniendo su relación de aspecto.

Consulta la propiedad de componente layout para más detalles.

image.objectFit

Type: ImageFit
Default: "cover"

Añadido en: astro@5.10.0

El valor de la propiedad CSS object-fit para imágenes adaptables. Puede ser anulado por la propiedad fit en el componente de imagen. Requiere que se establezca un valor para layout.

Consulta la propiedad de componente fit para más detalles.

image.objectPosition

Type: string
Default: "center"

Añadido en: astro@5.10.0

El valor predeterminado de la propiedad CSS object-position para imágenes adaptables. Puede ser anulado por la propiedad position en el componente de imagen. Requiere que se establezca un valor para layout.

Consulta la propiedad de componente position para más detalles.

image.breakpoints

Tipo: Array<number>
Por defecto: [640, 750, 828, 1080, 1280, 1668, 2048, 2560] | [640, 750, 828, 960, 1080, 1280, 1668, 1920, 2048, 2560, 3200, 3840, 4480, 5120, 6016]

Añadido en: astro@5.10.0

Los puntos de interrupción (breakpoints) utilizados para generar imágenes adaptables. Requiere que se establezca un valor para layout. La lista completa no se utiliza normalmente, sino que se filtra según el tamaño de origen y de salida. Los valores predeterminados utilizados dependen de si se utiliza un servicio de imágenes local o remoto. Para los servicios remotos se utiliza la lista más completa, porque solo se generan los tamaños requeridos. Para los servicios locales, la lista es más corta para reducir la cantidad de imágenes generadas.

Opciones de Markdown

markdown.shikiConfig

Type: Partial<ShikiConfig>

Shiki es nuestro resaltador de sintaxis predeterminado. Puedes configurar todas las opciones a través del objeto markdown.shikiConfig:

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      // Choose from Shiki's built-in themes (or add your own)
      // https://shiki.style/themes
      theme: 'dracula',
      // Alternatively, provide multiple themes
      // See note below for using dual light/dark themes
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // Disable the default colors
      // https://shiki.style/guide/dual-themes#without-default-color
      // (Added in v4.12.0)
      defaultColor: false,
      // Add custom languages
      // Note: Shiki has countless langs built-in, including .astro!
      // https://shiki.style/languages
      langs: [],
      // Add custom aliases for languages
      // Map an alias to a Shiki language ID: https://shiki.style/languages#bundled-languages
      // https://shiki.style/guide/load-lang#custom-language-aliases
      langAlias: {
        cjs: "javascript"
      },
      // Enable word wrap to prevent horizontal scrolling
      wrap: true,
      // Add custom transformers: https://shiki.style/guide/transformers
      // Find common transformers: https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});

Consulta la guía de resaltado de sintaxis de código para ver el uso y ejemplos.

markdown.syntaxHighlight

Type: SyntaxHighlightConfig | SyntaxHighlightConfigType | false
Default: { type: 'shiki', excludeLangs: ['math'] }

Qué resaltador de sintaxis usar para los bloques de código de Markdown (```), si hay alguno. Esto determina las clases CSS que Astro aplicará a tus bloques de código de Markdown.

shiki - usa el resaltador Shiki (tema github-dark configurado por defecto)
prism - usa el resaltador Prism y proporciona tu propia hoja de estilos de Prism
false - no aplicar resaltado de sintaxis.

{
  markdown: {
    // Example: Switch to use prism for syntax highlighting in Markdown
    syntaxHighlight: 'prism',
  }
}

Para un mayor control sobre el resaltado de sintaxis, en su lugar puedes especificar un objeto de configuración con las propiedades enumeradas a continuación.

markdown.syntaxHighlight.type

Type: 'shiki' | 'prism'
Default: 'shiki'

Añadido en: astro@5.5.0

Las clases CSS predeterminadas a aplicar a los bloques de código de Markdown. (Si no se necesita ninguna otra configuración de resaltado de sintaxis, en su lugar puedes establecer markdown.syntaxHighlight directamente en shiki, prism o false).

markdown.syntaxHighlight.excludeLangs

Type: Array<string>
Default: ['math']

Añadido en: astro@5.5.0

Un array de lenguajes a excluir del resaltado de sintaxis predeterminado especificado en markdown.syntaxHighlight.type. Esto puede ser útil cuando se utilizan herramientas que crean diagramas a partir de bloques de código Markdown, como Mermaid.js y D2.

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    syntaxHighlight: {
      type: 'shiki',
      excludeLangs: ['mermaid', 'math'],
    },
  },
});

markdown.remarkPlugins

Type: RemarkPlugins

Pasa plugins de remark para personalizar cómo se construye tu Markdown. Puedes importar y aplicar la función del plugin (recomendado), o pasar el nombre del plugin como una cadena.

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

markdown.rehypePlugins

Type: RehypePlugins

Pasa plugins de rehype para personalizar cómo se procesa el HTML de salida de tu Markdown. Puedes importar y aplicar la función del plugin (recomendado), o pasar el nombre del plugin como una cadena.

import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis]
  }
}

markdown.gfm

Type: boolean
Default: true

Agregado en: astro@2.0.0

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

{
  markdown: {
    gfm: false,
  }
}

markdown.smartypants

Type: boolean | Smartypants
Default: true

Agregado en: astro@2.0.0

Indica si se debe utilizar el formateador SmartyPants para transformar comillas rectas en comillas tipográficas, guiones en guiones en/em y puntos triples en elipsis.

Para deshabilitar esto, establece la flag smartypants en false.

Para un mayor control sobre la tipografía, en su lugar puedes especificar un objeto de configuración con las propiedades soportadas por retext-smartypants.

markdown.remarkRehype

Type: RemarkRehype

Pasa opciones a remark-rehype.

{
  markdown: {
    // Example: Translate the footnotes text to another language, here are the default English values
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to reference 1"},
  },
};

markdown.processor

Type: MarkdownProcessor

Añadido en: astro@6.4.0

Configura el procesador de Markdown utilizado para renderizar archivos .md. Por defecto es satteri() de @astrojs/markdown-satteri, el pipeline nativo de Markdown de Astro.

import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';

export default defineConfig({
  markdown: {
    processor: satteri({
      features: { gfm: false },
    }),
  },
});

Para mantener el pipeline de remark/rehype, instala @astrojs/markdown-remark y pasa unified():

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkToc from 'remark-toc';

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [remarkToc],
    }),
  },
});

i18n

Type: object

Añadido 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.locales

Type: Locales

Añadido en: astro@3.5.0

Una lista de todos los locales (idiomas) soportados por el sitio web. Este es un campo obligatorio.

Los idiomas se pueden enumerar como códigos individuales (por ejemplo, ['en', 'es', 'pt-br']) o asignarse a una ruta (path) compartida de códigos (por ejemplo, { path: "english", codes: ["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 contienen tus archivos de contenido deben coincidir exactamente con los elementos de locales en la lista. En el caso de múltiples codes que apuntan a un prefijo de ruta de URL personalizado, almacena tus archivos de contenido en una carpeta con el mismo nombre que la ruta (path) configurada.

i18n.defaultLocale

Type: string

Añadido en: astro@3.5.0

El idioma predeterminado (locale) de tu sitio web/aplicación, que es uno de los locales especificados. Este es un campo obligatorio.

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

i18n.fallback

Type: Record<string, string>

Añadido en: astro@3.5.0

La estrategia de respaldo (fallback) al navegar a páginas que no existen (por ejemplo, no se ha creado una página traducida).

Usa este objeto para declarar una ruta de idioma de respaldo (locale fallback) para cada idioma que admitas. Si no se especifica ningún fallback, las páginas no disponibles devolverán un error 404.

Ejemplo

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

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

i18n.routing

Type: object | "manual"
Default: object

Añadido en: astro@3.7.0

Controla la estrategia de enrutamiento para determinar las URLs de tu sitio. Configura esto basándote en la configuración de tu ruta de carpeta/URL para tu idioma predeterminado.

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

Desde la versión 4.6.0, esta opción también se puede establecer en manual. Cuando se habilita esta estrategia de enrutamiento, Astro desactivará su middleware de i18n y no se podrán configurar otras opciones de enrutamiento (routing) (por ejemplo, prefixDefaultLocale). Serás responsable de escribir tu propia lógica de enrutamiento, o ejecutar el middleware i18n de Astro manualmente junto con el tuyo propio.

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr"],
    routing: "manual"
  }
})

i18n.routing.prefixDefaultLocale

Type: boolean
Default: false

Añadido en: astro@3.7.0

Cuando es false, solo los idiomas que no sean el predeterminado 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. URLs serán de la forma example.com/[locale]/content/ para todos los idiomas que no sean el predeterminado, pero example.com/content/ para el locale predeterminado.

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

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

i18n.routing.redirectToDefaultLocale

Type: boolean
Default: false

Añadido en: astro@4.2.0

Configura si la URL de inicio (/) generada por src/pages/index.astro redirigirá o no a /[defaultLocale] cuando se establece prefixDefaultLocale: true.

Establece redirectToDefaultLocale: true para habilitar 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: true
    }
  }
})

i18n.routing.fallbackType

Type: "redirect" | "rewrite"
Default: "redirect"

Añadido en: astro@4.15.0

Cuando i18n.fallback está configurado para evitar mostrar una página 404 para las rutas de página faltantes, esta opción controla si se debe redirigir (redirect) a la página de respaldo o reescribir (rewrite) el contenido de la página de respaldo en el lugar.

Por defecto, el enrutamiento i18n de Astro crea páginas que redirigen a tus visitantes a un nuevo destino basándose en tu configuración de respaldo. El navegador se actualizará y mostrará la dirección de destino en la barra de URL.

Cuando se configura i18n.routing.fallback: "rewrite", Astro creará páginas que rendericen el contenido de la página de respaldo en la URL original solicitada.

Con la siguiente configuración, si tienes el archivo src/pages/en/about.astro pero no src/pages/fr/about.astro, el comando astro build generará dist/fr/about.html con el mismo contenido que la página dist/en/about.html. El visitante de tu sitio verá la versión en inglés de la página en https://example.com/fr/about/ y no será redirigido.

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

i18n.domains

Type: Record<string, string>
Default: {}

Añadido en: astro@4.3.0

Configura el patrón de URL de uno o más idiomas soportados para usar un dominio personalizado (o subdominio).

Cuando un locale se asigna a un dominio, no se utilizará un prefijo de ruta /[locale]/. Sin embargo, todavía se requieren carpetas localizadas dentro de src/pages/, incluso para tu defaultLocale configurado.

Cualquier otro idioma no configurado tendrá por defecto una URL basada en una ruta localizada de acuerdo con tu estrategia prefixDefaultLocale (por ejemplo, https://example.com/[locale]/blog).

export default defineConfig({
   site: "https://example.com",
   output: "server", // required, with no prerendered pages
   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"
    }
  },
})

Tanto las rutas de página construidas como las URLs devueltas por las funciones auxiliares de astro:i18n, getAbsoluteLocaleUrl() y getAbsoluteLocaleUrlList() utilizarán las opciones establecidas en i18n.domains.

Consulta la guía de internacionalización para más detalles, incluyendo las limitaciones de esta característica.

env

Type: object
Default: {}

Añadido en: astro@5.0.0

Opciones de configuración para variables de entorno seguras en cuanto a tipos.

Consulta nuestra guía para obtener más información sobre las variables de entorno en Astro.

env.schema

Type: EnvSchema
Default: {}

Añadido en: astro@5.0.0

Define las variables de entorno que se aplicarán mediante la validación de Zod y para las cuales está disponible el soporte de TypeScript (por ejemplo, autocompletado, seguridad de tipos). Cada clave corresponde al nombre de la variable y el valor al tipo de datos y las validaciones definidas con envField.

Se admiten cuatro tipos de datos: string, number, enumeration y boolean. Cada tipo requiere un contexto (context, client o server), un nivel de acceso (access, public o secret) y validaciones adicionales, como un valor por defecto (default) y una indicación de si la variable es opcional (optional, por defecto false).

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

export default defineConfig({
  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" }),
    }
  }
})

env.validateSecrets

Type: boolean
Default: false

Añadido en: astro@5.0.0

Si se deben validar o no los secretos en el servidor al iniciar el servidor de desarrollo o al ejecutar una construcción.

Por defecto, solo las variables públicas se validan en el servidor al iniciar el servidor de desarrollo o una construcción, y las variables privadas se validan únicamente en tiempo de ejecución. Si se habilita, las variables privadas también se comprobarán al iniciar. Esto es útil en algunos flujos de trabajo de integración continua (CI) para asegurarse de que todos tus secretos estén configurados correctamente antes de realizar el despliegue.

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

export default defineConfig({
  env: {
    schema: {
      // ...
    },
    validateSecrets: true
  }
})

fonts

Type: Array<FontFamily>
Default: []

Añadido en: astro@6.0.0

Configura las fuentes y te permite especificar algunas opciones de personalización para cada fuente.

Consulta nuestra guía para obtener más información sobre el uso de fuentes personalizadas en Astro.

font.provider

Type: FontProvider

Añadido en: astro@6.0.0

La fuente de tus archivos de fuentes. Puedes usar un proveedor integrado o escribir tu propio proveedor personalizado:

import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  fonts: [{
    provider: fontProviders.google(),
    name: "Roboto",
    cssVariable: "--font-roboto"
  }]
});

font.name

Type: string

Añadido en: astro@6.0.0

El nombre de la familia de fuentes, tal como lo identifica tu proveedor de fuentes:

name: "Roboto"

font.cssVariable

Type: string

Añadido en: astro@6.0.0

Un ident válido de tu elección en forma de variable CSS (es decir, que comience con --):

cssVariable: "--font-roboto"

font.fallbacks

Type: Array<string>
Default: ["sans-serif"]

Añadido en: astro@6.0.0

Un array de fuentes a usar cuando la fuente elegida no esté disponible o se esté cargando. Las fuentes de respaldo se elegirán en el orden en que aparecen. Se utilizará la primera fuente disponible:

fallbacks: ["CustomFont", "serif"]

Para deshabilitar las fuentes de respaldo por completo, configura un array vacío:

fallbacks: []

Especifica al menos un nombre de familia genérico que coincida con la apariencia prevista de tu fuente. Astro intentará entonces generar respaldos optimizados utilizando métricas de fuente. Para deshabilitar esta optimización, establece optimizedFallbacks en false.

font.optimizedFallbacks

Type: boolean
Default: true

Añadido en: astro@6.0.0

Indica si se debe habilitar o no la optimización por defecto de Astro al generar fuentes de respaldo. Puedes deshabilitar esta optimización por defecto para tener un control total sobre cómo se generan los valores de fallbacks:

optimizedFallbacks: false

font.weights

Type: Array<(number|string)>
Default: [400]

Añadido en: astro@6.0.0

Un array de pesos de fuente (font weights). Si no se especifica ningún valor en tu configuración, solo se incluye el peso 400 por defecto para evitar descargas innecesarias. Necesitarás incluir esta propiedad para acceder a cualquier otro peso de fuente:

weights: [200, "400", "bold"]

Si la fuente asociada es una fuente variable, puedes especificar un rango de pesos:

weights: ["100 900"]

font.styles

Type: Array<("normal"|"italic"|"oblique")>
Default: ["normal", "italic"]

Añadido en: astro@6.0.0

Un array de estilos de fuente:

styles: ["normal", "oblique"]

font.subsets

Type: Array<string>
Default: ["latin"]

Añadido en: astro@6.0.0

Define una lista de subconjuntos de fuentes a precargar.

subsets: ["latin"]

font.formats

Type: Array<("woff2"|"woff"|"otf"|"ttf"|"eot")>
Default: ["woff2"]

Añadido en: astro@6.0.0

Un array de formatos de fuente:

formats: ["woff2", "woff"]

font.options

Type: Record<string, any>

Añadido en: astro@6.0.0

Un objeto para pasar opciones específicas del proveedor. Se tipa automáticamente según el proveedor de la familia de fuentes:

options: {
  experimental: {
    glyphs: ["a"]
  }
}

font.display

Type: "auto" | "block" | "swap" | "fallback" | "optional"
Default: "swap"

Añadido en: astro@6.0.0

Define cómo se muestra una fuente en función de cuándo se descarga y está lista para su uso:

display: "block"

font.unicodeRange

Type: Array<string>
Default: undefined

Añadido en: astro@6.0.0

Determina cuándo debe descargarse y usarse una fuente en función de un rango específico de caracteres unicode. Si un carácter en la página coincide con el rango configurado, el navegador descargará la fuente y todos los caracteres estarán disponibles para su uso en la página. Para configurar un subconjunto de caracteres precargados para una sola fuente, consulta la propiedad subsets en su lugar.

Esto puede ser útil para la localización a fin de evitar descargas de fuentes innecesarias cuando una parte específica de tu sitio web utiliza un alfabeto diferente y se mostrará con una fuente distinta. Por ejemplo, un sitio web que ofrece versiones en inglés y japonés puede evitar que el navegador descargue la fuente japonesa en las versiones en inglés de la página que no contienen ninguno de los caracteres japoneses proporcionados en unicodeRange.

unicodeRange: ["U+26"]

font.stretch

Type: string
Default: undefined

Añadido en: astro@6.0.0

A estiramiento de fuente:

stretch: "condensed"

font.featureSettings

Type: string
Default: undefined

Añadido en: astro@6.0.0

Controla las características tipográficas de la fuente (por ejemplo, ligaduras, versalitas o adornos):

featureSettings: "'smcp' 2"

font.variationSettings

Type: string
Default: undefined

Añadido en: astro@6.0.0

Ajustes de variación de la fuente:

variationSettings: "'xhgt' 0.7"

cache

Type: object
Default: undefined

Añadido en: astro@7.0.0 Nuevo

Habilita el almacenamiento en caché de rutas para respuestas SSR. Proporciona una API independiente de la plataforma para almacenar en caché páginas renderizadas y respuestas de la API, con proveedores conectables que los adaptadores pueden configurar automáticamente.

import { memoryCache } from 'astro/config';

{
  cache: {
    provider: memoryCache(),
  },
  routeRules: {
    '/blog/[...path]': { maxAge: 300, swr: 60 },
  },
}

Usa Astro.cache.set() en las rutas y context.cache.set() en el middleware o en las rutas de la API para controlar el almacenamiento en caché por solicitud.

cache.provider

Type: CacheProviderConfig

Añadido en: astro@7.0.0 Nuevo

Un proveedor que controla cómo se almacenan en caché las respuestas.

Usa la función de configuración del proveedor para obtener una configuración segura en cuanto a tipos:

import { defineConfig, memoryCache } from 'astro/config';

export default defineConfig({
  cache: { provider: memoryCache() },
});

routeRules

Type: Record<string, RouteRule>
Default: undefined

Añadido en: astro@7.0.0 Nuevo

Patrones de ruta asignados a reglas de caché. Utiliza la misma sintaxis [param] y [...rest] que el enrutamiento basado en archivos. Usa un parámetro [...rest] para coincidir con un grupo de rutas:

import { memoryCache } from 'astro/config';

{
  cache: { provider: memoryCache() },
  routeRules: {
    '/api/[...path]': { swr: 600 },
    '/products/[...slug]': { maxAge: 3600, tags: ['products'] },
  },
}

Contribuir Comunidad Patrocinar

Referencia de configuración

Opciones globales

site

base

trailingSlash

redirects

output

adapter

integrations

root

Ejemplos

srcDir

publicDir

outDir

cacheDir

compressHTML

scopedStyleStrategy

prerenderConflictBehavior

vite

Ejemplos

security

security.checkOrigin

security.allowedDomains

security.actionBodySizeLimit

security.serverIslandBodySizeLimit

security.csp

security.csp.algorithm

security.csp.directives

security.csp.styleDirective

security.csp.styleDirective.hashes

security.csp.styleDirective.resources

security.csp.scriptDirective

security.csp.scriptDirective.hashes

security.csp.scriptDirective.resources

security.csp.scriptDirective.strictDynamic

Opciones de construcción

build.format

Efecto en Astro.url

build.client

build.server

build.assets

build.assetsPrefix

build.serverEntry

build.redirects

build.inlineStylesheets

build.concurrency

Opciones del servidor

server.host

server.port

server.allowedHosts

server.open

server.headers

fetchFile

Opciones del registrador (logger)

logger.entrypoint

logger.config

Opciones de sesión

session.driver

session.options

session.cookie

session.ttl

Opciones de la barra de herramientas de desarrollo

devToolbar.enabled

devToolbar.placement

Opciones de pre-búsqueda (prefetch)

prefetch.prefetchAll

prefetch.defaultStrategy

Opciones de imágenes

image.endpoint

image.service

image.service.config.limitInputPixels

image.service.config.kernel

image.service.config.jpeg

image.service.config.webp

image.service.config.avif

image.service.config.png

image.dangerouslyProcessSVG

image.domains

image.remotePatterns

image.responsiveStyles