0
# Nuxt Integration
1

2
Dedicated Nuxt.js module for seamless integration with Nuxt projects, providing the same inspection capabilities with Nuxt-specific configuration.
3

4
## Capabilities
5

6
### Nuxt Module
7

8
Pre-configured Nuxt module that automatically integrates vite-plugin-inspect with Nuxt's Vite configuration.
9

10
```typescript { .api }
11
/**
12
 * Nuxt module for vite-plugin-inspect
13
 * @param options - Configuration options (same as ViteInspectOptions)
14
 * @returns Configured Nuxt module
15
 */
16
function defineNuxtModule<T>(options: ModuleOptions): NuxtModule<T>;
17

18
interface ModuleOptions extends ViteInspectOptions {}
19
```
20

21
**Usage Example:**
22

23
```typescript
24
// nuxt.config.ts
25
export default defineNuxtConfig({
26
  modules: [
27
    ['vite-plugin-inspect/nuxt', {
28
      dev: true,
29
      build: false,
30
      silent: false
31
    }]
32
  ]
33
});
34

35
// Or using the 'inspect' key
36
export default defineNuxtConfig({
37
  modules: ['vite-plugin-inspect/nuxt'],
38
  inspect: {
39
    dev: true,
40
    build: false,
41
    open: false
42
  }
43
});
44
```
45

46
### Module Configuration
47

48
The Nuxt module accepts all the same configuration options as the main plugin.
49

50
```typescript { .api }
51
interface ModuleOptions {
52
  /** Enable the inspect plugin in dev mode @default true */
53
  dev?: boolean;
54
  /** Enable the inspect plugin in build mode @default false */
55
  build?: boolean;
56
  /** Directory for build inspector UI output @default '.vite-inspect' */
57
  outputDir?: string;
58
  /** Filter for modules to be inspected */
59
  include?: FilterPattern;
60
  /** Filter for modules to not be inspected */
61
  exclude?: FilterPattern;
62
  /** Base URL for inspector UI */
63
  base?: string;
64
  /** Print URL output silently in the terminal @default false */
65
  silent?: boolean;
66
  /** Automatically open inspect page @default false */
67
  open?: boolean;
68
  /** Remove version query and treat as same module @default true */
69
  removeVersionQuery?: boolean;
70
  /** Enable embedded mode @default false */
71
  embedded?: boolean;
72
}
73
```
74

75
### Module Setup Process
76

77
The Nuxt module handles the integration automatically:
78

79
1. **Auto-detection**: Detects Nuxt's Vite configuration
80
2. **Plugin Registration**: Adds the inspect plugin to Vite's plugin array
81
3. **Configuration Merge**: Merges module options with Nuxt's base configuration
82
4. **Environment Handling**: Properly handles Nuxt's SSR and client environments
83

84
### Development Mode Usage
85

86
In Nuxt development mode, the inspector is available at the standard endpoint:
87

88
```bash
89
# Start Nuxt dev server
90
npm run dev
91

92
# Access inspector interface
93
# Visit: http://localhost:3000/__inspect/
94
```
95

96
**Nuxt-specific Features:**
97

98
- **SSR Environment**: Inspect server-side rendering transformations
99
- **Client Environment**: Inspect client-side transformations  
100
- **Universal Mode**: View both environments simultaneously
101
- **Nuxt Plugins**: See how Nuxt's built-in plugins transform modules
102

103
### Build Mode Usage
104

105
Enable build inspection for production builds:
106

107
```typescript
108
// nuxt.config.ts
109
export default defineNuxtConfig({
110
  modules: ['vite-plugin-inspect/nuxt'],
111
  inspect: {
112
    build: true,
113
    outputDir: '.nuxt-inspect'
114
  }
115
});
116
```
117

118
After building:
119

120
```bash
121
# Build the Nuxt app
122
npm run build
123

124
# Serve the inspection report
125
npx serve .nuxt-inspect
126
```
127

128
### Nuxt-Specific Configuration Examples
129

130
#### Development Only
131

132
```typescript
133
// nuxt.config.ts
134
export default defineNuxtConfig({
135
  modules: ['vite-plugin-inspect/nuxt'],
136
  inspect: {
137
    dev: process.env.NODE_ENV === 'development',
138
    build: false,
139
    silent: false
140
  }
141
});
142
```
143

144
#### Filter Nuxt-Specific Files
145

146
```typescript
147
// nuxt.config.ts
148
export default defineNuxtConfig({
149
  modules: ['vite-plugin-inspect/nuxt'],
150
  inspect: {
151
    include: [
152
      'pages/**/*.vue',
153
      'components/**/*.vue', 
154
      'layouts/**/*.vue',
155
      'plugins/**/*.{js,ts}',
156
      'middleware/**/*.{js,ts}'
157
    ],
158
    exclude: [
159
      '.nuxt/**',
160
      'node_modules/**'
161
    ]
162
  }
163
});
164
```
165

