0
# Configuration System
1

2
The configuration system in @nuxt/schema provides complete TypeScript coverage for all Nuxt configuration options, enabling type-safe configuration management and IntelliSense support.
3

4
## Core Configuration Interfaces
5

6
### NuxtConfig
7

8
The main user-facing configuration interface used in `nuxt.config.ts` files.
9

10
```typescript { .api }
11
interface NuxtConfig extends DeepPartial<Omit<ConfigSchema, 'vue' | 'vite' | 'runtimeConfig' | 'webpack' | 'nitro'>> {
12
  vue?: Omit<DeepPartial<ConfigSchema['vue']>, 'config'> & { 
13
    config?: Partial<Filter<VueAppConfig, string | boolean>> 
14
  }
15
  vite?: ConfigSchema['vite']
16
  nitro?: NitroConfig
17
  runtimeConfig?: Overrideable<RuntimeConfig>
18
  webpack?: DeepPartial<ConfigSchema['webpack']> & {
19
    $client?: DeepPartial<ConfigSchema['webpack']>
20
    $server?: DeepPartial<ConfigSchema['webpack']>
21
  }
22
  $schema?: SchemaDefinition
23
}
24
```
25

26
### NuxtOptions
27

28
The normalized internal configuration interface used by Nuxt at runtime.
29

30
```typescript { .api }
31
interface NuxtOptions extends Omit<ConfigSchema, 'vue' | 'sourcemap' | 'debug' | 'builder' | 'postcss' | 'webpack'> {
32
  vue: Omit<ConfigSchema['vue'], 'config'> & { 
33
    config?: Partial<Filter<VueAppConfig, string | boolean>> 
34
  }
35
  sourcemap: Required<Exclude<ConfigSchema['sourcemap'], boolean>>
36
  debug: Required<Exclude<ConfigSchema['debug'], true>>
37
  builder: '@nuxt/vite-builder' | '@nuxt/webpack-builder' | '@nuxt/rspack-builder' | NuxtBuilder
38
  postcss: Omit<ConfigSchema['postcss'], 'order'> & { 
39
    order: Exclude<ConfigSchema['postcss']['order'], string> 
40
  }
41
  webpack: ConfigSchema['webpack'] & {
42
    $client: ConfigSchema['webpack']
43
    $server: ConfigSchema['webpack']
44
  }
45
  _layers: readonly NuxtConfigLayer[]
46
  $schema: SchemaDefinition
47
}
48
```
49

50
### NuxtConfigLayer
51

52
Configuration layer support for extending configurations from multiple sources.
53

54
```typescript { .api }
55
type NuxtConfigLayer = ResolvedConfig<NuxtConfig & {
56
  srcDir: ConfigSchema['srcDir']
57
  rootDir: ConfigSchema['rootDir']
58
}> & {
59
  cwd: string
60
  configFile: string
61
}
62
```
63

64
## Key Configuration Areas
65

66
### Application Configuration
67

68
```typescript { .api }
69
interface AppConfig {
70
  baseURL: string
71
  buildAssetsDir: string
72
  cdnURL: string
73
  head: NuxtAppConfig['head']
74
  layoutTransition: NuxtAppConfig['layoutTransition']
75
  pageTransition: NuxtAppConfig['pageTransition']
76
  viewTransition: NuxtAppConfig['viewTransition']
77
  keepalive: NuxtAppConfig['keepalive']
78
  rootId: string | false
79
  rootTag: string
80
  rootAttrs: SerializableHtmlAttributes
81
  teleportTag: string
82
  teleportId: string | false
83
  teleportAttrs: SerializableHtmlAttributes
84
  spaLoaderTag: string
85
  spaLoaderAttrs: SerializableHtmlAttributes
86
}
87
```
88

89
### Vue Configuration
90

91
```typescript { .api }
92
interface VueConfig {
93
  transformAssetUrls: AssetURLTagConfig
94
  compilerOptions: CompilerOptions
95
  runtimeCompiler: boolean
96
  propsDestructure: boolean
97
  config: Serializable<VueAppConfig>
98
}
99
```
100

101
### Build Configuration
102

103
```typescript { .api }
104
interface BuildConfig {
105
  transpile: Array<string | RegExp | ((ctx: { isClient?: boolean, isServer?: boolean, isDev: boolean }) => string | RegExp | false)>
106
  templates: NuxtTemplate<any>[]
107
  analyze: boolean | { enabled?: boolean } & ((0 extends 1 & BundleAnalyzerPlugin.Options ? Record<string, unknown> : BundleAnalyzerPlugin.Options) | PluginVisualizerOptions)
108
}
109
```
110

