Astro Configuration Reference

This page documents all available configuration options in astro.config.mjs. For an introduction to Astro configuration, see the Configuration Overview.

Top-Level Options

These options configure fundamental aspects of your Astro project.

`site`

site

string

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

astro.config.mjs

export default defineConfig({
  site: 'https://www.my-site.dev'
});

It’s strongly recommended to set site to get the most out of Astro’s SEO and sitemap features.

`base`

base

string

default:"/"

The base path to deploy to. Astro uses this path as the root for pages and assets in development and production.

astro.config.mjs

export default defineConfig({
  base: '/docs'
});

When using base, all asset imports and URLs should include the base prefix. Access it via import.meta.env.BASE_URL:

src/pages/index.astro

<a href={`${import.meta.env.BASE_URL}about`}>About</a>

`trailingSlash`

trailingSlash

'always' | 'never' | 'ignore'

default:"'ignore'"

Control URL trailing slash behavior in the dev server and on-demand rendered pages.

ignore: Match URLs regardless of trailing slash
always: Only match URLs with a trailing slash (e.g., /about/)
never: Only match URLs without a trailing slash (e.g., /about)

astro.config.mjs

export default defineConfig({
  trailingSlash: 'always'
});

In production, requests for the wrong format will redirect (301 for GET, 308 for other methods).

`output`

output

'static' | 'server'

default:"'static'"

Specifies the output target for builds.

static: Build a static site (prerendered HTML)
server: Build for server-side rendering (SSR)

astro.config.mjs

export default defineConfig({
  output: 'server'
});

`adapter`

adapter

AstroIntegration

Deploy adapter for SSR. Required when output: 'server'.

astro.config.mjs

import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'server',
  adapter: netlify()
});

Node.js

Deploy to Node.js servers

Vercel

Deploy to Vercel

Netlify

Deploy to Netlify

Cloudflare

Deploy to Cloudflare

`integrations`

integrations

AstroIntegration[]

Extend Astro with integrations for frameworks, features, and libraries.

astro.config.mjs

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

export default defineConfig({
  integrations: [react(), tailwind()]
});

`redirects`

redirects

Record<string, RedirectConfig>

default:"{}"

Define URL redirects. Keys are routes to match, values are destinations.

astro.config.mjs

export default defineConfig({
  redirects: {
    '/old': '/new',
    '/blog/[...slug]': '/articles/[...slug]',
    '/news': {
      status: 302,
      destination: 'https://example.com/news'
    }
  }
});

Static sites use a <meta http-equiv="refresh"> tag. SSR and adapter-enabled static sites support status codes.

Directory Options

Customize project directory structure.

`root`

root

string

default:"'.'"

The project root directory. Usually provided via CLI instead of config.

astro dev --root ./my-project

`srcDir`

srcDir

string

default:"'./src'"

The directory where Astro reads your site source files.

astro.config.mjs

export default defineConfig({
  srcDir: './www'
});

`publicDir`

publicDir

string

default:"'./public'"

Directory for static assets served at / and copied as-is to build output.

astro.config.mjs

export default defineConfig({
  publicDir: './static'
});

`outDir`

outDir

string

default:"'./dist'"

The directory where astro build writes the final build.

astro.config.mjs

export default defineConfig({
  outDir: './build'
});

`cacheDir`

cacheDir

string

default:"'./node_modules/.astro'"

Directory for caching build artifacts to speed up subsequent builds.

astro.config.mjs

export default defineConfig({
  cacheDir: './.cache'
});

Build Options

Configure the build output and optimization.

`build.format`

build.format

'file' | 'directory' | 'preserve'

default:"'directory'"

Control the output file format for each page.

file: Generate about.html for each page
directory: Generate about/index.html for each page
preserve: Keep the same structure as source files

astro.config.mjs

export default defineConfig({
  build: {
    format: 'file'
  }
});

The format affects Astro.url.pathname during build. Use with trailingSlash for consistent URLs.

`build.client`

build.client

string

default:"'./client'"

Output directory for client-side CSS and JavaScript (relative to outDir).

astro.config.mjs

export default defineConfig({
  build: {
    client: './browser'
  }
});

`build.server`

build.server

string

default:"'./server'"

Output directory for server JavaScript when building to SSR (relative to outDir).

astro.config.mjs

export default defineConfig({
  build: {
    server: './ssr'
  }
});

`build.assets`

build.assets

string

default:"'_astro'"

Directory name for Astro-generated assets (bundled JS, CSS).

astro.config.mjs

export default defineConfig({
  build: {
    assets: '_assets'
  }
});

`build.assetsPrefix`

build.assetsPrefix

string | Record<string, string>

CDN prefix for Astro-generated asset links.

astro.config.mjs

export default defineConfig({
  build: {
    assetsPrefix: 'https://cdn.example.com'
  }
});

