Configuration Reference
The following reference covers all supported configuration options in Astro. To learn more about configuring Astro, read our guide on Configuring Astro.
Top-Level Options
Section titled Top-Level OptionsType: 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.
Examples
Section titled ExamplessrcDir
Section titled srcDirType: 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.
publicDir
Section titled publicDirType: 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.
outDir
Section titled outDirType: 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.
See Also:
- build.server
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.
Type: string
The base path to deploy to. Astro will build your pages and assets using this path as the root. Currently, this has no effect during development.
trailingSlash
Section titled trailingSlashType: '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.
See Also:
- build.format
adapter
Section titled adapterType: 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.
See Also:
- output
output
Section titled outputType: '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).
See Also:
- adapter
Build Options
Section titled Build Optionsbuild.format
Section titled build.formatType: ('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.
Effect on Astro.url
Section titled Effect on Astro.urlSetting build.format
controls what Astro.url
is set to during the build. When it is:
directory
- TheAstro.url.pathname
will include a trailing slash to mimic folder behavior; ie/foo/
.file
- TheAstro.url.pathname
will include.html
; ie/foo.html
.
This means that when you create relative URLs using new URL('./relative', Astro.url)
, you will get consistent behavior between dev and build.
build.client
Section titled build.clientType: string
Default: './dist/client'
Controls the output directory of your client-side CSS and JavaScript when output: 'server'
only.
outDir
controls where the code is built to.
This value is relative to the outDir
.
build.server
Section titled build.serverType: string
Default: './dist/server'
Controls the output directory of server JavaScript when building to SSR.
This value is relative to the outDir
.
build.serverEntry
Section titled build.serverEntryType: 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 and will be set by your adapter for you.
Note that it is recommended that this file ends with .mjs
so that the runtime
detects that the file is a JavaScript module.
Server Options
Section titled Server OptionsCustomize the Astro dev server, used by both astro dev
and astro preview
.
To set different configuration based on the command run (“dev”, “preview”) a function can also be passed to this configuration option.
server.host
Section titled server.hostType: 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 addresstrue
- 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
)
server.port
Section titled server.portType: 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.
Markdown Options
Section titled Markdown Optionsmarkdown.drafts
Section titled markdown.draftsType: 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.shikiConfig
Section titled markdown.shikiConfigType: Partial<ShikiConfig>
Shiki configuration options. See the Markdown configuration docs for usage.
markdown.syntaxHighlight
Section titled markdown.syntaxHighlightType: 'shiki' | 'prism' | false
Default: shiki
Which syntax highlighter to use, if any.
shiki
- use the Shiki highlighterprism
- use the Prism highlighterfalse
- do not apply syntax highlighting.
markdown.remarkPlugins
Section titled markdown.remarkPluginsType: RemarkPlugins
Pass remark plugins to customize how your Markdown is built. You can import and apply the plugin function (recommended), or pass the plugin name as a string.
markdown.rehypePlugins
Section titled markdown.rehypePluginsType: RehypePlugins
Pass rehype plugins to customize how your Markdown’s output HTML is processed. You can import and apply the plugin function (recommended), or pass the plugin name as a string.
markdown.extendDefaultPlugins
Section titled markdown.extendDefaultPluginsType: boolean
Default: false
Astro applies the GitHub-flavored Markdown and Smartypants plugins by default. When adding your own remark or rehype plugins, you can preserve these defaults by setting the extendDefaultPlugins
flag to true
:
markdown.remarkRehype
Section titled markdown.remarkRehypeType: RemarkRehype
Pass options to remark-rehype.
Integrations
Section titled IntegrationsExtend 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.
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.
Examples
Section titled ExamplesLegacy Flags
Section titled Legacy FlagsTo 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.
legacy.astroFlavoredMarkdown
Section titled legacy.astroFlavoredMarkdownType: boolean
Default: false
Enable Astro’s pre-v1.0 support for components and JSX expressions in .md
(and alternative extensions for markdown files like “.markdown”) 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.