Configuration Reference

This page documents all Astro configuration options in astro.config.mjs.

Top-Level Options

site

string

Your final, deployed URL. Astro uses this full URL to generate your sitemap and canonical URLs in your final build.

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

base

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.

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

trailingSlash

'always' | 'never' | 'ignore'

default:"'ignore'"

Set the route matching behavior for trailing slashes in the dev server and on-demand rendered pages.

'ignore' - Match URLs regardless of whether a trailing ”/” exists
'always' - Only match URLs that include a trailing slash (e.g: “/about/”)
'never' - Only match URLs that do not include a trailing slash (e.g: “/about”)

{
  trailingSlash: 'always'
}

redirects

Record<string, RedirectConfig>

default:"{}"

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

{
  redirects: {
    '/old': '/new',
    '/blog/[...slug]': '/articles/[...slug]',
    '/news': {
      status: 302,
      destination: 'https://example.com/news'
    }
  }
}

For statically-generated sites with no adapter, this produces a client redirect using a <meta http-equiv="refresh"> tag. When using SSR or with a static adapter, status codes are supported.

output

'static' | 'server'

default:"'static'"

Specifies the output target for builds.

'static' - Prerender all your pages by default, outputting a completely static site
'server' - Use server-side rendering (SSR) for all pages by default

{
  output: 'server'
}

adapter

AstroIntegration

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

import netlify from '@astrojs/netlify';

{
  adapter: netlify()
}

integrations

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.

import react from '@astrojs/react';
import mdx from '@astrojs/mdx';

{
  integrations: [react(), mdx()]
}

root

string

default:"'.' (current working directory)"

Set the project root. The project root is the directory where your Astro project (and all src, public and package.json files) live.

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

If you provide a relative path, Astro will resolve it against your current working directory.

srcDir

string

default:"'./src'"

Set the directory that Astro will read your site from.

{
  srcDir: './www'
}

publicDir

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.

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

outDir

string

default:"'./dist'"

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

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

cacheDir

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.

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

compressHTML

boolean

default:"true"

Minify your HTML output and reduce the size of your HTML files. By default, Astro removes whitespace from your HTML in a lossless manner.

{
  compressHTML: false
}

scopedStyleStrategy

'where' | 'class' | 'attribute'

default:"'attribute'"

Specify the strategy used for scoping styles within Astro components.

'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

{
  scopedStyleStrategy: 'class'
}

vite

ViteUserConfig

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

{
  vite: {
    ssr: {
      external: ['broken-npm-package']
    }
  }
}

Build Options

build.format

'file' | 'directory' | 'preserve'

default:"'directory'"

Control the output file format of each page.

'file': Generate an HTML file named for each page route (e.g. /about.html)
'directory': Generate a directory with a nested index.html file for each page (e.g. /about/index.html)
'preserve': Generate HTML files exactly as they appear in your source folder

{
  build: {
    format: 'file'
  }
}

build.client

string

default:"'./client'"

Controls the output directory of your client-side CSS and JavaScript when building with SSR. This value is relative to the outDir.

{
  build: {
    client: './client'
  }
}

build.server

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

string

default:"'_astro'"

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

{
  build: {
    assets: '_custom'
  }
}

build.assetsPrefix

string | Record<string, string>

Specifies the prefix for Astro-generated asset links. Use this if assets are served from a different domain than the current site.

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

You can also pass an object to specify different domains for each file type:

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

build.serverEntry

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.

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

build.redirects

boolean

default:"true"

Specifies whether redirects will be output to HTML during the build. This option only applies to output: 'static' mode.

{
  build: {
    redirects: false
  }
}

build.inlineStylesheets

'always' | 'auto' | 'never'

default:"'auto'"

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

'always' - project styles are inlined into <style> tags
'auto' - only stylesheets smaller than 4kb are inlined
'never' - project styles are sent in external stylesheets

{
  build: {
    inlineStylesheets: 'never'
  }
}

build.concurrency

number

default:"1"

The number of pages to build in parallel. In most cases, you should not change the default value of 1.

{
  build: {
    concurrency: 2
  }
}

Server Options

server.host

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]

server.port

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

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

string | boolean

default:"false"

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

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

server.headers

OutgoingHttpHeaders

default:"{}"

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

Image Options

image.service

ImageServiceConfig

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

{
  image: {
    service: {
      entrypoint: 'astro/assets/services/sharp',
      config: {
        limitInputPixels: false
      }
    }
  }
}

image.endpoint

{route: string, entrypoint: string}

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

{
  image: {
    endpoint: {
      route: '/custom_endpoint',
      entrypoint: 'src/my_endpoint.ts'
    }
  }
}

image.domains

string[]

default:"[]"

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

{
  image: {
    domains: ['astro.build']
  }
}

image.remotePatterns

RemotePattern[]

default:"[]"

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

{
  image: {
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com'
    }]
  }
}

You can use wildcards:

