0
# Configuration
1

2
Configuration utilities for defining and managing Nuxt application settings with full TypeScript support. The configuration system provides extensive customization options for routing, rendering, modules, and runtime behavior.
3

4
## Capabilities
5

6
### Define Nuxt Configuration
7

8
Identity function that provides TypeScript support for Nuxt configuration files.
9

10
```typescript { .api }
11
/**
12
 * Define Nuxt configuration with TypeScript support
13
 * @param config - The configuration object
14
 * @returns The same configuration object with proper typing
15
 */
16
function defineNuxtConfig(config: NuxtConfig): NuxtConfig;
17

18
interface NuxtConfig {
19
  // Application
20
  ssr?: boolean;
21
  target?: "static" | "server";
22
  mode?: "universal" | "spa";
23
  modern?: boolean | "client" | "server";
24
  
25
  // Directory structure
26
  rootDir?: string;
27
  srcDir?: string;
28
  buildDir?: string;
29
  
30
  // Modules and plugins
31
  modules?: (string | [string, any] | ModuleOptions)[];
32
  buildModules?: (string | [string, any] | ModuleOptions)[];
33
  plugins?: (string | PluginOptions)[];
34
  
35
  // Styling
36
  css?: string[];
37
  
38
  // Runtime configuration
39
  runtimeConfig?: RuntimeConfig;
40
  publicRuntimeConfig?: Record<string, any>;
41
  privateRuntimeConfig?: Record<string, any>;
42
  
43
  // Head configuration
44
  head?: MetaObject;
45
  
46
  // Router configuration
47
  router?: RouterConfig;
48
  
49
  // Build configuration
50
  build?: BuildConfig;
51
  
52
  // Server configuration
53
  server?: ServerConfig;
54
  
55
  // Development configuration
56
  dev?: boolean;
57
  debug?: boolean;
58
  
59
  // Hooks
60
  hooks?: NuxtHooks;
61
  
62
  // Watchers
63
  watch?: string[];
64
  watchers?: {
65
    webpack?: any;
66
    chokidar?: any;
67
  };
68
  
69
  // Auto-imports
70
  imports?: ImportsOptions;
71
  
72
  // Components
73
  components?: ComponentsOptions;
74
  
75
  // Layouts
76
  layouts?: Record<string, string>;
77
  
78
  // Error page
79
  ErrorPage?: string;
80
  
81
  // Loading configuration
82
  loading?: LoadingConfig | string | false;
83
  loadingIndicator?: LoadingIndicatorConfig | string | false;
84
  
85
  // Transition configuration
86
  pageTransition?: TransitionConfig | string | false;
87
  layoutTransition?: TransitionConfig | string | false;
88
  
89
  // Generate configuration (for static generation)
90
  generate?: GenerateConfig;
91
  
92
  // Experimental features
93
  experimental?: ExperimentalConfig;
94
  
95
  [key: string]: any;
96
}
97

98
interface RuntimeConfig {
99
  [key: string]: any;
100
  public?: {
101
    [key: string]: any;
102
  };
103
}
104

105
interface ModuleOptions {
106
  src: string;
107
  options?: any;
108
  mode?: "client" | "server" | "all";
109
}
110

111
interface PluginOptions {
112
  src: string;
113
  mode?: "client" | "server" | "all";
114
  ssr?: boolean;
115
}
116
```
117

118
**Usage Examples:**
119

120
```typescript
121
// nuxt.config.ts
122
import { defineNuxtConfig } from "nuxt/config";
123

124
export default defineNuxtConfig({
125
  // Basic configuration
126
  ssr: true,
127
  target: "server",
128
  
129
  // Modules
130
  modules: [
131
    "@nuxtjs/tailwindcss",
132
    "@nuxtjs/color-mode",
133
    ["@nuxtjs/google-fonts", {
134
      families: {
135
        Inter: [400, 500, 600, 700]
136
      }
137
    }]
138
  ],
139
  
140
  // Styling
141
  css: [
142
    "~/assets/css/main.css"
143
  ],
144
  
145
  // Runtime configuration
146
  runtimeConfig: {
147
    // Private keys (available only on server-side)
148
    apiSecret: process.env.API_SECRET,
149
    
150
    // Public keys (exposed to client-side)
151
    public: {
152
      apiBase: process.env.API_BASE || "/api",
153
      appName: "My Nuxt App"
154
    }
155
  },
156
  
157
  // Head configuration
158
  head: {
159
    title: "My Nuxt App",
160
    meta: [
161
      { charset: "utf-8" },
162
      { name: "viewport", content: "width=device-width, initial-scale=1" },
163
      { hid: "description", name: "description", content: "My amazing Nuxt application" }
164
    ],
165
    link: [
166
      { rel: "icon", type: "image/x-icon", href: "/favicon.ico" }
167
    ]
168
  }
169
});
170
```
171

