Configuration and Type System

Relevant source files

• packages/astro/src/container/index.ts
• packages/astro/src/container/pipeline.ts
• packages/astro/src/core/app/pipeline.ts
• packages/astro/src/core/app/types.ts
• packages/astro/src/core/base-pipeline.ts
• packages/astro/src/core/build/generate.ts
• packages/astro/src/core/build/pipeline.ts
• packages/astro/src/core/build/plugins/plugin-manifest.ts
• packages/astro/src/core/build/plugins/plugin-ssr.ts
• packages/astro/src/core/config/schemas/README.md
• packages/astro/src/core/config/schemas/base.ts
• packages/astro/src/core/config/schemas/index.ts
• packages/astro/src/core/config/validate.ts
• packages/astro/src/core/csp/config.ts
• packages/astro/src/core/errors/errors-data.ts
• packages/astro/src/core/errors/zod-error-map.ts
• packages/astro/src/core/routing/rewrite.ts
• packages/astro/src/env/env-loader.ts
• packages/astro/src/env/runtime.ts
• packages/astro/src/env/vite-plugin-env.ts
• packages/astro/src/manifest/serialized.ts
• packages/astro/src/types/public/config.ts
• packages/astro/src/vite-plugin-astro-server/plugin.ts
• packages/astro/src/vite-plugin-config-alias/index.ts
• packages/astro/templates/env.mjs
• packages/astro/test/fixtures/alias-tsconfig/deps/namespace-package/index.js
• packages/astro/test/fixtures/alias-tsconfig/deps/namespace-package/package.json
• packages/astro/test/fixtures/alias-tsconfig/src/components/Foo.astro
• packages/astro/test/fixtures/alias-tsconfig/src/components/Style.astro
• packages/astro/test/fixtures/alias-tsconfig/src/pages.ts
• packages/astro/test/fixtures/alias-tsconfig/src/pages/index.astro
• packages/astro/test/fixtures/alias-tsconfig/src/styles/main.css
• packages/astro/test/fixtures/alias-tsconfig/src/utils/constants.js
• packages/astro/test/fixtures/alias-tsconfig/src/utils/index.js
• packages/astro/test/fixtures/alias-tsconfig/tsconfig.json
• packages/astro/test/fixtures/astro-envs/.env
• packages/astro/test/fixtures/astro-envs/astro.config.mjs
• packages/astro/test/fixtures/astro-envs/src/components/Client.vue
• packages/astro/test/fixtures/astro-envs/src/data/cats.json
• packages/astro/test/fixtures/astro-envs/src/data/hello.css
• packages/astro/test/fixtures/astro-envs/src/data/hi.md
• packages/astro/test/fixtures/astro-envs/src/pages/destructured.astro
• packages/astro/test/fixtures/astro-envs/src/pages/index.astro
• packages/astro/test/fixtures/astro-envs/src/pages/info.html
• packages/astro/test/units/config/config-validate.test.ts
• packages/astro/test/units/errors/zod-error-map.test.ts

The Astro Configuration and Type System manages project settings through astro.config.* files, providing type-safe validation with Zod schemas, default value injection, and runtime configuration resolution. The system coordinates configuration loading, validation, and transformation into AstroSettings objects that drive build and development workflows.

This page documents the configuration schema definition, the resolution process, and how configuration flows through CLI commands, build processes, and development servers.

---

Configuration Architecture

The configuration system implements a multi-stage pipeline from user configuration files to validated AstroConfig objects and runtime AstroSettings.

Configuration Resolution Flow

• AstroConfigSchema: The central Zod schema that defines the structure and validation rules for the entire configuration packages/astro/src/core/config/schemas/base.ts93-220
• ASTRO_CONFIG_DEFAULTS: A constant object providing the baseline values for all configuration properties packages/astro/src/core/config/schemas/defaults.ts10-112
• AstroSettings: The final runtime object used by the core engine. It wraps the resolved AstroConfig and adds runtime state like renderers and clientDirectives packages/astro/src/types/astro.ts50-70

Sources: packages/astro/src/core/config/schemas/base.ts93-220 packages/astro/src/core/config/schemas/defaults.ts10-112 packages/astro/src/types/public/config.ts171-220

---

Configuration Type System

Astro maintains distinct TypeScript interfaces for configuration at different stages of the lifecycle.

Core Configuration Interfaces

