> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/config/overview).

## Top-Level Options

These options configure fundamental aspects of your Astro project.

### `site`

<ParamField path="site" type="string">
  Your final, deployed URL. Astro uses this to generate your sitemap and canonical URLs.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    site: 'https://www.my-site.dev'
  });
  ```
</ParamField>

<Tip>
  It's strongly recommended to set `site` to get the most out of Astro's SEO and sitemap features.
</Tip>

### `base`

<ParamField path="base" type="string" default="/">
  The base path to deploy to. Astro uses this path as the root for pages and assets in development and production.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    base: '/docs'
  });
  ```
</ParamField>

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

```astro title="src/pages/index.astro" theme={null}
<a href={`${import.meta.env.BASE_URL}about`}>About</a>
```

### `trailingSlash`

<ParamField path="trailingSlash" type="'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`)

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    trailingSlash: 'always'
  });
  ```
</ParamField>

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

### `output`

<ParamField path="output" type="'static' | 'server'" default="'static'">
  Specifies the output target for builds.

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

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    output: 'server'
  });
  ```
</ParamField>

### `adapter`

<ParamField path="adapter" type="AstroIntegration">
  Deploy adapter for SSR. Required when `output: 'server'`.

  ```js title="astro.config.mjs" theme={null}
  import netlify from '@astrojs/netlify';

  export default defineConfig({
    output: 'server',
    adapter: netlify()
  });
  ```
</ParamField>

<CardGroup cols={2}>
  <Card title="Node.js" href="/integrations/adapters">
    Deploy to Node.js servers
  </Card>

  <Card title="Vercel" href="/integrations/adapters">
    Deploy to Vercel
  </Card>

  <Card title="Netlify" href="/integrations/adapters">
    Deploy to Netlify
  </Card>

  <Card title="Cloudflare" href="/integrations/adapters">
    Deploy to Cloudflare
  </Card>
</CardGroup>

### `integrations`

<ParamField path="integrations" type="AstroIntegration[]">
  Extend Astro with integrations for frameworks, features, and libraries.

  ```js title="astro.config.mjs" theme={null}
  import react from '@astrojs/react';
  import tailwind from '@astrojs/tailwind';

  export default defineConfig({
    integrations: [react(), tailwind()]
  });
  ```
</ParamField>

### `redirects`

<ParamField path="redirects" type="Record<string, RedirectConfig>" default="{}">
  Define URL redirects. Keys are routes to match, values are destinations.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    redirects: {
      '/old': '/new',
      '/blog/[...slug]': '/articles/[...slug]',
      '/news': {
        status: 302,
        destination: 'https://example.com/news'
      }
    }
  });
  ```
</ParamField>

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

## Directory Options

Customize project directory structure.

### `root`

<ParamField path="root" type="string" default="'.'">
  The project root directory. Usually provided via CLI instead of config.

  ```bash theme={null}
  astro dev --root ./my-project
  ```
</ParamField>

### `srcDir`

<ParamField path="srcDir" type="string" default="'./src'">
  The directory where Astro reads your site source files.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    srcDir: './www'
  });
  ```
</ParamField>

### `publicDir`

<ParamField path="publicDir" type="string" default="'./public'">
  Directory for static assets served at `/` and copied as-is to build output.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    publicDir: './static'
  });
  ```
</ParamField>

### `outDir`

<ParamField path="outDir" type="string" default="'./dist'">
  The directory where `astro build` writes the final build.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    outDir: './build'
  });
  ```
</ParamField>

### `cacheDir`

<ParamField path="cacheDir" type="string" default="'./node_modules/.astro'">
  Directory for caching build artifacts to speed up subsequent builds.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    cacheDir: './.cache'
  });
  ```
</ParamField>

## Build Options

Configure the build output and optimization.

### `build.format`

<ParamField path="build.format" type="'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

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    build: {
      format: 'file'
    }
  });
  ```
</ParamField>

<Info>
  The `format` affects `Astro.url.pathname` during build. Use with `trailingSlash` for consistent URLs.
</Info>

### `build.client`