172
### Advanced Configuration
173

174
```typescript
175
// nuxt.config.ts
176
import { defineNuxtConfig } from "nuxt/config";
177

178
export default defineNuxtConfig({
179
  // Server configuration
180
  server: {
181
    port: 3000,
182
    host: "0.0.0.0"
183
  },
184
  
185
  // Router configuration
186
  router: {
187
    base: "/my-app/",
188
    middleware: ["auth"],
189
    extendRoutes(routes, resolve) {
190
      routes.push({
191
        name: "custom",
192
        path: "/custom",
193
        component: resolve(__dirname, "pages/custom.vue")
194
      });
195
    }
196
  },
197
  
198
  // Build configuration
199
  build: {
200
    transpile: ["@my-org/my-package"],
201
    extend(config, ctx) {
202
      if (ctx.isDev && ctx.isClient) {
203
        config.module.rules.push({
204
          enforce: "pre",
205
          test: /\.(js|vue)$/,
206
          loader: "eslint-loader",
207
          exclude: /(node_modules)/
208
        });
209
      }
210
    }
211
  },
212
  
213
  // Components auto-discovery
214
  components: [
215
    "~/components",
216
    { path: "~/components/ui", prefix: "ui" }
217
  ],
218
  
219
  // Auto-imports
220
  imports: {
221
    dirs: [
222
      "composables/**",
223
      "utils/**"
224
    ]
225
  },
226
  
227
  // Development tools
228
  devtools: { enabled: true },
229
  
230
  // Experimental features
231
  experimental: {
232
    payloadExtraction: false,
233
    typedPages: true
234
  }
235
});
236
```
237

238
### Environment-based Configuration
239

240
```typescript
241
// nuxt.config.ts
242
import { defineNuxtConfig } from "nuxt/config";
243

244
export default defineNuxtConfig({
245
  // Environment-specific settings
246
  ...(process.env.NODE_ENV === "production" && {
247
    ssr: true,
248
    nitro: {
249
      minify: true,
250
      compressPublicAssets: true
251
    }
252
  }),
253
  
254
  ...(process.env.NODE_ENV === "development" && {
255
    devtools: { enabled: true },
256
    debug: true
257
  }),
258
  
259
  // Runtime config with environment variables
260
  runtimeConfig: {
261
    // Server-only
262
    databaseUrl: process.env.DATABASE_URL,
263
    jwtSecret: process.env.JWT_SECRET,
264
    
265
    // Public (client + server)
266
    public: {
267
      apiBase: process.env.NUXT_PUBLIC_API_BASE || "/api",
268
      appVersion: process.env.npm_package_version || "1.0.0",
269
      gtag: {
270
        id: process.env.GOOGLE_ANALYTICS_ID
271
      }
272
    }
273
  },
274
  
275
  // Conditional modules
276
  modules: [
277
    "@nuxtjs/tailwindcss",
278
    ...(process.env.ANALYZE === "true" ? ["@nuxtjs/bundle-analyzer"] : [])
279
  ]
280
});
281
```
282

283
### TypeScript Configuration
284

285
```typescript
286
// nuxt.config.ts
287
import { defineNuxtConfig } from "nuxt/config";
288

289
export default defineNuxtConfig({
290
  // TypeScript configuration
291
  typescript: {
292
    strict: true,
293
    typeCheck: true
294
  },
295
  
296
  // Vite configuration for TypeScript
297
  vite: {
298
    vue: {
299
      script: {
300
        defineModel: true,
301
        propsDestructure: true
302
      }
303
    }
304
  },
305
  
306
  // Auto-imports with TypeScript
307
  imports: {
308
    autoImport: true,
309
    presets: [
310
      {
311
        from: "vue-i18n",
312
        imports: ["useI18n"]
313
      }
314
    ]
315
  }
316
});
317
```
318

319
### Module Configuration
320

