Skip to content

Configuration Reference

The following reference covers all supported configuration options in Astro. To learn more about configuring Astro, read our guide on Configuring Astro.

astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
// your configuration options here...
})

Type: string

Your final, deployed URL. Astro uses this full URL to generate your sitemap and canonical URLs in your final build. It is strongly recommended that you set this configuration to get the most out of Astro.

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

Type: string

The base path to deploy to. Astro will use this path as the root for your pages and assets both in development and in production build.

In the example below, astro dev will start your server at /docs.

{
base: '/docs'
}

When using this option, all of your static asset imports and URLs should add the base as a prefix. You can access this value via import.meta.env.BASE_URL.

The value of import.meta.env.BASE_URL will be determined by your trailingSlash config, no matter what value you have set for base.

A trailing slash is always included if trailingSlash: "always" is set. If trailingSlash: "never" is set, BASE_URL will not include a trailing slash, even if base includes one.

Additionally, Astro will internally manipulate the configured value of config.base before making it available to integrations. The value of config.base as read by integrations will also be determined by your trailingSlash configuration in the same way.

In the example below, the values of import.meta.env.BASE_URL and config.base when processed will both be /docs:

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

In the example below, the values of import.meta.env.BASE_URL and config.base when processed will both be /docs/:

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

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

Set the route matching behavior of the dev server. Choose from the following options:

  • 'always' - Only match URLs that include a trailing slash (ex: “/foo/“)
  • 'never' - Never match URLs that include a trailing slash (ex: “/foo”)
  • 'ignore' - Match URLs regardless of whether a trailing ”/” exists

Use this configuration option if your production host has strict handling of how trailing slashes work or do not work.

You can also set this if you prefer to be more strict yourself, so that URLs with or without trailing slashes won’t work during development.

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

See Also:

  • build.format

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

Added in: astro@2.9.0

Specify a mapping of redirects where the key is the route to match and the value is the path to redirect to.

You can redirect both static and dynamic routes, but only to the same kind of route. For example you cannot have a '/article': '/blog/[...slug]' redirect.

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

For statically-generated sites with no adapter installed, this will produce a client redirect using a <meta http-equiv="refresh"> tag and does not support status codes.

When using SSR or with a static adapter in output: static mode, status codes are supported. Astro will serve redirected GET requests with a status of 301 and use a status of 308 for any other request method.

You can customize the redirection status code using an object in the redirect config:

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

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

Specifies the output target for builds.

  • 'static' - Building a static site to be deployed to any static host.
  • 'server' - Building an app to be deployed to a host supporting SSR (server-side rendering).
  • 'hybrid' - Building a static site with a few server-side rendered pages.
import { defineConfig } from 'astro/config';
export default defineConfig({
output: 'static'
})

See Also:

  • adapter

Type: AstroIntegration

Deploy to your favorite server, serverless, or edge host with build adapters. Import one of our first-party adapters for Netlify, Vercel, and more to engage Astro SSR.

See our Server-side Rendering guide for more on SSR, and our deployment guides for a complete list of hosts.

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

See Also:

  • output

Type: AstroIntegration[]

Extend Astro with custom integrations. Integrations are your one-stop-shop for adding framework support (like Solid.js), new features (like sitemaps), and new libraries (like Partytown).

Read our Integrations Guide for help getting started with Astro Integrations.

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

Type: string
CLI: --root
Default: "." (current working directory)

You should only provide this option if you run the astro CLI commands in a directory other than the project root directory. Usually, this option is provided via the CLI instead of the Astro config file, since Astro needs to know your project root before it can locate your config file.

If you provide a relative path (ex: --root: './my-project') Astro will resolve it against your current working directory.

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

Type: string
Default: "./src"

Set the directory that Astro will read your site from.

The value can be either an absolute file system path or a path relative to the project root.

{
srcDir: './www'
}

Type: string
Default: "./public"

Set the directory for your static assets. Files in this directory are served at / during dev and copied to your build directory during build. These files are always served or copied as-is, without transform or bundling.

The value can be either an absolute file system path or a path relative to the project root.

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

Type: string
Default: "./dist"

