Contents

astro

Configuration Reference

Astro

Configuration Reference

style-src 'self' 'sha256-somehash';
"

```

You can further customize the <meta> element by enabling this feature with a configuration object that includes additional options.

security.csp.algorithm

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

The hash function to use when generating the hashes of the styles and scripts emitted by Astro.

security.csp.directives

Type: Array<string>
Default: []

A list of CSP directives (beyond script-src and style-src which are included by default) that defines valid sources for specific content types. These directives are added to all pages.

After the build, the <meta> element will add your directives into the content value alongside Astro's default directives:

<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 configuration object that allows you to override the default sources for the style-src directive with the resources property, or to provide additional hashes to be rendered.

security.csp.styleDirective.hashes

Type: Array<CspHash>
Default: []

A list of additional hashes to be rendered.

You must provide hashes that start with sha384-, sha512- or sha256-. Other values will cause a validation error. These hashes are added to all pages.

After the build, the <meta> element will include your additional hashes in the style-src directives:

<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 list of valid sources for style-src directives to override Astro's default sources. This will not include 'self' by default, and must be included in this list if you wish to keep it. These resources are added to all pages.

After the build, the <meta> element will instead apply your sources to the style-src directives:

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

When resources are inserted multiple times or from multiple sources (e.g. defined in your csp config and added using the CSP runtime API), Astro will merge and deduplicate all resources to create your <meta> element.

security.csp.scriptDirective

Type: CspScriptDirective
Default: undefined

A configuration object that allows you to override the default sources for the script-src directive with the resources property, or to provide additional hashes to be rendered.

security.csp.scriptDirective.hashes

Type: Array<CspHash>
Default: []

A list of additional hashes to be rendered.

You must provide hashes that start with sha384-, sha512- or sha256-. Other values will cause a validation error. These hashes are added to all pages.

After the build, the <meta> element will include your additional hashes in the script-src directives:

<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 list of valid sources for the script-src directives to override Astro's default sources. This will not include 'self' by default, and must be included in this list if you wish to keep it. These resources are added to all pages.

After the build, the <meta> element will instead apply your sources to the script-src directives:

<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

Enables the strict-dynamic keyword to support the dynamic injection of scripts.

Build Options

build.format

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

Control the output file format of each page. This value may be set by an adapter for you.

'file': Astro will generate an HTML file named for each page route. (e.g. src/pages/about.astro and src/pages/about/index.astro both build the file /about.html)
'directory': Astro will generate a directory with a nested index.html file for each page. (e.g. src/pages/about.astro and src/pages/about/index.astro both build the file /about/index.html)
'preserve': Astro will generate HTML files exactly as they appear in your source folder. (e.g. src/pages/about.astro builds /about.html and src/pages/about/index.astro builds the file /about/index.html)

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

Effect on Astro.url

Setting build.format controls what Astro.url is set to during the build. When it is:

directory - The Astro.url.pathname will include a trailing slash to mimic folder behavior. (e.g. /foo/)
file - The Astro.url.pathname will include .html. (e.g. /foo.html)

This means that when you create relative URLs using new URL('./relative', Astro.url), you will get consistent behavior between dev and build.

To prevent inconsistencies with trailing slash behaviour in dev, you can restrict the trailingSlash option to 'always' or 'never' depending on your build format:

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

build.client

Type: string
Default: './client'

Controls the output directory of your client-side CSS and JavaScript when building a website with server-rendered pages. outDir controls where the code is built to.

This value is relative to the outDir.

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

build.server

Type: string
Default: './server'

Controls the output directory of server JavaScript when building to SSR.

This value is relative to the outDir.

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

build.assets

Type: string
Default: '_astro'

Specifies the directory in the build output where Astro-generated assets (bundled JS and CSS for example) should live.

{
  build: {
    assets: '_custom'
  }
}

See Also:

outDir

build.assetsPrefix

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

Specifies the prefix for Astro-generated asset links. This can be used if assets are served from a different domain than the current site.

This requires uploading the assets in your local ./dist/_astro folder to a corresponding /_astro/ folder on the remote domain. To rename the _astro path, specify a new directory in build.assets.

To fetch all assets uploaded to the same domain (e.g. https://cdn.example.com/_astro/...), set assetsPrefix to the root domain as a string (regardless of your base configuration):

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

Added in: astro@4.5.0

You can also pass an object to assetsPrefix to specify a different domain for each file type. In this case, a fallback property is required and will be used by default for any other files.

{
  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'

Specifies the file name of the server entrypoint when building to SSR. This entrypoint is usually dependent on which host you are deploying to and will be set by your adapter for you.

Note that it is recommended that this file ends with .mjs so that the runtime detects that the file is a JavaScript module.

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

build.redirects

Type: boolean
Default: true

Specifies whether redirects will be output to HTML during the build. This option only applies to output: 'static' mode; in SSR redirects are treated the same as all responses.

This option is mostly meant to be used by adapters that have special configuration files for redirects and do not need/want HTML based redirects.

{
  build: {
    redirects: false
  }
}

build.inlineStylesheets

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

Control whether project styles are sent to the browser in a separate css file or inlined into <style> tags. Choose from the following options:

'always' - project styles are inlined into <style> tags
'auto' - only stylesheets smaller than ViteConfig.build.assetsInlineLimit (default: 4kb) are inlined. Otherwise, project styles are sent in external stylesheets.
'never' - project styles are sent in external stylesheets

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

build.concurrency

Type: number
Default: 1

The number of pages to build in parallel.

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

Use this option only when other attempts to reduce the overall rendering time (e.g. batch or cache long running tasks like fetch calls or data access) are not possible or are insufficient. If the number is set too high, page rendering may slow down due to insufficient memory resources and because JS is single-threaded.

{
  build: {
    concurrency: 2
  }
}

:::caution[Breaking changes possible] This feature is stable and is not considered experimental. However, this feature is only intended to address difficult performance issues, and breaking changes may occur in a minor release to keep this option as performant as possible. Please check the Astro CHANGELOG for every minor release if you are using this feature. :::

Server Options

Customize the Astro dev server, used by both astro dev and astro preview.

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

To set different configuration based on the command run ("dev", "preview") a function can also be passed to this configuration option.

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

server.host

Type: string | boolean
Default: false

Set which network IP addresses the server should listen on (i.e. non-localhost IPs).

false - do not expose on a network IP address
true - listen on all addresses, including LAN and public addresses
[custom-address] - expose on a network IP address at [custom-address] (ex: 192.168.0.1)

server.port

Type: number
Default: 4321

Set which port the server should listen on.

If the given port is already in use, Astro will automatically try the next available port.

{
  server: { port: 8080 }
}

server.allowedHosts

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

A list of hostnames that Astro is allowed to respond to. When the value is set to true, any hostname is allowed.

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

server.open

Type: string | boolean
Default: false

Controls whether the dev server should open in your browser window on startup.

Pass a full URL string (e.g. "http://example.com") or a pathname (e.g. "/about") to specify the URL to open.

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

server.headers

Type: OutgoingHttpHeaders
Default: {}

Set custom HTTP response headers to be sent in astro dev and astro preview.

fetchFile

Type: string | null
Default: 'fetch'

Customizes the file used as the fetch entrypoint inside srcDir. Defaults to 'fetch', meaning Astro looks for src/fetch.ts (or .js / .mjs / .mts).

The fetch file allows you to compose Astro's request pipeline with the Web Fetch standard or your own Hono middleware.

If you already have a src/fetch.ts file in use for other purposes, define a different filename or set the value to null to disable the entrypoint:

// astro.config.mjs

Learn more about customizing the request pipeline in the advanced routing guide.

Logger Options

Type: LoggerHandlerConfig
Default: undefined

Configures how Astro logs messages during development and production.

By default, Astro uses a built-in logger that outputs human-friendly logs to the console. You can customize this behavior by providing your own logger handler or by using one of the built-in log handlers:

// astro.config.mjs

See the logger API reference for more information.

logger.entrypoint

Type: string

The entrypoint of the log handler. This can be a path to a file in your project or an npm package:

logger.config

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

The configuration object for the log handler. The options depend on the configured logger.

Session Options

Configures session storage for your Astro project. This is used to store session data in a persistent way, so that it can be accessed across different requests.

Some adapters may provide a default session driver, but you can override it with your own configuration:

Session drivers are configured at build time. This means environment variables used in the driver configuration are inlined. You must create your own driver entrypoint to override the configuration at runtime.

See the sessions guide for more information.

session.driver

Type: SessionDriverConfig | undefined

The driver to use for session storage. The Node, Cloudflare, and Netlify adapters automatically configure a default driver for you, but you can specify your own if you would prefer or if you are using an adapter that does not provide one.

See the code syntax highlighting guide for usage and examples.

markdown.syntaxHighlight

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

Which syntax highlighter to use for Markdown code blocks (```), if any. This determines the CSS classes that Astro will apply to your Markdown code blocks.