Type	Purpose	Source
AstroUserConfig	The raw input from astro.config.mjs. Supports partial values and relative paths.	packages/astro/src/types/public/config.ts171-220
AstroConfig	The fully resolved configuration. All paths are converted to URL objects.	packages/astro/src/types/public/config.ts157-163
AstroSettings	The internal object used by the build/dev server. Includes the config plus runtime state.	packages/astro/src/types/astro.ts50-70

Key Configuration Areas

• Project Structure: Managed via root, srcDir, publicDir, and outDir. These are transformed from strings to URL objects during validation packages/astro/src/core/config/schemas/base.ts94-118
• Build Options: Includes format (file/directory), concurrency, and assetsPrefix for CDN deployments packages/astro/src/core/config/schemas/base.ts151-181
• Server Options: Controls the dev server via host, port, and custom headers packages/astro/src/types/public/config.ts79-151
• I18n: Configures localization strategies, including locales, defaultLocale, and routing strategies packages/astro/src/core/app/types.ts154-162

Sources: packages/astro/src/core/config/schemas/base.ts94-118 packages/astro/src/types/public/config.ts79-151 packages/astro/src/core/app/types.ts154-162

---

Environment Variable System (astro:env)

Astro provides a type-safe environment variable system via the astro:env module, supporting both public and secret variables.

Env Resolution and Validation

The astro:env system uses an EnvSchema to define expected variables and their access levels (public vs secret).

• createEnvLoader: Aggregates variables from .env files and process.env, filtering them based on the provided schema packages/astro/src/env/env-loader.ts31-98
• Virtual Modules: The system generates virtual modules for client and server access. Secret variables are strictly excluded from the client module to prevent leakage packages/astro/src/env/vite-plugin-env.ts171-213
• Runtime Resolution: At runtime, getEnv() provides access to variables, allowing adapters to override resolution (e.g., using Cloudflare Bindings) packages/astro/src/env/runtime.ts12-16

Sources: packages/astro/src/env/env-loader.ts31-98 packages/astro/src/env/vite-plugin-env.ts171-213 packages/astro/src/env/runtime.ts12-16

---

Schema Validation and Error Mapping

Astro uses zod for validation but implements a custom error mapping system to provide user-friendly diagnostics.

Zod Error Mapping

The zodErrorMap function intercepts Zod validation errors and transforms them into AstroError objects with helpful hints.

• Type Mismatches: Converts invalid_type errors into clear "Expected X, received Y" messages packages/astro/src/core/errors/zod-error-map.ts10-45
• Path Resolution: Errors in path resolution (e.g., an invalid site URL) are caught during the transform phase of the schema packages/astro/src/core/config/schemas/base.ts119
• Integration Validation: Preprocesses the integrations array to flatten nested arrays and filter out falsy values before validation packages/astro/src/core/config/schemas/base.ts143-150

Sources: packages/astro/src/core/errors/zod-error-map.ts10-45 packages/astro/src/core/config/schemas/base.ts143-150

---

Configuration Resolution in Build and Dev

Path Aliasing

Astro supports tsconfig.json path aliases. The configAliasVitePlugin ensures these aliases work across CSS imports and module resolutions.

• CSS Aliases: Handles @import and url() references in CSS files using a regex-based replacement fallback for Vite packages/astro/src/vite-plugin-config-alias/index.ts131-169
• Module Aliases: Resolves JS/TS/Astro imports by matching against compilerOptions.paths in tsconfig.json packages/astro/src/vite-plugin-config-alias/index.ts172-206

Manifest Generation

During the build, the configuration is serialized into an SSRManifest. This manifest is the "single source of truth" for the production runtime.

• Serialized Manifest: Contains the resolved base, trailingSlash, renderers, and routes packages/astro/src/core/app/types.ts63-148
• Token Injection: The build uses a MANIFEST_REPLACE token (@@ASTRO_MANIFEST_REPLACE@@) which is replaced with the actual JSON-serialized manifest data at the end of the bundling process packages/astro/src/core/build/plugins/plugin-manifest.ts63-117

Sources: packages/astro/src/vite-plugin-config-alias/index.ts131-206 packages/astro/src/core/app/types.ts63-148 packages/astro/src/core/build/plugins/plugin-manifest.ts63-117

---

Summary of Code Entities

Sources: packages/astro/src/types/public/config.ts171-220 packages/astro/src/types/astro.ts50-70 packages/astro/src/core/app/types.ts63-148 packages/astro/src/core/base-pipeline.ts64-114