0
# Configuration & Loading
1

2
Configuration loading and schema management with support for layers, custom configurations, and Nuxt instance management.
3

4
## Capabilities
5

6
### Configuration Loading
7

8
Load and resolve Nuxt configuration with layer support and environment-specific overrides.
9

10
```typescript { .api }
11
/**
12
 * Load and resolve Nuxt configuration with layers
13
 * @param opts - Configuration loading options
14
 * @returns Promise resolving to complete NuxtOptions
15
 */
16
function loadNuxtConfig(opts: LoadNuxtConfigOptions): Promise<NuxtOptions>;
17

18
interface LoadNuxtConfigOptions {
19
  /** Configuration file path or directory */
20
  cwd?: string;
21
  /** Override configuration values */
22
  overrides?: Partial<NuxtOptions>;
23
  /** Environment name (development, production, etc.) */
24
  envName?: string;
25
}
26

27
interface NuxtOptions {
28
  [key: string]: any;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { loadNuxtConfig } from "@nuxt/kit";
36

37
// Load configuration from current directory
38
const config = await loadNuxtConfig({
39
  cwd: process.cwd()
40
});
41

42
// Load with overrides
43
const config = await loadNuxtConfig({
44
  cwd: "./my-nuxt-app",
45
  overrides: {
46
    dev: false,
47
    ssr: true
48
  },
49
  envName: "production"
50
});
51
```
52

53
### Schema Extension
54

55
Extend and modify Nuxt configuration schema with custom definitions.
56

57
```typescript { .api }
58
/**
59
 * Extend Nuxt configuration schema
60
 * @param def - Schema definition or function returning schema definition
61
 */
62
function extendNuxtSchema(def: SchemaDefinition | (() => SchemaDefinition)): void;
63

64
interface SchemaDefinition {
65
  [key: string]: SchemaProperty;
66
}
67

68
interface SchemaProperty {
69
  type?: string;
70
  default?: any;
71
  description?: string;
72
  [key: string]: any;
73
}
74
```
75

76
**Usage Examples:**
77

78
```typescript
79
import { extendNuxtSchema } from "@nuxt/kit";
80

81
// Extend schema with new configuration options
82
extendNuxtSchema({
83
  myModule: {
84
    type: "object",
85
    default: {},
86
    properties: {
87
      enabled: {
88
        type: "boolean",
89
        default: true,
90
        description: "Enable my module functionality"
91
      },
92
      apiUrl: {
93
        type: "string",
94
        default: "https://api.example.com",
95
        description: "API endpoint URL"
96
      }
97
    }
98
  }
99
});
100

101
// Dynamic schema extension
102
extendNuxtSchema(() => ({
103
  dynamicOption: {
104
    type: "string",
105
    default: process.env.DYNAMIC_VALUE || "default"
106
  }
107
}));
108
```
109

110
### Nuxt Instance Management
111

112
Load and build Nuxt instances programmatically for testing and tooling.
113

114
```typescript { .api }
115
/**
116
 * Load a Nuxt instance with configuration
117
 * @param opts - Loading options including configuration overrides
118
 * @returns Promise resolving to configured Nuxt instance
119
 */
120
function loadNuxt(opts: LoadNuxtOptions): Promise<Nuxt>;
121

122
/**
123
 * Build a Nuxt instance (prepare for production)
124
 * @param nuxt - Nuxt instance to build
125
 * @returns Promise resolving to build result
126
 */
127
function buildNuxt(nuxt: Nuxt): Promise<any>;
128

129
interface LoadNuxtOptions {
130
  /** Working directory for the Nuxt project */
131
  cwd?: string;
132
  /** Development mode flag */
133
  dev?: boolean;
134
  /** Configuration overrides */
135
  overrides?: Partial<NuxtOptions>;
136
  /** Ready callback after instance is loaded */
137
  ready?: boolean;
138
}
139

140
interface Nuxt {
141
  options: NuxtOptions;
142
  hooks: Hookable;
143
  hook: Hookable['hook'];
144
  callHook: Hookable['callHook'];
145
  ready: () => Promise<void>;
146
  close: () => Promise<void>;
147
  [key: string]: any;
148
}
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
import { loadNuxt, buildNuxt } from "@nuxt/kit";
155

156
// Load Nuxt instance for development
157
const nuxt = await loadNuxt({
158
  cwd: "./my-app",
159
  dev: true,
160
  ready: false
161
});
162

163
// Prepare instance
164
await nuxt.ready();
165

166
// Build for production
167
const nuxtProd = await loadNuxt({
168
  cwd: "./my-app",
169
  dev: false,
170
  overrides: {
171
    nitro: {
172
      preset: "node-server"
173
    }
174
  }
175
});
176

177
await buildNuxt(nuxtProd);
178
```
179

180
### Layer Management
181

182
Work with Nuxt layers and get layer directory information.
183

184
```typescript { .api }
185
/**
186
 * Get resolved directory paths for all layers in priority order
187
 * @param nuxt - Nuxt instance (defaults to current context)
188
 * @returns Array of LayerDirectories objects
189
 */
190
function getLayerDirectories(nuxt?: Nuxt): LayerDirectories[];
191

192
interface LayerDirectories {
193
  /** Nuxt rootDir (`/` by default) */
194
  readonly root: string;
195
  /** Nitro source directory (`/server` by default) */
196
  readonly server: string;
197
  /** Local modules directory (`/modules` by default) */
198
  readonly modules: string;
199
  /** Shared directory (`/shared` by default) */
200
  readonly shared: string;
201
  /** Public directory (`/public` by default) */
202
  readonly public: string;
203
  /** Nuxt srcDir (`/app/` by default) */
204
  readonly app: string;
205
  /** Layouts directory (`/app/layouts` by default) */
206
  readonly appLayouts: string;
207
  /** Middleware directory (`/app/middleware` by default) */
208
  readonly appMiddleware: string;
209
  /** Pages directory (`/app/pages` by default) */
210
  readonly appPages: string;
211
  /** Plugins directory (`/app/plugins` by default) */
212
  readonly appPlugins: string;
213
}
214
```
215

216
**Usage Examples:**
217

218
```typescript
219
import { getLayerDirectories } from "@nuxt/kit";
220

221
// Get all layer directories
222
const layers = getLayerDirectories();
223

224
layers.forEach((layer, index) => {
225
  console.log(`Layer ${index}: ${layer.root}`);
226
  console.log(`  App: ${layer.app}`);
227
  console.log(`  Layouts: ${layer.appLayouts}`);
228
  console.log(`  Pages: ${layer.appPages}`);
229
  console.log(`  Plugins: ${layer.appPlugins}`);
230
});
231
```
232

233
## Types
234

235
```typescript { .api }
236
interface Hookable {
237
  hook<T>(name: string, fn: T): () => void;
238
  callHook<T>(name: string, ...args: any[]): Promise<T>;
239
  [key: string]: any;
240
}
241
```