111
### Development Server Configuration
112

113
```typescript { .api }
114
interface DevServerConfig {
115
  https: boolean | { key: string, cert: string } | { pfx: string, passphrase: string }
116
  port: number
117
  host: string | undefined
118
  url: string
119
  loadingTemplate: (data: { loading?: string }) => string
120
  cors: H3CorsOptions
121
}
122
```
123

124
### TypeScript Configuration
125

126
```typescript { .api }
127
interface TypeScriptConfig {
128
  strict: boolean
129
  builder: 'vite' | 'webpack' | 'rspack' | 'shared' | false | undefined | null
130
  hoist: Array<string>
131
  includeWorkspace: boolean
132
  typeCheck: boolean | 'build'
133
  tsConfig: TSConfig & { vueCompilerOptions?: RawVueCompilerOptions }
134
  nodeTsConfig: TSConfig
135
  sharedTsConfig: TSConfig
136
  shim: boolean
137
}
138
```
139

140
## Utility Types
141

142
### Runtime Value
143

144
Provides runtime override support for configuration values.
145

146
```typescript { .api }
147
type RuntimeValue<T, B extends string> = T & { [message]?: B }
148

149
type UpperSnakeCase<S extends string> = Uppercase<SnakeCase<S>>
150
```
151

152
### Deep Partial
153

154
Recursive partial type for configuration options.
155

156
```typescript { .api }
157
type DeepPartial<T> = T extends Function 
158
  ? T 
159
  : T extends Record<string, any> 
160
    ? { [P in keyof T]?: DeepPartial<T[P]> } 
161
    : T
162
```
163

164
## Usage Examples
165

166
### Basic Configuration
167

168
```typescript
169
import type { NuxtConfig } from '@nuxt/schema';
170

171
const config: NuxtConfig = {
172
  // Directory structure
173
  srcDir: 'src/',
174
  buildDir: '.output',
175
  
176
  // Application settings
177
  app: {
178
    baseURL: '/app/',
179
    head: {
180
      title: 'My Nuxt App',
181
      meta: [
182
        { name: 'description', content: 'My amazing Nuxt application' }
183
      ]
184
    }
185
  },
186
  
187
  // Module system
188
  modules: [
189
    '@nuxtjs/tailwindcss',
190
    ['@pinia/nuxt', { autoImports: ['defineStore'] }]
191
  ],
192
  
193
  // TypeScript configuration
194
  typescript: {
195
    strict: true,
196
    typeCheck: true
197
  }
198
};
199
```
200

201
### Advanced Configuration with Layers
202

203
```typescript
204
import type { NuxtConfig } from '@nuxt/schema';
205

206
const config: NuxtConfig = {
207
  extends: [
208
    '@nuxt/ui-pro',
209
    'github:my-org/nuxt-base-layer'
210
  ],
211
  
212
  // Runtime configuration with environment variable support
213
  runtimeConfig: {
214
    // Private keys (server-only)
215
    apiSecret: process.env.API_SECRET,
216
    
217
    // Public keys (exposed to client)
218
    public: {
219
      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api'
220
    }
221
  },
222
  
223
  // Builder-specific configuration
224
  vite: {
225
    optimizeDeps: {
226
      include: ['lodash-es']
227
    }
228
  },
229
  
230
  webpack: {
231
    extractCSS: true,
232
    optimization: {
233
      splitChunks: {
234
        chunks: 'all'
235
      }
236
    }
237
  }
238
};
239
```
240

241
### Experimental Features
242

243
```typescript
244
const config: NuxtConfig = {
245
  experimental: {
246
    // Enable experimental features
247
    componentIslands: true,
248
    typedPages: true,
249
    viewTransition: true,
250
    
251
    // Default options for composables
252
    defaults: {
253
      nuxtLink: {
254
        trailingSlash: 'append'
255
      },
256
      useAsyncData: {
257
        deep: false
258
      }
259
    }
260
  },
261
  
262
  future: {
263
    compatibilityVersion: 4,
264
    typescriptBundlerResolution: true
265
  }
266
};
267
```
268

269
The configuration system ensures that all options are properly typed and validated, providing excellent developer experience with full IntelliSense support and compile-time error checking.