Set the directory that astro build writes your final build to.

The value can be either an absolute file system path or a path relative to the project root.

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

See Also:

  • build.server

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

Set the directory for caching build artifacts. Files in this directory will be used in subsequent builds to speed up the build time.

The value can be either an absolute file system path or a path relative to the project root.

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

Type: boolean
Default: true

This is an option to minify your HTML output and reduce the size of your HTML files. By default, Astro removes all whitespace from your HTML, including line breaks, from .astro components. This occurs both in development mode and in the final build. To disable HTML compression, set the compressHTML flag to false.

{
compressHTML: false
}

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

Added in: astro@2.4

Specify the strategy used for scoping styles within Astro components. Choose from:

  • 'where' - Use :where selectors, causing no specificity increase.
  • 'class' - Use class-based selectors, causing a +1 specificity increase.
  • 'attribute' - Use data- attributes, causing a +1 specificity increase.

Using 'class' is helpful when you want to ensure that element selectors within an Astro component override global style defaults (e.g. from a global stylesheet). Using 'where' gives you more control over specificity, but requires that you use higher-specificity selectors, layers, and other tools to control which selectors are applied. Using 'attribute' is useful when you are manipulating the class attribute of elements and need to avoid conflicts between your own styling logic and Astro’s application of styles.

Type: ViteUserConfig

Pass additional configuration options to Vite. Useful when Astro doesn’t support some advanced configuration that you may need.

View the full vite configuration object documentation on vitejs.dev.

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

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

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; ie /foo/.
  • file - The Astro.url.pathname will include .html; ie /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'

Type: string
Default: './dist/client'

Controls the output directory of your client-side CSS and JavaScript when output: 'server' or output: 'hybrid' only. outDir controls where the code is built to.

This value is relative to the outDir.

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

Type: string
Default: './dist/server'

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

This value is relative to the outDir.

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

Type: string
Default: '_astro'

Added in: astro@2.0.0

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

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

Added in: astro@2.2.0

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

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

Type: boolean
Default: true

Added in: astro@2.6.0

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

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

Added in: astro@2.6.0

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

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

Type: string | boolean
Default: false

Added in: astro@0.24.0

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)

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

Type: string | boolean
Default: false

Added in: astro@4.1.0

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

Type: OutgoingHttpHeaders
Default: {}

Added in: astro@1.7.0

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

Type: boolean
Default: true

Whether to enable the Astro Dev Toolbar. This toolbar allows you to inspect your page islands, see helpful audits on performance and accessibility, and more.

This option is scoped to the entire project, to only disable the toolbar for yourself, run npm run astro preferences disable devToolbar. To disable the toolbar for all your Astro projects, run npm run astro preferences disable devToolbar --global.

Type: boolean | object

Enable prefetching for links on your site to provide faster page transitions. (Enabled by default on pages using the <ViewTransitions /> router. Set prefetch: false to opt out of this behaviour.)

This configuration automatically adds a prefetch script to every page in the project giving you access to the data-astro-prefetch attribute. Add this attribute to any <a /> link on your page to enable prefetching for that page.

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

Further customize the default prefetching behavior using the prefetch.defaultStrategy and prefetch.prefetchAll options.

See the Prefetch guide for more information.

Type: boolean

Enable prefetching for all links, including those without the data-astro-prefetch attribute. This value defaults to true when using the <ViewTransitions /> router. Otherwise, the default value is false.

prefetch: {
prefetchAll: true
}

When set to true, you can disable prefetching individually by setting data-astro-prefetch="false" on any individual links.

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

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

The default prefetch strategy to use when the data-astro-prefetch attribute is set on a link with no value.

  • 'tap': Prefetch just before you click on the link.
  • 'hover': Prefetch when you hover over or focus on the link. (default)
  • 'viewport': Prefetch as the links enter the viewport.
  • 'load': Prefetch all links on the page after the page is loaded.

You can override this default value and select a different strategy for any individual link by setting a value on the attribute.

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

Type: string
Default: undefined

Added in: astro@3.1.0

Set the endpoint to use for image optimization in dev and SSR. Set to undefined to use the default endpoint.

