Configuration

astro.config.mjs (or .ts/.cjs/.mts) is the user-facing entry point for configuration. The shape is defined by Zod schemas under packages/astro/src/core/config/schemas/ and surfaced as TypeScript types in packages/astro/src/types/public/config.ts (3,134 lines — the largest file in the repo).

Resolution

packages/astro/src/core/config/ resolves the user's config via:

1. Locate astro.config.{mjs,ts,js,cjs,mts} starting at the project root.
2. Load it with Vite's config loader (so TypeScript and ESM both work).
3. Merge with defaults from schemas/base.ts.
4. Validate with Zod (createMarkdownProcessor-style schemas live in packages/markdown/remark/).
5. Run through every integration's astro:config:setup hook (which can mutate config).
6. Run astro:config:done for hooks that need the final config.

Top-level options

(See packages/astro/src/types/public/config.ts for the complete typed surface.)

Key	Purpose
site	Public URL of the deployed site. Used by Astro.site, @astrojs/sitemap, RSS.
base	URL prefix for the deployed app.
output	'static' | 'server'. Per-route override via export const prerender.
adapter	An AstroAdapter (set via setAdapter() in an integration).
integrations	Array of AstroIntegrations.
redirects	Map of from → to.
i18n	Locale routing config (see features / i18n).
markdown	Remark/rehype plugins, Shiki theme, Smartypants.
image	Image service, remote patterns, Sharp encoder config.
prefetch	Built-in prefetch strategy and toggle.
session	Session driver and cookie config.
env.schema	Typed environment variable declarations.
experimental.*	Unstable feature flags (fonts, csp, clientPrerender, serializeConfig, …).
vite	Pass-through Vite config. Last resort — most things should be configured via Astro's options.
server	Dev server host/port/headers.
outDir, publicDir, srcDir, cacheDir, build.client, build.server	Build paths.
compressHTML	Whitespace minification on the rendered HTML.
scopedStyleStrategy	'where' | 'class' | 'attribute'.
security.checkOrigin	CSRF-style origin checking.
legacy.*	Opt-in compatibility flags.

Notable schemas

File	What it covers
packages/astro/src/core/config/schemas/base.ts	The main AstroConfigSchema.
packages/astro/src/assets/fonts/config.ts	Fonts.
packages/astro/src/assets/svg/config.ts	SVG optimizer.
packages/astro/src/env/schema.ts	env.schema.
packages/astro/src/core/cache/config.ts	cache and route rules.
packages/astro/src/core/csp/config.ts	CSP.
packages/astro/src/core/session/config.ts	Sessions.

defineConfig

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  output: 'static',
  integrations: [
    /* … */
  ],
});

defineConfig is just a typed identity helper. The runtime parses whatever the file exports.

TypeScript

Astro ships several tsconfig.*.json presets at packages/astro/tsconfigs/:

• base.json
• strict.json
• strictest.json

create-astro selects one during scaffolding. Recent commits (feat: tsconfig types like TS 5, feat: update tsconfig template to prepare for TS 6) keep these in lockstep with TypeScript releases.

Related pages

• features / env
• features / csp
• features / sessions
• features / image optimization
• features / fonts
• features / i18n
• reference / Vite dep optimizer