Configuration Reference

Purpose and Scope

Astro configuration starts with a project-level config file, usually astro.config.mjs, where users import defineConfig from astro/config and export a single configuration object. The official documentation frames this file as optional until a project has something to configure, but in practice most projects use it to coordinate routing, build output, integrations, image behavior, content, server rendering, and development ergonomics. This reference explains configuration as a set of connected contracts: user-facing options are collected in the config file, public helper modules expose safe subsets of those options at runtime, and internal schemas validate specialized feature areas before they are used by the renderer or build pipeline.

The source paths for this page show how Astro keeps configuration modular. Instead of one monolithic file owning every option, individual subsystems define the shapes they need: image endpoint routing lives with asset endpoint injection, font family configuration lives with the font asset pipeline, SVG optimization validates optimizer plugins, content collections define their loader and schema contracts, and route caching declares provider and route-rule schemas. This organization matters for users because an option in astro.config.mjs is not just a static setting. It often becomes runtime behavior, generated routes, validation errors, editor affordances, or type-safe imports.

Sources: packages/astro/src/assets/endpoint/config.ts, packages/astro/src/assets/fonts/config.ts, packages/astro/src/assets/svg/config.ts, packages/astro/src/content/config.ts, packages/astro/src/core/cache/config.ts, packages/language-tools/vscode/languages/astro-language-configuration.json

Relevant Source Files

• packages/language-tools/vscode/languages/astro-language-configuration.json defines editor-facing language configuration for Astro files, including comments, brackets, auto-closing pairs, indentation rules, folding markers, word patterns, and enter-key behavior.
• packages/astro/src/assets/endpoint/config.ts turns image endpoint configuration into an injected internal endpoint route, choosing development or build entrypoints when the user has not supplied one.
• packages/astro/src/assets/fonts/config.ts defines Zod schemas for font providers and font families, including weights, styles, display behavior, fallbacks, formats, CSS variables, provider hooks, and provider-specific options.
• packages/astro/src/assets/svg/config.ts defines the minimal optimizer contract for SVG handling: an optimizer has a name and an optimize function.
• packages/astro/src/content/config.ts defines content, data, content-layer, and live collection configuration types, plus data-store and metadata-store interfaces used by loaders and content APIs.
• packages/astro/src/core/cache/config.ts defines cache provider configuration, route-level cache options, and the routeRules mapping syntax used to associate cache behavior with route patterns.

Astro Config Entrypoints

The first entrypoint most users see is astro.config.mjs. A typical file imports defineConfig from astro/config and exports options such as site, base, trailingSlash, integrations, adapter settings, image settings, and other feature-specific blocks. The official configuration reference describes site as the final deployed URL used for generated URLs, base as the deployment base path used for pages and assets, and trailingSlash as the policy that influences generated URLs and the value of import.meta.env.BASE_URL. Those top-level options are part of the public authoring experience, while the files cited here show how deeper feature-specific options are validated and consumed once configuration has been loaded.

Astro also exposes configuration values through the virtual module family astro:config. The official modules reference separates astro:config/client from astro:config/server: client imports only expose serializable values safe for browser code, while server imports can include filesystem-oriented values such as directories. That distinction is important when writing utilities or integrations that need configuration at runtime. Treat the config file as the authoring source of truth, and treat config imports as a read-only, already-processed view designed for the environment where the code executes.

Configuration is therefore not limited to one place in the repository. Some configuration shapes are user-authored in astro.config.mjs; some are content-specific and live in files such as src/content.config.ts or src/live.config.ts; some are editor configuration files consumed by language tooling rather than by the Astro runtime. The language configuration JSON is a good example of a non-runtime configuration surface: it controls how Astro files behave in VS Code-compatible tooling, including HTML-style comments, bracket pairing, auto-closing behavior, region folding markers, and indentation heuristics for tags and braces. Sources: packages/language-tools/vscode/languages/astro-language-configuration.json

import { defineConfig } from 'astro/config';
 
export default defineConfig({
  site: 'https://www.example.com',
  base: '/docs',
  trailingSlash: 'always',
});

System-to-Code Mapping

The image endpoint configuration path demonstrates how a user-facing option becomes a route in Astro’s manifest. injectImageEndpoint() receives AstroSettings, the manifest route list, the current mode, and an optional working directory. It unshifts a generated route into the manifest, meaning the image endpoint is registered as an internal endpoint before normal routing continues. When settings.config.image.endpoint.entrypoint is not set, Astro selects astro/assets/endpoint/dev in development and astro/assets/endpoint/generic during build. If a custom entrypoint is configured, that entrypoint is resolved against the project root before parseRoute() creates endpoint route data for settings.config.image.endpoint.route. Sources: packages/astro/src/assets/endpoint/config.ts

