Nuxt Schema & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Nuxt Schema & Configuration provides a type-safe, extensible foundation for managing application settings across different versions and layers of a Nuxt project. The system is built around @nuxt/schema, which defines cross-version typedefs and default configurations, ensuring that developers can build production-grade full-stack applications with zero-configuration TypeScript support.
The core responsibility of this module is to resolve, merge, and generate types for the project's configuration. It utilizes untyped to extract JSDoc annotations and schema definitions from layers, creating a unified NuxtConfig and NuxtOptions interface. This allows for dynamic runtime configuration overrides via environment variables while maintaining strict build-time type checking.
Sources: README.md:20-30, packages/schema/package.json:9-11, packages/nuxt/src/core/schema.ts:18-20
Schema Resolution Architecture
The schema resolution process involves loading schema definitions (nuxt.schema.*) from multiple project layers, merging them with defu, and generating TypeScript declaration files. This process is orchestrated during the Nuxt module initialization phase.
Schema Loading Flow
The following diagram illustrates how Nuxt loads and merges schemas from different project layers and modules.
The system uses jiti to import schema files and untyped/babel-plugin to extract JSDoc annotations, which are critical for providing developer hints and documentation links in the generated types.
Sources: packages/nuxt/src/core/schema.ts:24-55, packages/nuxt/src/core/schema.ts:133-176
Core Schema Hooks
Nuxt provides lifecycle hooks to intercept and modify the schema during the build and resolution process.
| Hook Name | Description |
|---|---|
schema:extend | Allows modules to add custom schema definitions before merging. |
schema:resolved | Called after schemas are merged and normalized. |
schema:beforeWrite | Final chance to modify the merged schema before it is written to disk. |
schema:written | Triggered after the .json and .d.ts files are successfully written. |
Sources: packages/nuxt/src/core/schema.ts:167-185
Type Generation & Augmentation
Once the schema is resolved, Nuxt generates a comprehensive TypeScript declaration file (nuxt.schema.d.ts) in the build directory. This file augments existing Nuxt modules to include custom configuration keys.
Module Augmentation Logic
The generated types wrap the project's specific schema and inject it into the global @nuxt/schema and nuxt/schema modules. This ensures that defineNuxtConfig provides autocomplete for custom module settings.
declare module '@nuxt/schema' {
interface NuxtConfig extends Omit<NuxtCustomSchema, 'appConfig'> {}
interface NuxtOptions extends Omit<NuxtCustomSchema, 'appConfig'> {}
interface CustomAppConfig extends _CustomAppConfig {}
}
Sources: packages/nuxt/src/core/schema.ts:196-210
Configuration Key Features
| Feature | Description | File Reference |
|---|---|---|
| Runtime Config | Dynamic variables accessible via useRuntimeConfig. Overridable by NUXT_* env vars. | packages/schema/src/types/schema.ts:544-565 |
| App Config | Programmatic application configuration merged with app.config files. | packages/schema/src/types/schema.ts:567-572 |
| Experimental | Opt-in features for early access to framework updates (e.g., componentIslands, asyncContext). | packages/schema/src/types/schema.ts:654-750 |
| Dev Server | Configuration for HTTPS, port, host, and CORS for the development environment. | packages/schema/src/types/schema.ts:574-617 |
Component & Template Configuration
Nuxt Schema also manages how components and templates are discovered and typed. The ComponentsOptions define auto-registration rules, while NuxtTemplate interfaces handle the generation of virtual files.
Component Discovery Schema
The components configuration allows for boolean toggles or detailed directory scanning options.
Nuxt automatically generates a components.d.ts file that provides types for every discovered component, including "Lazy" versions for hydration strategies.
Sources: packages/schema/src/types/schema.ts:40-60, packages/nuxt/src/components/templates.ts:175-185
Runtime Configuration Overrides
The schema defines a strict naming convention for environment variable overrides. For instance, a property testConfig in public runtime config can be overridden by NUXT_PUBLIC_TEST_CONFIG.
Sources: test/fixtures/basic-types/config-types.ts:64-75
Summary
The Nuxt Schema & Configuration system ensures project settings are robust, type-safe, and layer-aware. By leveraging untyped and monorepo packages like @nuxt/schema, the framework provides a seamless developer experience where configuration is not just a JSON object, but a fully documented and typed interface that spans from the nuxt.config.ts to runtime composables.
Sources: packages/schema/package.json:9-11, packages/nuxt/src/core/schema.ts:20-25