Astro Configuration Reference

Complete reference for astro.config.mjs configuration options

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