For per-file-type CDNs:

astro.config.mjs

export default defineConfig({
  build: {
    assetsPrefix: {
      js: 'https://js.cdn.example.com',
      css: 'https://css.cdn.example.com',
      fallback: 'https://cdn.example.com'
    }
  }
});

`build.inlineStylesheets`

build.inlineStylesheets

'always' | 'auto' | 'never'

default:"'auto'"

Control whether styles are inlined or in separate CSS files.

always: Inline all styles in <style> tags
auto: Inline only stylesheets smaller than 4kb
never: Send all styles in external files

astro.config.mjs

export default defineConfig({
  build: {
    inlineStylesheets: 'never'
  }
});

Server Options

Customize the Astro dev server for astro dev and astro preview.

`server.port`

server.port

number

default:"4321"

The port the dev server listens on.

astro.config.mjs

export default defineConfig({
  server: {
    port: 8080
  }
});

If the port is in use, Astro automatically tries the next available port.

`server.host`

server.host

string | boolean

default:"false"

Set which network IP addresses the server listens on.

false: Don’t expose on network IP
true: Listen on all addresses (LAN and public)
[custom-address]: Expose on specific IP address

astro.config.mjs

export default defineConfig({
  server: {
    host: true
  }
});

`server.open`

server.open

string | boolean

default:"false"

Open the browser on dev server startup.

astro.config.mjs

export default defineConfig({
  server: {
    open: '/about'  // Open to /about page
  }
});

`server.headers`

server.headers

OutgoingHttpHeaders

default:"{}"

Custom HTTP response headers for astro dev and astro preview.

astro.config.mjs

export default defineConfig({
  server: {
    headers: {
      'X-Custom-Header': 'value'
    }
  }
});

Dynamic Server Configuration

You can provide a function to configure the server based on the command:

astro.config.mjs

export default defineConfig({
  server: ({ command }) => ({
    port: command === 'dev' ? 4321 : 4000
  })
});

Security Options

Enable security features for SSR pages.

`security.checkOrigin`

security.checkOrigin

boolean

default:"true"

Verify that the “origin” header matches the request URL to provide CSRF protection.

astro.config.mjs

export default defineConfig({
  security: {
    checkOrigin: false  // Not recommended
  }
});

Only disable checkOrigin if you understand the security implications and have other CSRF protections in place.

Styling Options

`scopedStyleStrategy`

scopedStyleStrategy

'where' | 'class' | 'attribute'

default:"'attribute'"

Strategy for scoping styles within Astro components.

where: Use :where selectors (no specificity increase)
class: Use class-based selectors (+1 specificity)
attribute: Use data- attributes (+1 specificity)

astro.config.mjs

export default defineConfig({
  scopedStyleStrategy: 'class'
});

`compressHTML`

compressHTML

boolean

default:"true"

Minify HTML output to reduce file size.

astro.config.mjs

export default defineConfig({
  compressHTML: false
});

Advanced Options

`vite`

vite

ViteUserConfig

Pass additional configuration to Vite. See Vite Configuration for details.

astro.config.mjs

export default defineConfig({
  vite: {
    ssr: {
      external: ['broken-npm-package']
    }
  }
});

Next Steps

TypeScript Config

Configure TypeScript for your project

Vite Config

Advanced Vite configuration options

Environment Variables

Use environment variables in your project

Integrations

Extend Astro with integrations

Get Started

Core Concepts

Features

Integrations

Configuration

Guides

​Top-Level Options

​site

​base

​trailingSlash

​output

​adapter

Node.js

Vercel

Netlify

Cloudflare

​integrations

​redirects

​Directory Options

​root

​srcDir

​publicDir

​outDir

​cacheDir

​Build Options

​build.format

​build.client

​build.server

​build.assets

​build.assetsPrefix

​build.inlineStylesheets

​Server Options

​server.port

​server.host

​server.open

​server.headers

​Dynamic Server Configuration

​Security Options

​security.checkOrigin

​Styling Options

​scopedStyleStrategy

​compressHTML

​Advanced Options

​vite

​Next Steps

TypeScript Config

Vite Config

Environment Variables

Integrations

Build docs developers (and LLMs) love

Top-Level Options

`site`

`base`

`trailingSlash`

`output`

`adapter`

`integrations`

`redirects`

Directory Options

`root`

`srcDir`

`publicDir`

`outDir`

`cacheDir`

Build Options

`build.format`

`build.client`

`build.server`

`build.assets`

`build.assetsPrefix`

`build.inlineStylesheets`

Server Options

`server.port`

`server.host`

`server.open`

`server.headers`

Dynamic Server Configuration

Security Options

`security.checkOrigin`

Styling Options

`scopedStyleStrategy`

`compressHTML`

Advanced Options

`vite`

Next Steps