<ParamField path="build.client" type="string" default="'./client'">
  Output directory for client-side CSS and JavaScript (relative to `outDir`).

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    build: {
      client: './browser'
    }
  });
  ```
</ParamField>

### `build.server`

<ParamField path="build.server" type="string" default="'./server'">
  Output directory for server JavaScript when building to SSR (relative to `outDir`).

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    build: {
      server: './ssr'
    }
  });
  ```
</ParamField>

### `build.assets`

<ParamField path="build.assets" type="string" default="'_astro'">
  Directory name for Astro-generated assets (bundled JS, CSS).

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    build: {
      assets: '_assets'
    }
  });
  ```
</ParamField>

### `build.assetsPrefix`

<ParamField path="build.assetsPrefix" type="string | Record<string, string>">
  CDN prefix for Astro-generated asset links.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    build: {
      assetsPrefix: 'https://cdn.example.com'
    }
  });
  ```
</ParamField>

For per-file-type CDNs:

```js title="astro.config.mjs" theme={null}
export default defineConfig({
  build: {
    assetsPrefix: {
      js: 'https://js.cdn.example.com',
      css: 'https://css.cdn.example.com',
      fallback: 'https://cdn.example.com'
    }
  }
});
```

### `build.inlineStylesheets`

<ParamField path="build.inlineStylesheets" type="'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

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    build: {
      inlineStylesheets: 'never'
    }
  });
  ```
</ParamField>

## Server Options

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

### `server.port`

<ParamField path="server.port" type="number" default="4321">
  The port the dev server listens on.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    server: {
      port: 8080
    }
  });
  ```
</ParamField>

<Note>
  If the port is in use, Astro automatically tries the next available port.
</Note>

### `server.host`

<ParamField path="server.host" type="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

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    server: {
      host: true
    }
  });
  ```
</ParamField>

### `server.open`

<ParamField path="server.open" type="string | boolean" default="false">
  Open the browser on dev server startup.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    server: {
      open: '/about'  // Open to /about page
    }
  });
  ```
</ParamField>

### `server.headers`

<ParamField path="server.headers" type="OutgoingHttpHeaders" default="{}">
  Custom HTTP response headers for `astro dev` and `astro preview`.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    server: {
      headers: {
        'X-Custom-Header': 'value'
      }
    }
  });
  ```
</ParamField>

### Dynamic Server Configuration

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

```js title="astro.config.mjs" theme={null}
export default defineConfig({
  server: ({ command }) => ({
    port: command === 'dev' ? 4321 : 4000
  })
});
```

## Security Options

Enable security features for SSR pages.

### `security.checkOrigin`

<ParamField path="security.checkOrigin" type="boolean" default="true">
  Verify that the "origin" header matches the request URL to provide CSRF protection.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    security: {
      checkOrigin: false  // Not recommended
    }
  });
  ```
</ParamField>

<Warning>
  Only disable `checkOrigin` if you understand the security implications and have other CSRF protections in place.
</Warning>

## Styling Options

### `scopedStyleStrategy`

<ParamField path="scopedStyleStrategy" type="'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)

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    scopedStyleStrategy: 'class'
  });
  ```
</ParamField>

### `compressHTML`

<ParamField path="compressHTML" type="boolean" default="true">
  Minify HTML output to reduce file size.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    compressHTML: false
  });
  ```
</ParamField>

## Advanced Options

### `vite`

<ParamField path="vite" type="ViteUserConfig">
  Pass additional configuration to Vite. See [Vite Configuration](/config/vite) for details.

  ```js title="astro.config.mjs" theme={null}
  export default defineConfig({
    vite: {
      ssr: {
        external: ['broken-npm-package']
      }
    }
  });
  ```
</ParamField>

## Next Steps

<CardGroup cols={2}>
  <Card title="TypeScript Config" icon="code" href="/config/typescript">
    Configure TypeScript for your project
  </Card>

  <Card title="Vite Config" icon="bolt" href="/config/vite">
    Advanced Vite configuration options
  </Card>

  <Card title="Environment Variables" icon="key" href="/features/env-variables">
    Use environment variables in your project
  </Card>

  <Card title="Integrations" icon="puzzle-piece" href="/integrations/overview">
    Extend Astro with integrations
  </Card>
</CardGroup>