App Config vs Runtime Config
Relevant source files
The following files were used as context for generating this wiki page:
Nuxt provides two primary mechanisms for handling application configuration: App Config and Runtime Config. While both serve to parameterize application behavior, they differ significantly in their lifecycle, accessibility, and intended use cases.
Runtime Config is designed for values that need to be updated at runtime using environment variables, such as API secrets or base URLs. It supports a clear distinction between private values (server-only) and public values (available to the client). In contrast, App Config is used for reactive, UI-related configuration that can be updated via Hot Module Replacement (HMR) during development and is fully exposed to the application.
Sources: packages/schema/src/types/schema.ts:684-706, packages/nuxt/src/core/templates.ts:314-340
Runtime Config
Runtime Config allows passing dynamic configuration and environment variables to the Nuxt application context. It is structured into private and public segments.
Structure and Accessibility
- Private Config: Values defined at the top level of
runtimeConfigare only accessible on the server usinguseRuntimeConfig. These are ideal for sensitive information like API secret tokens. - Public Config: Values under
runtimeConfig.publicare exposed to the browser. - Environment Variables: Values are automatically replaced by matching environment variables at runtime (e.g.,
NUXT_API_KEYoverwritesapiKey).
Sources: packages/schema/src/types/schema.ts:684-706, test/fixtures/basic-types/config-types.ts:62-79
Technical Implementation
Nuxt generates TypeScript definitions for runtime configuration to ensure type safety. Private keys (excluding public and nitro) are processed into a SharedRuntimeConfig interface, while public keys are mapped to SharedPublicRuntimeConfig.
The diagram shows how configuration flows from build-time schema resolution to runtime environment variable merging.
Sources: packages/nuxt/src/core/templates.ts:241-285
App Config
App Config is intended for public, reactive configuration that does not contain sensitive information. It is merged from multiple layers and can be updated without a full server restart in development.
Merging Logic
App Config is resolved by merging an inlineConfig (from nuxt.config) with multiple app.config files found across different layers. The merge utilizes defuFn to handle function-based configuration values.
Sources: packages/nuxt/src/core/app.ts:245-252, packages/nuxt/src/core/templates.ts:400-424
HMR Support
In development, App Config supports Hot Module Replacement. When an app.config file is modified, the _replaceAppConfig function is triggered to update the configuration in the running client without a page reload.
Sources: packages/nuxt/src/core/templates.ts:430-437
Comparison Table
| Feature | Runtime Config | App Config |
|---|---|---|
| Primary Purpose | Env variables, Secrets, Dynamic URLs | UI Configuration, Theme settings |
| Reactivity | Static after boot | Fully reactive (supports HMR) |
| Security | Supports server-only private keys | Always public / client-exposed |
| Merging | Merges with process.env | Merges multiple app.config files |
| Type Support | Generated via untyped schema | Generated via MergedAppConfig type |
Sources: packages/schema/src/types/schema.ts:684-712, packages/nuxt/src/core/templates.ts:314-445
Configuration Lifecycle
The following sequence diagram illustrates how Nuxt initializes these configurations during the application setup process.
The diagram highlights the parallel compilation of config templates and the subsequent runtime injection.
Sources: packages/nuxt/src/core/app.ts:46-70, packages/nuxt/src/core/templates.ts:439-445
Type Augmentation and Resolution
Nuxt uses complex TypeScript mappings to ensure that custom configurations provided by users or modules are correctly typed.
App Config Merging Types
The system uses a MergedAppConfig utility type to deeply merge ResolvedAppConfig (built-in/inline) with CustomAppConfig (user-defined). This ensures that if a user provides a specific type for a key, it takes precedence over the generic inferred type.
Sources: packages/nuxt/src/core/templates.ts:365-381
Runtime Value Hints
For Runtime Config, Nuxt provides TypeScript hints that inform developers which environment variable can be used to override a specific key at runtime (e.g., NUXT_PUBLIC_TEST_CONFIG).
Sources: test/fixtures/basic-types/config-types.ts:70-76
Summary
Runtime Config and App Config are complementary systems. Runtime Config is the authoritative source for environment-dependent and sensitive data, utilizing a strict server/client boundary. App Config provides a flexible, layer-aware, and HMR-capable system for defining the visual and behavioral parameters of the application UI.
Sources: packages/schema/src/types/schema.ts:684-712, packages/nuxt/src/core/templates.ts:439-445