shiki - use the Shiki highlighter (github-dark theme configured by default)
prism - use the Prism highlighter and provide your own Prism stylesheet
false - do not apply syntax highlighting.

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

For more control over syntax highlighting, you can instead specify a configuration object with the properties listed below.

markdown.syntaxHighlight.type

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

The default CSS classes to apply to Markdown code blocks. (If no other syntax highlighting configuration is needed, you can instead set markdown.syntaxHighlight directly to shiki, prism, or false.)

markdown.syntaxHighlight.excludeLangs

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

An array of languages to exclude from the default syntax highlighting specified in markdown.syntaxHighlight.type. This can be useful when using tools that create diagrams from Markdown code blocks, such as Mermaid.js and D2.

markdown.remarkPlugins

:::caution[Deprecated] Pass remarkPlugins to unified({ remarkPlugins }) from @astrojs/markdown-remark and set it as markdown.processor instead. Will be removed in a future major. :::

Type: RemarkPlugins

Pass remark plugins to customize how your Markdown is built. You can import and apply the plugin function (recommended), or pass the plugin name as a string.


{
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents"} ] ]
  }
}

markdown.rehypePlugins

:::caution[Deprecated] Pass rehypePlugins to unified({ rehypePlugins }) from @astrojs/markdown-remark and set it as markdown.processor instead. Will be removed in a future major. :::

