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

# Configuration Reference

> Complete reference for astro.config.mjs configuration options

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

## Top-Level Options

### site

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

  ```js theme={null}
  {
    site: 'https://www.my-site.dev'
  }
  ```
</ParamField>

### base

<ParamField path="base" 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.

  ```js theme={null}
  {
    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`.
</ParamField>

### trailingSlash

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

  ```js theme={null}
  {
    trailingSlash: 'always'
  }
  ```
</ParamField>

### redirects

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

  ```js theme={null}
  {
    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.
</ParamField>

### output

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

  ```js theme={null}
  {
    output: 'server'
  }
  ```
</ParamField>

### adapter

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

  ```js theme={null}
  import netlify from '@astrojs/netlify';

  {
    adapter: netlify()
  }
  ```
</ParamField>

### integrations

<ParamField path="integrations" 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.

  ```js theme={null}
  import react from '@astrojs/react';
  import mdx from '@astrojs/mdx';

  {
    integrations: [react(), mdx()]
  }
  ```
</ParamField>

### root

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

  ```js theme={null}
  {
    root: './my-project-directory'
  }
  ```

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

### srcDir

<ParamField path="srcDir" type="string" default="'./src'">
  Set the directory that Astro will read your site from.

  ```js theme={null}
  {
    srcDir: './www'
  }
  ```
</ParamField>

### publicDir

<ParamField path="publicDir" 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.

  ```js theme={null}
  {
    publicDir: './my-custom-publicDir-directory'
  }
  ```
</ParamField>

### outDir

<ParamField path="outDir" type="string" default="'./dist'">
  Set the directory that `astro build` writes your final build to.

  ```js theme={null}
  {
    outDir: './my-custom-build-directory'
  }
  ```
</ParamField>

### cacheDir

<ParamField path="cacheDir" 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.

  ```js theme={null}
  {
    cacheDir: './my-custom-cache-directory'
  }
  ```
</ParamField>

### compressHTML

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

  ```js theme={null}
  {
    compressHTML: false
  }
  ```
</ParamField>

### scopedStyleStrategy

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

  ```js theme={null}
  {
    scopedStyleStrategy: 'class'
  }
  ```
</ParamField>

### vite

<ParamField path="vite" type="ViteUserConfig">
  Pass additional configuration options to Vite. Useful when Astro doesn't support some advanced configuration that you may need.

  ```js theme={null}
  {
    vite: {
      ssr: {
        external: ['broken-npm-package']
      }
    }
  }
  ```
</ParamField>

## Build Options

### build.format

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

  ```js theme={null}
  {
    build: {
      format: 'file'
    }
  }
  ```
</ParamField>

### build.client

<ParamField path="build.client" type="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`.

  ```js theme={null}
  {
    build: {
      client: './client'
    }
  }
  ```
</ParamField>

### build.server

<ParamField path="build.server" type="string" default="'./server'">
  Controls the output directory of server JavaScript when building to SSR. This value is relative to the `outDir`.

  ```js theme={null}
  {
    build: {
      server: './server'
    }
  }
  ```
</ParamField>

### build.assets

<ParamField path="build.assets" type="string" default="'_astro'">
  Specifies the directory in the build output where Astro-generated assets (bundled JS and CSS) should live.

  ```js theme={null}
  {
    build: {
      assets: '_custom'
    }
  }
  ```
</ParamField>

### build.assetsPrefix

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

  ```js theme={null}
  {
    build: {
      assetsPrefix: 'https://cdn.example.com'
    }
  }
  ```

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

  ```js theme={null}
  {
    build: {
      assetsPrefix: {
        'js': 'https://js.cdn.example.com',
        'css': 'https://css.cdn.example.com',
        'fallback': 'https://cdn.example.com'
      }
    }
  }
  ```
</ParamField>

### build.serverEntry

<ParamField path="build.serverEntry" 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.

  ```js theme={null}
  {
    build: {
      serverEntry: 'main.mjs'
    }
  }
  ```
</ParamField>

### build.redirects