321
```typescript
322
// nuxt.config.ts
323
import { defineNuxtConfig } from "nuxt/config";
324

325
export default defineNuxtConfig({
326
  modules: [
327
    // Simple module
328
    "@nuxtjs/tailwindcss",
329
    
330
    // Module with inline options
331
    ["@nuxtjs/google-fonts", {
332
      families: {
333
        Inter: [400, 500, 600, 700],
334
        "Fira Code": [400, 500]
335
      },
336
      display: "swap"
337
    }],
338
    
339
    // Local module
340
    "~/modules/my-module",
341
    
342
    // Conditional module
343
    ...(process.env.NODE_ENV === "development" ? ["@nuxtjs/eslint-module"] : [])
344
  ],
345
  
346
  // Module-specific configuration
347
  tailwindcss: {
348
    configPath: "~/config/tailwind.config.js",
349
    exposeConfig: true
350
  },
351
  
352
  colorMode: {
353
    preference: "system",
354
    fallback: "light",
355
    hid: "nuxt-color-mode-script",
356
    globalName: "__NUXT_COLOR_MODE__",
357
    componentName: "ColorScheme",
358
    classPrefix: "",
359
    classSuffix: "-mode",
360
    storageKey: "nuxt-color-mode"
361
  }
362
});
363
```
364

365
## Configuration Types
366

367
```typescript { .api }
368
interface BuildConfig {
369
  analyze?: boolean | any;
370
  extractCSS?: boolean | any;
371
  optimizeCSS?: boolean | any;
372
  splitChunks?: {
373
    layouts?: boolean;
374
    pages?: boolean;
375
    commons?: boolean;
376
  };
377
  transpile?: (string | RegExp)[];
378
  extend?: (config: any, ctx: BuildContext) => void;
379
  babel?: any;
380
  postcss?: any;
381
  html?: any;
382
  publicPath?: string;
383
  filenames?: any;
384
  loaders?: any;
385
  plugins?: any[];
386
  terser?: any;
387
  hardSource?: boolean;
388
  parallel?: boolean;
389
  cache?: boolean;
390
  standalone?: boolean;
391
}
392

393
interface ServerConfig {
394
  port?: number;
395
  host?: string;
396
  https?: boolean | any;
397
  socket?: string;
398
  timing?: boolean | any;
399
}
400

401
interface RouterConfig {
402
  base?: string;
403
  mode?: "hash" | "history";
404
  linkActiveClass?: string;
405
  linkExactActiveClass?: string;
406
  linkPrefetchedClass?: string;
407
  middleware?: string | string[];
408
  extendRoutes?: (routes: any[], resolve: any) => void;
409
  scrollBehavior?: (to: any, from: any, savedPosition: any) => any;
410
  parseQuery?: (query: string) => any;
411
  stringifyQuery?: (query: any) => string;
412
  fallback?: boolean;
413
  prefetchLinks?: boolean;
414
  prefetchPayloads?: boolean;
415
  trailingSlash?: boolean;
416
}
417

418
interface LoadingConfig {
419
  color?: string;
420
  failedColor?: string;
421
  height?: string;
422
  throttle?: number;
423
  duration?: number;
424
  continuous?: boolean;
425
  rtl?: boolean;
426
}
427

428
interface TransitionConfig {
429
  name?: string;
430
  mode?: "in-out" | "out-in";
431
  css?: boolean;
432
  duration?: number | { enter: number; leave: number };
433
  type?: "transition" | "animation";
434
  enterClass?: string;
435
  enterToClass?: string;
436
  enterActiveClass?: string;
437
  leaveClass?: string;
438
  leaveToClass?: string;
439
  leaveActiveClass?: string;
440
  beforeEnter?: (el: Element) => void;
441
  enter?: (el: Element, done: () => void) => void;
442
  afterEnter?: (el: Element) => void;
443
  enterCancelled?: (el: Element) => void;
444
  beforeLeave?: (el: Element) => void;
445
  leave?: (el: Element, done: () => void) => void;
446
  afterLeave?: (el: Element) => void;
447
  leaveCancelled?: (el: Element) => void;
448
}
449

450
interface GenerateConfig {
451
  dir?: string;
452
  routes?: string[] | ((routes: string[]) => string[] | Promise<string[]>);
453
  exclude?: (string | RegExp)[];
454
  concurrency?: number;
455
  interval?: number;
456
  subFolders?: boolean;
457
  fallback?: boolean | string;
458
}
459

460
interface ExperimentalConfig {
461
  payloadExtraction?: boolean;
462
  typedPages?: boolean;
463
  watcher?: string;
464
  configSchema?: boolean;
465
  treeshakeClientOnly?: boolean;
466
  emitRouteChunkError?: "reload" | "manual";
467
  restoreState?: boolean;
468
}
469

470
interface BuildContext {
471
  isClient: boolean;
472
  isServer: boolean;
473
  isDev: boolean;
474
  isStatic: boolean;
475
  target: string;
476
  loaders: any;
477
}
478
```