Font configuration shows a different pattern: it is schema-first. The font asset subsystem defines a FontProviderSchema whose required shape includes a provider name, a required resolveFont function, and optional config, init, and listFonts members. The code deliberately validates the provider shape with z.custom() rather than remapping with a plain Zod object, preserving class instances and other provider objects that satisfy the contract. A FontFamilySchema then describes the public family-level fields Astro can accept: name, cssVariable, provider, optional weights, styles, subsets, formats, fallback behavior, font-display behavior, stretch and variation settings, Unicode range, and arbitrary provider-specific options. Sources: packages/astro/src/assets/fonts/config.ts

SVG optimization is intentionally narrower. The SVG config schema requires a name and an optimize function for each optimizer object. That compact contract allows the asset pipeline to depend on a stable optimizer interface without prescribing the optimizer’s internal configuration format. For readers comparing fonts and SVGs, the difference is useful: font configuration models a full asset family and provider ecosystem, while SVG configuration models a single optimization hook. Both are validated with Zod, but the depth of the schema mirrors the complexity of the feature being configured. Sources: packages/astro/src/assets/svg/config.ts

Feature Configuration Contracts

Content configuration is one of Astro’s richest configuration surfaces because it connects authoring files, loaders, schemas, and runtime stores. The source defines DataEntry records with an id, arbitrary data, and optional filePath and body. DataStore and MetaStore describe storage-like interfaces with familiar methods such as get, set, entries, values, keys, delete, clear, and has. These interfaces let loaders and the content layer reason about entries consistently, regardless of whether the data came from local files, generated objects, or another loader mechanism. Sources: packages/astro/src/content/config.ts

Collection configuration is modeled as a discriminated family rather than one generic bag of options. A content collection can default to the content type and may include a schema, but it cannot include a loader. A data collection uses type: 'data' and can include a schema. A content-layer collection can use type: 'content_layer', must provide a loader, and may include a schema function that receives a context containing an image helper. Live collections have their own LiveCollectionConfig, require a live loader, and are defined through defineLiveCollection(), which defaults the type to the live content type and validates that live collections are defined from src/live.config.ts. Sources: packages/astro/src/content/config.ts

Caching configuration uses route rules to bind cache behavior to route patterns. The cache provider schema accepts an optional provider with entrypoint, optional config, and optional name. Route-level cache options include integer maxAge, integer swr, and string tags. The RouteRulesSchema is a record keyed by route patterns, and the source comments state that patterns use Astro’s file-based routing style such as [param] and [...rest]; glob wildcards are not supported. This makes route rules feel familiar to Astro users while keeping cache behavior declarative and independent from page code. Sources: packages/astro/src/core/cache/config.ts

export default defineConfig({
  routeRules: {
    '/api/[...path]': { swr: 600 },
    '/products/[...slug]': { maxAge: 3600, tags: ['products'] },
  },
});

Compact Reference

Implementation Details and Constraints

A recurring implementation choice is to keep validation close to the subsystem that consumes the option. The font and SVG modules import Zod directly and export schemas that describe their own contracts. The cache module does the same for provider configuration and route rule values. This design makes it easier for subsystem maintainers to evolve a feature without forcing every option into a central config file, and it gives users more precise validation behavior. When a feature has callbacks, such as font providers or SVG optimizers, the schema checks for function members instead of assuming the object can be serialized into plain JSON.

Another important constraint is environment safety. The official astro:config module documentation distinguishes client-safe configuration values from server-only values. That mirrors the implementation pattern visible in these subsystem files: configuration may contain functions, URLs, provider entrypoints, filesystem-sensitive values, or loader behavior, so not every value should be exposed everywhere. When authoring utilities, prefer astro:config/client only for browser-safe values such as base URL behavior, site information, build format, internationalization metadata, and HTML compression state. Use the server submodule or integration hooks for values that describe project directories, generated files, or deployment internals.

For maintainers, the content configuration file is also a reminder that configuration can be validated by location as well as by shape. defineLiveCollection() inspects the importer filename from the stack trace and throws an Astro error when live collections are defined outside a src/live.config.ts file. That is different from merely checking whether an object has loader and schema properties. It protects a file convention that affects how live content is discovered and loaded, and it gives the user an error tied to the configuration file they need to move or rename. Sources: packages/astro/src/content/config.ts

Practical Next Steps

When adding or debugging an Astro option, first identify the configuration surface involved. Top-level site behavior belongs in astro.config.mjs; content model behavior belongs in the content configuration APIs; cache behavior belongs in routeRules; asset pipelines usually have feature-specific schemas. Then follow the option into the subsystem that consumes it. For example, image endpoint problems should be traced through endpoint route injection, font provider issues through FontProviderSchema and FontFamilySchema, and caching problems through the provider and route-rule schemas. This approach keeps troubleshooting concrete and avoids treating every configuration issue as a generic Astro config problem.

If you are writing project code, use defineConfig() for the main config file and import processed values from the appropriate astro:config submodule when you need read-only access at runtime. If you are writing an integration or contributing to Astro, look for the subsystem-level schema near the feature implementation and preserve the same pattern: validate the smallest useful contract, keep client exposure safe, and document any file placement conventions that affect discovery. For adjacent details, continue to the API reference for public module exports, the image service reference for image-specific behavior, or the content collections page for collection authoring patterns.