hostname: Start with ** to allow all subdomains, or * for one level
pathname: End with /** to allow all sub-routes, or /* for one level

image.layout

'constrained' | 'fixed' | 'full-width'

The default layout type for responsive images. Can be overridden by the layout prop on the image component.

constrained - The image will scale to fit the container, maintaining aspect ratio
fixed - The image will maintain its original dimensions
full-width - The image will scale to fit the container

image.responsiveStyles

boolean

default:"false"

Whether to automatically add global styles for responsive images. Enable this unless you are styling images yourself.

Markdown Options

markdown.syntaxHighlight

'shiki' | 'prism' | false

default:"'shiki'"

Which syntax highlighter to use for Markdown code blocks.

'shiki' - use the Shiki highlighter
'prism' - use the Prism highlighter
false - do not apply syntax highlighting

{
  markdown: {
    syntaxHighlight: 'prism'
  }
}

markdown.shikiConfig

ShikiConfig

Configure Shiki syntax highlighter options.

{
  markdown: {
    shikiConfig: {
      theme: 'dracula',
      wrap: true,
      transformers: []
    }
  }
}

markdown.remarkPlugins

RemarkPlugins

Pass remark plugins to customize how your Markdown is built.

import remarkToc from 'remark-toc';

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

markdown.rehypePlugins

RehypePlugins

Pass rehype plugins to customize how your Markdown’s output HTML is processed.

import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';

{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis]
  }
}

markdown.gfm

boolean

default:"true"

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

{
  markdown: {
    gfm: false
  }
}

markdown.smartypants

boolean

default:"true"

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

{
  markdown: {
    smartypants: false
  }
}

Security Options

security.checkOrigin

boolean

default:"true"

Performs a check that the “origin” header matches the URL sent by each request. This provides Cross-Site Request Forgery (CSRF) protection for SSR pages.

{
  security: {
    checkOrigin: false
  }
}

security.actionBodySizeLimit

number

default:"1048576"

Sets the maximum size in bytes allowed for action request bodies. Default is 1 MB.

{
  security: {
    actionBodySizeLimit: 10 * 1024 * 1024 // 10 MB
  }
}

Session Options

session.driver

SessionDriverConfig

The driver to use for session storage. Some adapters automatically configure a default driver.

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

{
  session: {
    driver: sessionDrivers.redis({
      url: process.env.REDIS_URL
    })
  }
}

session.ttl

number

default:"Infinity"

An optional default time-to-live expiration period for session values, in seconds.

{
  session: {
    ttl: 3600 // 1 hour
  }
}

i18n Options

i18n.locales

Locales

required

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

{
  i18n: {
    locales: ['en', 'es', 'pt-br']
  }
}

You can also map to shared paths:

{
  i18n: {
    locales: [
      'en',
      { path: 'english', codes: ['en', 'en-US'] }
    ]
  }
}

i18n.defaultLocale

string

required

The default locale of your website/application. This is a required field.

{
  i18n: {
    defaultLocale: 'en'
  }
}

i18n.fallback

Record<string, string>

The fallback strategy when navigating to pages that do not exist.

{
  i18n: {
    fallback: {
      'pt-br': 'es',
      'fr': 'en'
    }
  }
}

i18n.routing

object | 'manual'

default:"object"

Controls the routing strategy to determine your site URLs.

{
  i18n: {
    routing: {
      prefixDefaultLocale: false,
      redirectToDefaultLocale: true,
      fallbackType: 'redirect'
    }
  }
}

devToolbar.enabled

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.

devToolbar.placement

The default placement of the Astro Dev Toolbar on the screen.

Prefetch Options

prefetch.prefetchAll

boolean

Enable prefetching for all links, including those without the data-astro-prefetch attribute.

{
  prefetch: {
    prefetchAll: true
  }
}

prefetch.defaultStrategy

'tap' | 'hover' | 'viewport' | 'load'

default:"'hover'"

The default prefetch strategy when the data-astro-prefetch attribute is set with no value.

'tap' - Prefetch just before you click on the link
'hover' - Prefetch when you hover over or focus on the link
'viewport' - Prefetch as the links enter the viewport
'load' - Prefetch all links on the page after the page is loaded

JavaScript API

Runtime API

Configuration

CLI Commands

​Top-Level Options

​site

​base

​trailingSlash

​redirects

​output

​adapter

​integrations

​root

​srcDir

​publicDir

​outDir

​cacheDir

​compressHTML

​scopedStyleStrategy

​vite

​Build Options

​build.format

​build.client

​build.server

​build.assets

​build.assetsPrefix

​build.serverEntry

​build.redirects

​build.inlineStylesheets

​build.concurrency

​Server Options

​server.host

​server.port

​server.allowedHosts

​server.open

​server.headers

​Image Options

​image.service

​image.endpoint

​image.domains

​image.remotePatterns

​image.layout

​image.responsiveStyles

​Markdown Options

​markdown.syntaxHighlight

​markdown.shikiConfig

​markdown.remarkPlugins

​markdown.rehypePlugins

​markdown.gfm

​markdown.smartypants

​Security Options

​security.checkOrigin

​security.actionBodySizeLimit

​Session Options

​session.driver

​session.ttl

​i18n Options

​i18n.locales

​i18n.defaultLocale

​i18n.fallback

​i18n.routing

​Dev Toolbar Options

​devToolbar.enabled

​devToolbar.placement

​Prefetch Options

​prefetch.prefetchAll

​prefetch.defaultStrategy

Build docs developers (and LLMs) love

Top-Level Options

site

base

trailingSlash

redirects

output

adapter

integrations

root

srcDir

publicDir

outDir

cacheDir

compressHTML

scopedStyleStrategy

vite

Build Options

build.format

build.client

build.server

build.assets

build.assetsPrefix

build.serverEntry

build.redirects

build.inlineStylesheets

build.concurrency

Server Options

server.host

server.port

server.allowedHosts

server.open

server.headers

Image Options

image.service

image.endpoint

image.domains

image.remotePatterns

image.layout

image.responsiveStyles

Markdown Options

markdown.syntaxHighlight

markdown.shikiConfig

markdown.remarkPlugins

markdown.rehypePlugins

markdown.gfm

markdown.smartypants

Security Options

security.checkOrigin

security.actionBodySizeLimit

Session Options

session.driver

session.ttl

i18n Options

i18n.locales

i18n.defaultLocale

i18n.fallback

i18n.routing

Dev Toolbar Options

devToolbar.enabled

devToolbar.placement

Prefetch Options

prefetch.prefetchAll

prefetch.defaultStrategy