Configuring Astro
Customize how Astro works by adding an astro.config.mjs
file in your project. This is a common file in Astro projects, and all official example templates and themes ship with one by default.
📚 Read Astro’s API configuration reference for a full overview of all supported configuration options.
The Astro Config File
Section titled The Astro Config FileA valid Astro config file exports its configuration using the default
export, using the recommended defineConfig
helper:
import { defineConfig } from 'astro/config'
export default defineConfig({
// your configuration options here...
// https://docs.astro.build/en/reference/configuration-reference/
})
Using defineConfig()
is recommended for automatic type hints in your IDE, but it is also optional. An absolutely bare-minimum, valid configuration file would look like this:
// Example: Bare minimum, empty configuration file
export default {}
Supported Config File Types
Section titled Supported Config File TypesAstro supports several file formats for its JavaScript configuration file: astro.config.js
, astro.config.mjs
, astro.config.cjs
and astro.config.ts
. We recommend using .mjs
in most cases or .ts
if you want to write TypeScript in your config file.
TypeScript config file loading is handled using tsm
and will respect your project tsconfig options.
Config File Resolving
Section titled Config File ResolvingAstro will automatically try to resolve a config file named astro.config.mjs
inside project root. If no config file is found in your project root, Astro’s default options will be used.
# Example: Reads your configuration from ./astro.config.mjs
astro build
You can explicitly set a config file to use with the --config
CLI flag. This CLI flag always resolves relative to the current working directory where you ran the astro
CLI command.
# Example: Reads your configuration from this file
astro build --config my-config-file.js
Config IntelliSense
Section titled Config IntelliSenseAstro recommends using the defineConfig()
helper in your configuration file. defineConfig()
provides automatic IntelliSense in your IDE. Editors like VSCode are able to read Astro’s TypeScript type definitions and provide automatic jsdoc type hints, even if your configuration file isn’t written in TypeScript.
import { defineConfig } from 'astro/config'
export default defineConfig({
// your configuration options here...
// https://docs.astro.build/en/reference/configuration-reference/
})
You can also provide type definitions manually to VSCode, using this JSDoc notation:
export default /** @type {import('astro').AstroUserConfig} */ {
// your configuration options here...
// https://docs.astro.build/en/reference/configuration-reference/
}
Referencing Relative Files
Section titled Referencing Relative FilesIf you provide a relative path to root
or the --root
CLI flag, Astro will resolve it against the current working directory where you ran the astro
CLI command.
import { defineConfig } from 'astro/config'
export default defineConfig({
// Resolves to the "./foo" directory in your current working directory
root: 'foo'
})
Astro will resolve all other relative file and directory strings as relative to the project root:
import { defineConfig } from 'astro/config'
export default defineConfig({
// Resolves to the "./foo" directory in your current working directory
root: 'foo',
// Resolves to the "./foo/public" directory in your current working directory
publicDir: 'public',
})
To reference a file or directory relative to the configuration file, use import.meta.url
(unless you are writing a common.js astro.config.cjs
file).
import { defineConfig } from 'astro/config'
export default defineConfig({
// Resolves to the "./foo" directory, relative to this config file
root: new URL("./foo", import.meta.url),
// Resolves to the "./public" directory, relative to this config file
publicDir: new URL("./public", import.meta.url),
})
Customising Output Filenames
Section titled Customising Output FilenamesFor code that Astro processes, like imported JavaScript or CSS files, you can customise output filenames using entryFileNames
, chunkFileNames
, and assetFileNames
in a vite.build.rollupOptions
entry in your astro.config.*
file.
import { defineConfig } from 'astro/config'
export default defineConfig({
vite: {
build: {
rollupOptions: {
output: {
entryFileNames: 'entry.[hash].js',
chunkFileNames: 'chunks/chunk.[hash].js',
assetFileNames: 'assets/asset.[hash][extname]',
},
},
},
},
})
This can be helpful if you have scripts with names that might be impacted by ad blockers (e.g. ads.js
or google-tag-manager.js
).
Environment Variables
Section titled Environment VariablesAstro evaluates configuration files before it loads your other files. As such, you can’t use import.meta.env
or access environment variables that were set in .env
files.
You can use process.env
in a configuration file to access other environment variables, like those set by the CLI.
Configuration Reference
Section titled Configuration Reference📚 Read Astro’s API configuration reference for a full overview of all supported configuration options.