166
#### Custom Base Path
167

168
```typescript
169
// nuxt.config.ts
170
export default defineNuxtConfig({
171
  modules: ['vite-plugin-inspect/nuxt'],
172
  inspect: {
173
    base: '/admin/',  // Inspector at /admin/__inspect/
174
  }
175
});
176
```
177

178
### Environment-Specific Inspection
179

180
Nuxt applications run in multiple environments (client, server). The inspector handles both:
181

182
```typescript
183
// Access client environment data
184
const clientModules = await rpc.getModulesList({ 
185
  vite: 'nuxt-instance', 
186
  env: 'client' 
187
});
188

189
// Access SSR environment data  
190
const ssrModules = await rpc.getModulesList({ 
191
  vite: 'nuxt-instance', 
192
  env: 'ssr' 
193
});
194

195
// Compare environments
196
console.log('Client modules:', clientModules.length);
197
console.log('SSR modules:', ssrModules.length);
198

199
// Find environment-specific modules
200
const clientOnlyModules = clientModules.filter(cm => 
201
  !ssrModules.some(sm => sm.id === cm.id)
202
);
203
console.log('Client-only modules:', clientOnlyModules.map(m => m.id));
204
```
205

206
### Integration with Nuxt DevTools
207

208
The inspector can complement Nuxt DevTools for comprehensive debugging:
209

210
```typescript
211
// nuxt.config.ts
212
export default defineNuxtConfig({
213
  devtools: { enabled: true },
214
  modules: ['vite-plugin-inspect/nuxt'],
215
  inspect: {
216
    dev: true,
217
    embedded: true  // Better integration with other tools
218
  }
219
});
220
```
221

222
### Advanced Nuxt Patterns
223

224
#### Conditional Loading
225

226
```typescript
227
// nuxt.config.ts
228
export default defineNuxtConfig({
229
  modules: [
230
    // Only load in development or when specifically requested
231
    ...(process.env.NODE_ENV === 'development' || process.env.ENABLE_INSPECT
232
      ? [['vite-plugin-inspect/nuxt', { dev: true, build: false }]]
233
      : []
234
    )
235
  ]
236
});
237
```
238

239
#### Per-Environment Configuration
240

241
```typescript
242
// nuxt.config.ts
243
const inspectConfig = {
244
  development: {
245
    dev: true,
246
    build: false,
247
    open: false,
248
    silent: false
249
  },
250
  production: {
251
    dev: false, 
252
    build: true,
253
    outputDir: '.inspect-prod'
254
  }
255
};
256

257
export default defineNuxtConfig({
258
  modules: ['vite-plugin-inspect/nuxt'],
259
  inspect: inspectConfig[process.env.NODE_ENV as keyof typeof inspectConfig] || inspectConfig.development
260
});
261
```
262

263
#### Module Registration Helper
264

265
```typescript
266
// utils/modules.ts
267
export function createInspectModule(options: Partial<ModuleOptions> = {}) {
268
  const defaults: ModuleOptions = {
269
    dev: process.env.NODE_ENV === 'development',
270
    build: false,
271
    silent: process.env.CI === 'true',
272
    open: false
273
  };
274
  
275
  return ['vite-plugin-inspect/nuxt', { ...defaults, ...options }];
276
}
277

278
// nuxt.config.ts
279
import { createInspectModule } from './utils/modules';
280

281
export default defineNuxtConfig({
282
  modules: [
283
    createInspectModule({
284
      include: ['pages/**/*.vue', 'components/**/*.vue']
285
    })
286
  ]
287
});
288
```
289

290
### Troubleshooting
291

292
#### Module Not Loading
293

294
```typescript
295
// Ensure proper module registration
296
export default defineNuxtConfig({
297
  modules: [
298
    // Correct ways:
299
    'vite-plugin-inspect/nuxt',                    // Simple
300
    ['vite-plugin-inspect/nuxt', { dev: true }],  // With options
301
  ],
302
  
303
  // Alternative configuration
304
  inspect: {
305
    dev: true
306
  }
307
});
308
```
309

310
#### SSR Compatibility
311

312
The plugin is fully compatible with Nuxt's SSR mode:
313

314
```typescript
315
// Both environments are automatically handled
316
export default defineNuxtConfig({
317
  ssr: true,  // or false
318
  modules: ['vite-plugin-inspect/nuxt'],
319
  inspect: {
320
    dev: true
321
    // Automatically inspects both client and server builds
322
  }
323
});
324
```