Configure Astro

Project-wide settings live in astro.config.mjs, at the root of the project. The wizard created one for you.

A typical configuration imports defineConfig and exports an object:

import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://notes.flaviocopes.com'
})

defineConfig() doesn’t do much at runtime. It gives your editor the types, so you get autocomplete and a red underline when you mistype an option. Always use it.

The site option

site is the address where the site will be deployed. Astro needs it whenever it has to generate an absolute URL. Sitemap entries, canonical tags, RSS feed links, Open Graph images.

Without it, those features either fail or fall back to relative URLs. Set it early, even before you have a domain, and update it later.

What else goes here

Everything that affects the whole project. Integrations like React or Tailwind. Redirects. The output mode, static or server. The adapter for your host. Build options like the output directory.

One thing to remember: this file runs in the Astro toolchain, on your machine or on the build server. It never runs in the visitor’s browser.

Keep it small

A change in this file can affect every route. So add one setting at a time, and check the result before adding the next.

I also like to leave a short comment next to any option that isn’t obvious. Six months later, you won’t remember why trailingSlash is set to 'never'.

Prefer the defaults. Astro’s defaults are good, and a config file full of settings copied from a tutorial is harder to maintain than one that only says what your project needs.

A word on secrets

Configuration is server-side, but that doesn’t make every value private. If you read an environment variable here and pass it into something that ends up in the HTML or in a client bundle, it’s public.

Keep secrets out of any value that gets serialized into the output. We’ll come back to this in the data module.

Try this on your project: set site to a made-up domain, add a page with a canonical link that uses Astro.site, run npm run build, and open the generated HTML in dist/. The absolute URL in the output should start with the domain you configured.