The endpoint will always be injected at /_image.

{
image: {
// Example: Use a custom image endpoint
endpoint: './src/image-endpoint.ts',
},
}

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

Added in: astro@2.1.0

Set which image service is used for Astro’s assets support.

The value should be an object with an entrypoint for the image service to use and optionally, a config object to pass to the service.

The service entrypoint can be either one of the included services, or a third-party package.

{
image: {
// Example: Enable the Sharp-based image service with a custom config
service: {
entrypoint: 'astro/assets/services/sharp',
config: {
limitInputPixels: false,
},
},
},
}

image.service.config.limitInputPixels

Section titled image.service.config.limitInputPixels

Type: number | boolean
Default: true

Added in: astro@4.1.0

Whether or not to limit the size of images that the Sharp image service will process.

Set false to bypass the default image size limit for the Sharp image service and process large images.

Type: Array.<string>
Default: {domains: []}

Added in: astro@2.10.10

Defines a list of permitted image source domains for remote image optimization. No other remote images will be optimized by Astro.

This option requires an array of individual domain names as strings. Wildcards are not permitted. Instead, use image.remotePatterns to define a list of allowed source URL patterns.

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

Type: Array.<RemotePattern>
Default: {remotePatterns: []}

Added in: astro@2.10.10

Defines a list of permitted image source URL patterns for remote image optimization.

remotePatterns can be configured with four properties:

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

You can use wildcards to define the permitted hostname and pathname values as described below. Otherwise, only the exact values provided will be configured: hostname:

  • Start with ’**.’ to allow all subdomains (‘endsWith’).
  • Start with ’*.’ to allow only one level of subdomain.

