Configuration Reference

The following reference covers all supported configuration options in Astro. To learn more about configuring Astro, read our guide on Configuring Astro.

import { defineConfig } from 'astro/config'

export default defineConfig({
  // your configuration options here...
})

Type: string
CLI: --root
Default: "." (current working directory)

You should only provide this option if you run the astro CLI commands in a directory other than the project root directory. Usually, this option is provided via the CLI instead of the Astro config file, since Astro needs to know your project root before it can locate your config file.

If you provide a relative path (ex: --root: './my-project') Astro will resolve it against your current working directory.

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

$ astro build --root ./my-project-directory

Type: string
Default: "./src"

Set the directory that Astro will read your site from.

The value can be either an absolute file system path or a path relative to the project root.

{
  srcDir: './www'
}

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. These files are always served or copied as-is, without transform or bundling.

The value can be either an absolute file system path or a path relative to the project root.

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

Type: string
Default: "./dist"

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

The value can be either an absolute file system path or a path relative to the project root.

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

Type: string

Your final, deployed URL. Astro uses this full URL to generate your sitemap and canonical URLs in your final build. It is strongly recommended that you set this configuration to get the most out of Astro.

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

Type: string

The base path you’re deploying to. Astro will match this pathname during development so that your development experience matches your build environment as closely as possible. In the example below, astro dev will start your server at /docs.

{
  base: '/docs'
}

Type: 'always' | 'never' | 'ignore'
Default: 'ignore'

Set the route matching behavior of the dev server. Choose from the following options:

• 'always' - Only match URLs that include a trailing slash (ex: “/foo/“)
• 'never' - Never match URLs that include a trailing slash (ex: “/foo”)
• 'ignore' - Match URLs regardless of whether a trailing ”/” exists

Use this configuration option if your production host has strict handling of how trailing slashes work or do not work.

You can also set this if you prefer to be more strict yourself, so that URLs with or without trailing slashes won’t work during development.

{
  // Example: Require a trailing slash during development
  trailingSlash: 'always'
}

See Also:

• buildOptions.pageUrlFormat

Type: AstroIntegration

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

See our Server-side Rendering guide for more on SSR, and our deployment guides for a complete list of hosts.

import netlify from '@astrojs/netlify/functions';
{
  // Example: Build for Netlify serverless deployment
   adapter: netlify(),
}

See Also:

• output

Type: 'static' | 'server'
Default: 'static'

Specifies the output target for builds.

• ‘static’ - Building a static site to be deploy to any static host.
• ‘server’ - Building an app to be deployed to a host supporting SSR (server-side rendering).

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static'
})

See Also:

• adapter

Type: ('file' | 'directory')
Default: 'directory'

Control the output file format of each page.

• If ‘file’, Astro will generate an HTML file (ex: “/foo.html”) for each page.
• If ‘directory’, Astro will generate a directory with a nested index.html file (ex: “/foo/index.html”) for each page.

{
  build: {
    // Example: Generate `page.html` instead of `page/index.html` during build.
    format: 'file'
  }
}

Customize the Astro dev server, used by both astro dev and astro preview.

{
  server: { port: 1234, host: true}
}

To set different configuration based on the command run (“dev”, “preview”) a function can also be passed to this configuration option.

{
  // Example: Use the function syntax to customize based on command
  server: (command) => ({ port: command === 'dev' ? 3000 : 4000 })
}

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] (ex: 192.168.0.1)

Type: number
Default: 3000

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 }
}

Type: boolean
Default: false

Control whether Markdown draft pages should be included in the build.

A Markdown page is considered a draft if it includes draft: true in its frontmatter. Draft pages are always included & visible during development (astro dev) but by default they will not be included in your final build.

{
  markdown: {
    // Example: Include all drafts in your final build
    drafts: true,
  }
}

Type: Partial<ShikiConfig>

Shiki configuration options. See the Markdown configuration docs for usage.

Type: 'shiki' | 'prism' | false
Default: shiki

Which syntax highlighter to use, if any.

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

{
  markdown: {
    // Example: Switch to use prism for syntax highlighting in Markdown
    syntaxHighlight: 'prism',
  }
}

Type: RemarkPlugins

Pass a custom Remark plugin to customize how your Markdown is built.

Note: Enabling custom remarkPlugins or rehypePlugins removes Astro’s built-in support for GitHub-flavored Markdown support and Smartypants. You must explicitly add these plugins to your astro.config.mjs file, if desired.

{
  markdown: {
    // Example: The default set of remark plugins used by Astro
    remarkPlugins: ['remark-gfm', 'remark-smartypants'],
  },
};

Type: RehypePlugins

Pass a custom Rehype plugin to customize how your Markdown is built.

Note: Enabling custom remarkPlugins or rehypePlugins removes Astro’s built-in support for GitHub-flavored Markdown support and Smartypants. You must explicitly add these plugins to your astro.config.mjs file, if desired.

{
  markdown: {
    // Example: The default set of rehype plugins used by Astro
    rehypePlugins: [],
  },
};

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 (like Partytown and Turbolinks).

Read our Integrations Guide for help getting started with Astro Integrations.

import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // Example: Add React + Tailwind support to Astro
  integrations: [react(), tailwind()]
}

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

View the full vite configuration object documentation on vitejs.dev.

{
  vite: {
    ssr: {
      // Example: Force a broken package to skip SSR processing, if needed
      external: ['broken-npm-package'],
    }
  }
}

{
  vite: {
    // Example: Add custom vite plugins directly to your Astro project
    plugins: [myPlugin()],
  }
}

To help some users migrate between versions of Astro, we occasionally introduce legacy flags. These flags allow you to opt in to some deprecated or otherwise outdated behavior of Astro in the latest version, so that you can continue to upgrade and take advantage of new Astro releases.

Type: boolean
Default: false

Enable Astro’s pre-v1.0 support for components and JSX expressions in .md Markdown files. In Astro 1.0.0-rc, this original behavior was removed as the default, in favor of our new MDX integration.

To enable this behavior, set legacy.astroFlavoredMarkdown to true in your astro.config.mjs configuration file.

{
  legacy: {
    // Example: Add support for legacy Markdown features
    astroFlavoredMarkdown: true,
  },
}