Type: RehypePlugins

Pass rehype plugins to customize how your Markdown's output HTML is processed. You can import and apply the plugin function (recommended), or pass the plugin name as a string.


{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis]
  }
}

markdown.gfm

:::caution[Deprecated] Pass gfm to your processor instead (e.g. unified({ gfm: false })). Will be removed in a future major. :::

Type: boolean
Default: true

Astro uses GitHub-flavored Markdown by default. To disable this, set the gfm flag to false:

{
  markdown: {
    gfm: false,
  }
}

markdown.smartypants

:::caution[Deprecated] Pass smartypants to your processor instead (e.g. unified({ smartypants: false })). Will be removed in a future major. :::

Type: boolean | Smartypants
Default: true

Whether to use the SmartyPants formatter to transform straight quotes into smart quotes, dashes into en/em dashes, and triple dots into ellipses.

To disable this, set the smartypants flag to false.

For more control over typography, you can instead specify a configuration object with the properties supported by retext-smartypants.

markdown.remarkRehype

:::caution[Deprecated] Pass remarkRehype to unified({ remarkRehype }) from @astrojs/markdown-remark and set it as markdown.processor instead. Will be removed in a future major. :::

Type: RemarkRehype

Pass options to 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

Configures the Markdown processor used to render .md files. Defaults to satteri() from @astrojs/markdown-satteri, Astro's native Markdown pipeline.

// astro.config.mjs

To keep the remark/rehype pipeline, install @astrojs/markdown-remark and pass unified():

// astro.config.mjs

i18n

Type: object

Configures i18n routing and allows you to specify some customization options.

See our guide for more information on internationalization in Astro

i18n.locales

Type: Locales

A list of all locales supported by the website. This is a required field.

Languages can be listed either as individual codes (e.g. ['en', 'es', 'pt-br']) or mapped to a shared path of codes (e.g. { path: "english", codes: ["en", "en-US"]}). These codes will be used to determine the URL structure of your deployed site.