<ParamField path="build.redirects" type="boolean" default="true">
  Specifies whether redirects will be output to HTML during the build. This option only applies to `output: 'static'` mode.

  ```js theme={null}
  {
    build: {
      redirects: false
    }
  }
  ```
</ParamField>

### build.inlineStylesheets

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

  ```js theme={null}
  {
    build: {
      inlineStylesheets: 'never'
    }
  }
  ```
</ParamField>

### build.concurrency

<ParamField path="build.concurrency" type="number" default="1">
  The number of pages to build in parallel. In most cases, you should not change the default value of 1.

  ```js theme={null}
  {
    build: {
      concurrency: 2
    }
  }
  ```
</ParamField>

## Server Options

### server.host

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

### server.port

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

  ```js theme={null}
  {
    server: { port: 8080 }
  }
  ```
</ParamField>

### server.allowedHosts

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

  ```js theme={null}
  {
    server: {
      allowedHosts: ['staging.example.com', 'qa.example.com']
    }
  }
  ```
</ParamField>

### server.open

<ParamField path="server.open" type="string | boolean" default="false">
  Controls whether the dev server should open in your browser window on startup.

  ```js theme={null}
  {
    server: { open: "/about" }
  }
  ```
</ParamField>

### server.headers

<ParamField path="server.headers" type="OutgoingHttpHeaders" default="{}">
  Set custom HTTP response headers to be sent in `astro dev` and `astro preview`.
</ParamField>

## Image Options

### image.service

<ParamField path="image.service" type="ImageServiceConfig">
  Set which image service is used for Astro's assets support.

  ```js theme={null}
  {
    image: {
      service: {
        entrypoint: 'astro/assets/services/sharp',
        config: {
          limitInputPixels: false
        }
      }
    }
  }
  ```
</ParamField>

### image.endpoint

<ParamField path="image.endpoint" type="{route: string, entrypoint: string}">
  Set the endpoint to use for image optimization in dev and SSR.

  ```js theme={null}
  {
    image: {
      endpoint: {
        route: '/custom_endpoint',
        entrypoint: 'src/my_endpoint.ts'
      }
    }
  }
  ```
</ParamField>

### image.domains

<ParamField path="image.domains" type="string[]" default="[]">
  Defines a list of permitted image source domains for remote image optimization. No other remote images will be optimized by Astro.

  ```js theme={null}
  {
    image: {
      domains: ['astro.build']
    }
  }
  ```
</ParamField>

### image.remotePatterns

