The following reference covers all supported configuration options in Astro. To learn more about configuring Astro, read our guide on Configuring Astro.
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.
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.
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.
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.
See Also:
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.
The value can be either an absolute file system path or a path relative to the project root.
Type: Record.<string, RedirectConfig>
Default: {}
[email protected] New Specify a mapping of redirects where the key is the route to match and the value is the path to redirect to.
You can redirect both static and dynamic routes, but only to the same kind of route. For example you cannot have a '/article': '/blog/[...slug]' redirect.
For statically-generated sites with no adapter installed, this will produce a client redirect using a <meta http-equiv="refresh"> tag and does not support status codes.
When using SSR or with a static adapter in output: static mode, status codes are supported. Astro will serve redirected GET requests with a status of 301 and use a status of 308 for any other request method.
You can customize the redirection status code using an object in the redirect config:
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: boolean
Default: false
This is an option to minify your HTML output and reduce the size of your HTML files. When enabled, Astro removes all whitespace from your HTML, including line breaks, from .astro components. This occurs both in development mode and in the final build. To enable this, set the compressHTML flag to true.
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.
In the example below, astro dev will start your server at /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.
By default, the value of import.meta.env.BASE_URL includes a trailing slash. If you have the trailingSlash option set to 'never', you will need to add it manually in your static asset imports and URLs.
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 ”/” existsUse 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:
Type: 'where' | 'class'
Default: 'where'
[email protected] Specify the strategy used for scoping styles within Astro components. Choose from:
'where' - Use :where selectors, causing no specifity increase.'class' - Use class-based selectors, causing a +1 specifity increase.Using 'class' is helpful when you want to ensure that element selectors within an Astro component override global style defaults (e.g. from a global stylesheet). Using 'where' gives you more control over specifity, but requires that you use higher-specifity selectors, layers, and other tools to control which selectors are applied.
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.
See Also:
Type: 'static' | 'server' | 'hybrid'
Default: 'static'
Specifies the output target for builds.
See Also:
Type: ('file' | 'directory')
Default: 'directory'
Control the output file format of each page.
index.html file (ex: “/foo/index.html”) for each page.Setting build.format controls what Astro.url is set to during the build. When it is:
directory - The Astro.url.pathname will include a trailing slash to mimic folder behavior; ie /foo/.file - The Astro.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.
Type: string
Default: './dist/client'
Controls the output directory of your client-side CSS and JavaScript when output: 'server' or output: 'hybrid' only. outDir controls where the code is built to.
This value is relative to the outDir.
Type: string
Default: './dist/server'
Controls the output directory of server JavaScript when building to SSR.
This value is relative to the outDir.
Type: string
Default: '_astro'
[email protected] Specifies the directory in the build output where Astro-generated assets (bundled JS and CSS for example) should live.
See Also:
Type: string
Default: undefined
[email protected] Specifies the prefix for Astro-generated asset links. This can be used if assets are served from a different domain than the current site.
For example, if this is set to https://cdn.example.com, assets will be fetched from https://cdn.example.com/_astro/... (regardless of the base option). You would need to upload the files in ./dist/_astro/ to https://cdn.example.com/_astro/ to serve the assets. The process varies depending on how the third-party domain is hosted. To rename the _astro path, specify a new directory in build.assets.
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 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.
Type: boolean
Default: true
[email protected] Specifies whether redirects will be output to HTML during the build. This option only applies to output: 'static' mode; in SSR redirects are treated the same as all responses.
This option is mostly meant to be used by adapters that have special configuration files for redirects and do not need/want HTML based redirects.
Type: 'always' | 'auto' | 'never'
Default: never
[email protected] Control whether styles are sent to the browser in a separate css file or inlined into <style> tags. Choose from the following options:
'always' - all styles are inlined into <style> tags'auto' - only stylesheets smaller than ViteConfig.build.assetsInlineLimit (default: 4kb) are inlined. Otherwise, styles are sent in external stylesheets.'never' - all styles are sent in external stylesheetsType: boolean
Default: false
[email protected] Defines how the SSR code should be bundled when built.
When split is true, Astro will emit a file for each page. Each file emitted will render only one page. The pages will be emitted inside a dist/pages/ directory, and the emitted files will keep the same file paths of the src/pages directory.
Type: boolean
Default: false
[email protected] Defines whether or not any SSR middleware code will be bundled when built.
When enabled, middleware code is not bundled and imported by all pages during the build. To instead execute and import middleware code manually, set build.excludeMiddleware: true:
Customize 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.
Type: string | boolean
Default: false
[email protected] 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)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.
Type: OutgoingHttpHeaders
Default: {}
[email protected] Set custom HTTP response headers to be sent in astro dev and astro preview.
Type: Object
Default: {entrypoint: 'astro/assets/services/squoosh', config?: {}}
[email protected] Set which image service is used for Astro’s experimental assets support.
The value should be an object with an entrypoint for the image service to use and optionally, a config object to pass to the service.
The service entrypoint can be either one of the included services, or a third-party package.
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.
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 highlighterprism - use the Prism highlighterfalse - do not apply syntax highlighting.Type: 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.
Type: 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.
Type: boolean
Default: true
[email protected] Astro uses GitHub-flavored Markdown by default. To disable this, set the gfm flag to false:
Type: boolean
Default: true
[email protected] Astro uses the SmartyPants formatter by default. To disable this, set the smartypants flag to false:
Type: RemarkRehype
Pass options to remark-rehype.
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.
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.
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.
Astro offers experimental flags to give users early access to new features. These flags are not guaranteed to be stable.
Type: boolean
Default: false
[email protected] Enable experimental support for optimizing and resizing images. With this enabled, a new astro:assets module will be exposed.
To enable this feature, set experimental.assets to true in your Astro config:
Type: boolean
Default: false
[email protected] New Enable experimental support for the <ViewTransitions / > component. With this enabled you can opt-in to view transitions on a per-page basis using this component and enable animations with the transition:animate directive.
© 2021 Fred K. Schott
Licensed under the MIT License.
https://docs.astro.build/en/reference/configuration-reference/