No particular language code format or syntax is enforced, but your project folders containing your content files must match exactly the locales items in the list. In the case of multiple codes pointing to a custom URL path prefix, store your content files in a folder with the same name as the path configured.

i18n.defaultLocale

Type: string

The default locale of your website/application, that is one of the specified locales. This is a required field.

No particular language format or syntax is enforced, but we suggest using lower-case and hyphens as needed (e.g. "es", "pt-br") for greatest compatibility.

i18n.fallback

Type: Record<string, string>

The fallback strategy when navigating to pages that do not exist (e.g. a translated page has not been created).

Use this object to declare a fallback locale route for each language you support. If no fallback is specified, then unavailable pages will return a 404.

Example

The following example configures your content fallback strategy to redirect unavailable pages in /pt-br/ to their es version, and unavailable pages in /fr/ to their en version. Unavailable /es/ pages will return a 404.

font.name

Type: string

The font family name, as identified by your font provider:

name: "Roboto"

font.cssVariable

Type: string

A valid ident of your choosing in the form of a CSS variable (i.e. starting with --):

cssVariable: "--font-roboto"

font.fallbacks

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

An array of fonts to use when your chosen font is unavailable, or loading. Fallback fonts will be chosen in the order listed. The first available font will be used:

fallbacks: ["CustomFont", "serif"]

To disable fallback fonts completely, configure an empty array:

fallbacks: []

Specify at least a generic family name matching the intended appearance of your font. Astro will then attempt to generate optimized fallbacks using font metrics. To disable this optimization, set optimizedFallbacks to false.

font.optimizedFallbacks

Type: boolean
Default: true

Whether or not to enable Astro's default optimization when generating fallback fonts. You may disable this default optimization to have full control over how fallbacks are generated:

optimizedFallbacks: false

font.weights

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

An array of font weights. If no value is specified in your configuration, only weight 400 is included by default to prevent unnecessary downloads. You will need to include this property to access any other font weights:

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

If the associated font is a variable font, you can specify a range of weights:

weights: ["100 900"]

font.styles

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

An array of font styles:

styles: ["normal", "oblique"]

font.subsets

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

Defines a list of font subsets to preload.

subsets: ["latin"]

font.formats

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

An array of font formats:

formats: ["woff2", "woff"]

font.options

Type: Record<string, any>

An object to pass provider specific options. It is typed automatically based on the font family provider:

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

font.display

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

Defines how a font displays based on when it is downloaded and ready for use:

display: "block"

font.unicodeRange

Type: Array<string>
Default: undefined

Determines when a font must be downloaded and used based on a specific range of unicode characters. If a character on the page matches the configured range, the browser will download the font and all characters will be available for use on the page. To configure a subset of characters preloaded for a single font, see the subsets property instead.

This can be useful for localization to avoid unnecessary font downloads when a specific part of your website uses a different alphabet and will be displayed with a separate font. For example, a website that offers both English and Japanese versions can prevent the browser from downloading the Japanese font on English versions of the page that do not contain any of the Japanese characters provided in unicodeRange.

unicodeRange: ["U+26"]

font.stretch

Type: string
Default: undefined

A font stretch:

stretch: "condensed"

font.featureSettings

Type: string
Default: undefined

Controls the typographic font features (e.g. ligatures, small caps, or swashes):

featureSettings: "'smcp' 2"

font.variationSettings

Type: string
Default: undefined

Font variation settings:

variationSettings: "'xhgt' 0.7"

cache

Type: object
Default: undefined

Enables route caching for SSR responses. Provides a platform-agnostic API for caching rendered pages and API responses, with pluggable providers that adapters can configure automatically.

// astro.config.mjs

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

Use Astro.cache.set() in routes and context.cache.set() in middleware or API routes to control caching per-request.

cache.provider

Type: CacheProviderConfig

A provider that controls how responses are cached.

Use the provider's config function to get type-safe configuration:

routeRules

Type: Record<string, RouteRule>
Default: undefined

Route patterns mapped to cache rules. Uses the same [param] and [...rest] syntax as file-based routing. Use a [...rest] parameter to match a group of routes:

// astro.config.mjs

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