<ParamField path="image.remotePatterns" type="RemotePattern[]" default="[]">
  Defines a list of permitted image source URL patterns for remote image optimization.

  ```js theme={null}
  {
    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
</ParamField>

### image.layout

<ParamField path="image.layout" type="'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
</ParamField>

### image.responsiveStyles

<ParamField path="image.responsiveStyles" type="boolean" default="false">
  Whether to automatically add global styles for responsive images. Enable this unless you are styling images yourself.
</ParamField>

## Markdown Options

### markdown.syntaxHighlight

<ParamField path="markdown.syntaxHighlight" type="'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

  ```js theme={null}
  {
    markdown: {
      syntaxHighlight: 'prism'
    }
  }
  ```
</ParamField>

### markdown.shikiConfig

<ParamField path="markdown.shikiConfig" type="ShikiConfig">
  Configure Shiki syntax highlighter options.

  ```js theme={null}
  {
    markdown: {
      shikiConfig: {
        theme: 'dracula',
        wrap: true,
        transformers: []
      }
    }
  }
  ```
</ParamField>

### markdown.remarkPlugins

<ParamField path="markdown.remarkPlugins" type="RemarkPlugins">
  Pass remark plugins to customize how your Markdown is built.

  ```js theme={null}
  import remarkToc from 'remark-toc';

  {
    markdown: {
      remarkPlugins: [[remarkToc, { heading: "contents" }]]
    }
  }
  ```
</ParamField>

### markdown.rehypePlugins

<ParamField path="markdown.rehypePlugins" type="RehypePlugins">
  Pass rehype plugins to customize how your Markdown's output HTML is processed.

  ```js theme={null}
  import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';

  {
    markdown: {
      rehypePlugins: [rehypeAccessibleEmojis]
    }
  }
  ```
</ParamField>

### markdown.gfm

<ParamField path="markdown.gfm" type="boolean" default="true">
  Astro uses GitHub-flavored Markdown by default. To disable this, set the `gfm` flag to `false`.

  ```js theme={null}
  {
    markdown: {
      gfm: false
    }
  }
  ```
</ParamField>

### markdown.smartypants

<ParamField path="markdown.smartypants" type="boolean" default="true">
  Astro uses the SmartyPants formatter by default. To disable this, set the `smartypants` flag to `false`.

  ```js theme={null}
  {
    markdown: {
      smartypants: false
    }
  }
  ```
</ParamField>

## Security Options

### security.checkOrigin

<ParamField path="security.checkOrigin" type="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.

  ```js theme={null}
  {
    security: {
      checkOrigin: false
    }
  }
  ```
</ParamField>

### security.actionBodySizeLimit

<ParamField path="security.actionBodySizeLimit" type="number" default="1048576">
  Sets the maximum size in bytes allowed for action request bodies. Default is 1 MB.

  ```js theme={null}
  {
    security: {
      actionBodySizeLimit: 10 * 1024 * 1024 // 10 MB
    }
  }
  ```
</ParamField>

## Session Options

### session.driver

<ParamField path="session.driver" type="SessionDriverConfig">
  The driver to use for session storage. Some adapters automatically configure a default driver.

  ```js theme={null}
  import { defineConfig, sessionDrivers } from 'astro/config';

  {
    session: {
      driver: sessionDrivers.redis({
        url: process.env.REDIS_URL
      })
    }
  }
  ```
</ParamField>

### session.ttl

<ParamField path="session.ttl" type="number" default="Infinity">
  An optional default time-to-live expiration period for session values, in seconds.

  ```js theme={null}
  {
    session: {
      ttl: 3600 // 1 hour
    }
  }
  ```
</ParamField>

## i18n Options

### i18n.locales

<ParamField path="i18n.locales" type="Locales" required>
  A list of all locales supported by the website. This is a required field.

  ```js theme={null}
  {
    i18n: {
      locales: ['en', 'es', 'pt-br']
    }
  }
  ```

  You can also map to shared paths:

  ```js theme={null}
  {
    i18n: {
      locales: [
        'en',
        { path: 'english', codes: ['en', 'en-US'] }
      ]
    }
  }
  ```
</ParamField>

### i18n.defaultLocale

<ParamField path="i18n.defaultLocale" type="string" required>
  The default locale of your website/application. This is a required field.

  ```js theme={null}
  {
    i18n: {
      defaultLocale: 'en'
    }
  }
  ```
</ParamField>

### i18n.fallback

<ParamField path="i18n.fallback" type="Record<string, string>">
  The fallback strategy when navigating to pages that do not exist.

  ```js theme={null}
  {
    i18n: {
      fallback: {
        'pt-br': 'es',
        'fr': 'en'
      }
    }
  }
  ```
</ParamField>

### i18n.routing

<ParamField path="i18n.routing" type="object | 'manual'" default="object">
  Controls the routing strategy to determine your site URLs.

  ```js theme={null}
  {
    i18n: {
      routing: {
        prefixDefaultLocale: false,
        redirectToDefaultLocale: true,
        fallbackType: 'redirect'
      }
    }
  }
  ```
</ParamField>

## Dev Toolbar Options

### devToolbar.enabled

<ParamField path="devToolbar.enabled" 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.
</ParamField>

### devToolbar.placement

<ParamField path="devToolbar.placement" type="'bottom-left' | 'bottom-center' | 'bottom-right'" default="'bottom-center'">
  The default placement of the Astro Dev Toolbar on the screen.
</ParamField>

## Prefetch Options

### prefetch.prefetchAll

<ParamField path="prefetch.prefetchAll" type="boolean">
  Enable prefetching for all links, including those without the `data-astro-prefetch` attribute.

  ```js theme={null}
  {
    prefetch: {
      prefetchAll: true
    }
  }
  ```
</ParamField>

### prefetch.defaultStrategy

<ParamField path="prefetch.defaultStrategy" type="'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
</ParamField>