pathname:

  • End with ’/**’ to allow all sub-routes (‘startsWith’).
  • End with ’/*’ to allow only one level of sub-route.

Type: Partial<ShikiConfig>

Shiki configuration options. See the Markdown configuration docs for usage.

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

Which syntax highlighter to use, if any.

  • shiki - use the Shiki highlighter
  • prism - use the Prism highlighter
  • false - do not apply syntax highlighting.
{
markdown: {
// Example: Switch to use prism for syntax highlighting in Markdown
syntaxHighlight: 'prism',
}
}

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.

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

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.

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

Type: boolean
Default: true

Added in: astro@2.0.0

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

{
markdown: {
gfm: false,
}
}

Type: boolean
Default: true

Added in: astro@2.0.0

Astro uses the SmartyPants formatter by default. To disable this, set the smartypants flag to false:

{
markdown: {
smartypants: false,
}
}

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

Type: object

Added in: astro@3.5.0

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

See our guide for more information on internationalization in Astro

Type: string

Added in: astro@3.5.0

The default locale of your website/application. 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.

Type: Locales

Added in: astro@3.5.0

A list of all locales supported by the website, including the defaultLocale. 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.

Type: Record.<string, string>

Added in: astro@3.5.0

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.

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.

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

Type: Routing

Added in: astro@3.7.0

Controls the routing strategy to determine your site URLs. Set this based on your folder/URL path configuration for your default language.

i18n.routing.prefixDefaultLocale

Section titled i18n.routing.prefixDefaultLocale

Type: boolean
Default: false

Added in: astro@3.7.0

When false, only non-default languages will display a language prefix. The defaultLocale will not show a language prefix and content files do not exist in a localized folder. URLs will be of the form example.com/[locale]/content/ for all non-default languages, but example.com/content/ for the default locale.

When true, all URLs will display a language prefix. URLs will be of the form example.com/[locale]/content/ for every route, including the default language. Localized folders are used for every language, including the default.

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

i18n.routing.redirectToDefaultLocale

Section titled i18n.routing.redirectToDefaultLocale

Type: boolean
Default: true

Added in: astro@4.2.0

Configures whether or not the home URL (/) generated by src/pages/index.astro will redirect to /[defaultLocale] when prefixDefaultLocale: true is set.

Set redirectToDefaultLocale: false to disable this automatic redirection at the root of your site:

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

Type: string

Added in: astro@4.6.0

When this option is enabled, Astro will disable its i18n middleware so that you can implement your own custom logic. No other routing options (e.g. prefixDefaultLocale) may be configured with routing: "manual".

You will be responsible for writing your own routing logic, or executing Astro’s i18n middleware manually alongside your own.

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

To help some users migrate between versions of Astro, we occasionally introduce legacy flags. These flags allow you to opt in to some deprecated or otherwise outdated behavior of Astro in the latest version, so that you can continue to upgrade and take advantage of new Astro releases.

Astro offers experimental flags to give users early access to new features. These flags are not guaranteed to be stable.

experimental.directRenderScript

Section titled experimental.directRenderScript

Type: boolean
Default: false

Added in: astro@4.5.0

Enables a more reliable strategy to prevent scripts from being executed in pages where they are not used.

Scripts will directly render as declared in Astro files (including existing features like TypeScript, importing node_modules, and deduplicating scripts). You can also now conditionally render scripts in your Astro file. However, this means scripts are no longer hoisted to the <head> and multiple scripts on a page are no longer bundled together. If you enable this option, you should check that all your <script> tags behave as expected.

This option will be enabled by default in Astro 5.0.

{
experimental: {
directRenderScript: true,
},
}

Type: boolean
Default: false

Added in: astro@4.8.0 New

Actions help you write type-safe backend functions you can call from anywhere. Enable server rendering using the output property and add the actions flag to the experimental object:

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

Declare all your actions in src/actions/index.ts. This file is the global actions handler.

Define an action using the defineAction() utility from the astro:actions module. These accept the handler property to define your server-side request handler. If your action accepts arguments, apply the input property to validate parameters with Zod.

This example defines two actions: like and comment. The like action accepts a JSON object with a postId string, while the comment action accepts FormData with postId, author, and body strings. Each handler updates your database and return a type-safe response.

src/actions/index.ts
import { defineAction, z } from "astro:actions";
export const server = {
like: defineAction({
input: z.object({ postId: z.string() }),
handler: async ({ postId }) => {
// update likes in db
return likes;
},
}),
comment: defineAction({
accept: 'form',
input: z.object({
postId: z.string(),
author: z.string(),
body: z.string(),
}),
handler: async ({ postId }) => {
// insert comments in db
return comment;
},
}),
};

Then, call an action from your client components using the actions object from astro:actions. You can pass a type-safe object when using JSON, or a FormData object when using accept: 'form' in your action definition:

src/components/blog.tsx
import { actions } from "astro:actions";
import { useState } from "preact/hooks";
export function Like({ postId }: { postId: string }) {
const [likes, setLikes] = useState(0);
return (
<button
onClick={async () => {
const newLikes = await actions.like({ postId });
setLikes(newLikes);
}}
>
{likes} likes
</button>
);
}
export function Comment({ postId }: { postId: string }) {
return (
<form
onSubmit={async (e) => {
e.preventDefault();
const formData = new FormData(e.target);
const result = await actions.blog.comment(formData);
// handle result
}}
>
<input type="hidden" name="postId" value={postId} />
<label for="author">Author</label>
<input id="author" type="text" name="author" />
<textarea rows={10} name="body"></textarea>
<button type="submit">Post</button>
</form>
);
}

For a complete overview, and to give feedback on this experimental API, see the Actions RFC.

experimental.contentCollectionCache

Section titled experimental.contentCollectionCache

Type: boolean
Default: false

Added in: astro@3.5.0

Enables a persistent cache for content collections when building in static mode.

{
experimental: {
contentCollectionCache: true,
},
}

experimental.contentCollectionJsonSchema

Section titled experimental.contentCollectionJsonSchema

Type: boolean
Default: false

Added in: astro@4.5.0

This feature will auto-generate a JSON schema for content collections of type: 'data' which can be used as the $schema value for TypeScript-style autocompletion/hints in tools like VSCode.

To enable this feature, add the experimental flag:

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

This experimental implementation requires you to manually reference the schema in each data entry file of the collection:

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

Alternatively, you can set this in your VSCode json.schemas settings:

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

Note that this initial implementation uses a library with known issues for advanced Zod schemas, so you may wish to consult these limitations before enabling the experimental flag.

Type: boolean
Default: false

Added in: astro@4.2.0

Enables pre-rendering your prefetched pages on the client in supported browsers.

This feature uses the experimental Speculation Rules Web API and enhances the default prefetch behavior globally to prerender links on the client. You may wish to review the possible risks when prerendering on the client before enabling this feature.

Enable client side prerendering in your astro.config.mjs along with any desired prefetch configuration options:

astro.config.mjs
{
prefetch: {
prefetchAll: true,
defaultStrategy: 'viewport',
},
experimental: {
clientPrerender: true,
},
}

Continue to use the data-astro-prefetch attribute on any <a /> link on your site to opt in to prefetching. Instead of appending a <link> tag to the head of the document or fetching the page with JavaScript, a <script> tag will be appended with the corresponding speculation rules.

Client side prerendering requires browser support. If the Speculation Rules API is not supported, prefetch will fallback to the supported strategy.

See the Prefetch Guide for more prefetch options and usage.

experimental.globalRoutePriority

Section titled experimental.globalRoutePriority

Type: boolean
Default: false

Added in: astro@4.2.0

Prioritizes redirects and injected routes equally alongside file-based project routes, following the same route priority order rules for all routes.

This allows more control over routing in your project by not automatically prioritizing certain types of routes, and standardizes the route priority ordering for all routes.

The following example shows which route will build certain page URLs when file-based routes, injected routes, and redirects are combined as shown below:

  • File-based route: /blog/post/[pid]
  • File-based route: /[page]
  • Injected route: /blog/[...slug]
  • Redirect: /blog/tags/[tag] -> /[tag]
  • Redirect: /posts -> /blog

With experimental.globalRoutingPriority enabled (instead of Astro 4.0 default route priority order):

  • /blog/tags/astro is built by the redirect to /tags/[tag] (instead of the injected route /blog/[...slug])
  • /blog/post/0 is built by the file-based route /blog/post/[pid] (instead of the injected route /blog/[...slug])
  • /posts is built by the redirect to /blog (instead of the file-based route /[page])

In the event of route collisions, where two routes of equal route priority attempt to build the same URL, Astro will log a warning identifying the conflicting routes.

Type: boolean
Default: false

Added in: astro@4.3.0

Enables domain support for the experimental domains routing strategy which allows you to configure the URL pattern of one or more supported languages to use a custom domain (or sub-domain).

When a locale is mapped to a domain, a /[locale]/ path prefix will not be used. However, localized folders within src/pages/ are still required, including for your configured defaultLocale.

Any other locale not configured will default to a localized path-based URL according to your prefixDefaultLocale strategy (e.g. https://example.com/[locale]/blog).

astro.config.mjs
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",
},
},
experimental: {
i18nDomains: true,
},
});

Both page routes built and URLs returned by the astro:i18n helper functions getAbsoluteLocaleUrl() and getAbsoluteLocaleUrlList() will use the options set in i18n.domains.

See the Internationalization Guide for more details, including the limitations of this experimental feature.

Type: boolean
Default: false

Added in: astro@4.6.0

Enables CSRF protection for Astro websites.

The CSRF protection works only for pages rendered on demand (SSR) using server or hybrid mode. The pages must opt out of prerendering in hybrid mode.

astro.config.mjs
export default defineConfig({
output: "server",
experimental: {
security: {
csrfProtection: {
origin: true
}
}
}
})

Type: boolean
Default: false

Added in: astro@4.8.0 New

Enables a routing feature for rewriting requests in Astro pages, endpoints and Astro middleware, giving you programmatic control over your routes.

{
experimental: {
rewriting: true,
},
}

Use Astro.rewrite in your .astro files to reroute to a different page:

src/pages/dashboard.astro
---
if (!Astro.props.allowed) {
return Astro.rewrite("/")
}
---

Use context.rewrite in your endpoint files to reroute to a different page:

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

Use next("/") in your middleware file to reroute to a different page, and then call the next middleware function:

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

For a complete overview, and to give feedback on this experimental API, see the Rerouting RFC.