0
# Nuxt DevTools
1

2
Nuxt DevTools is a comprehensive development toolkit that provides visual insights and transparency for Nuxt applications. It offers a rich set of developer experience features including real-time application inspection, component analysis, route visualization, performance monitoring, and debugging tools integrated seamlessly with Nuxt applications.
3

4
## Package Information
5

6
- **Package Name**: @nuxt/devtools
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @nuxt/devtools` (enabled by default in Nuxt 3.8.0+)
10

11
## Core Imports
12

13
```typescript
14
import type { ModuleOptions } from "@nuxt/devtools";
15
export default defineNuxtConfig({
16
  devtools: {
17
    enabled: true // or false to disable
18
  }
19
})
20
```
21

22
For runtime usage (auto-imported by default):
23

24
```typescript
25
// Auto-imported when devtools module is enabled
26
const devtools = useNuxtDevTools();
27

28
// Or explicit import from Nuxt's virtual imports
29
import { useNuxtDevTools } from "#imports";
30
```
31

32
For web components:
33

34
```typescript
35
import { NuxtDevtoolsFrame, NuxtDevtoolsInspectPanel } from "@nuxt/devtools/webcomponents";
36
```
37

38
For development toolkit extensions:
39

40
```typescript
41
import { addCustomTab, extendServerRpc, startSubprocess, onDevToolsInitialized } from "@nuxt/devtools-kit";
42
```
43

44
## Basic Usage
45

46
```typescript
47
// Enable devtools in nuxt.config.ts
48
export default defineNuxtConfig({
49
  devtools: {
50
    enabled: true,
51
    componentInspector: true,
52
    viteInspect: true,
53
    vscode: {
54
      enabled: true,
55
      port: 3080
56
    }
57
  }
58
})
59

60
// Use devtools client in runtime (auto-imported)
61
export default {
62
  setup() {
63
    const devtools = useNuxtDevTools();
64
    
65
    // devtools.value contains the client API when available
66
    if (devtools.value) {
67
      console.log('DevTools is available');
68
    }
69
  }
70
}
71
```
72

73
## Architecture
74

75
Nuxt DevTools is built around several key components:
76

77
- **Nuxt Module**: The main integration point that configures and initializes devtools
78
- **Client Interface**: Browser-based UI with keyboard shortcuts for developer interaction  
79
- **Server RPC**: Communication layer between client and server for real-time data
80
- **Web Components**: Standalone components for embedding devtools UI
81
- **DevTools Kit**: Extension API for adding custom functionality
82
- **Integration Layer**: Connections with Vite, VS Code, and Vue DevTools
83

84
## Capabilities
85

86
### Module Configuration
87

88
Core Nuxt module that integrates devtools into applications with extensive configuration options for development workflow customization.
89

90
```typescript { .api }
91
export default defineNuxtModule<ModuleOptions>;
92

93
interface ModuleOptions {
94
  enabled?: boolean | undefined;
95
  componentInspector?: boolean;
96
  viteInspect?: boolean;
97
  vscode?: VSCodeOptions;
98
  disableAuthorization?: boolean;
99
}
100

101
interface VSCodeOptions {
102
  enabled?: boolean;
103
  startOnBoot?: boolean;
104
  port?: number;
105
  reuseExistingServer?: boolean;
106
}
107
```
108

109
[Module Configuration](./module-configuration.md)
110

111
### Runtime Composables
112

113
Runtime utilities for accessing devtools functionality within Nuxt applications during development.
114

115
```typescript { .api }
116
function useNuxtDevTools(): Ref<NuxtDevtoolsHostClient | undefined>;
117

118
interface NuxtDevtoolsHostClient {
119
  // RPC methods for communication with devtools
120
  [key: string]: any;
121
}
122
```
123

124
[Runtime Composables](./runtime-composables.md)
125

126
### Web Components
127

128
Standalone Vue custom elements for embedding devtools UI components directly into web applications.
129

130
```typescript { .api }
131
const NuxtDevtoolsFrame: VueElementConstructor;
132
const NuxtDevtoolsInspectPanel: VueElementConstructor;
133

134
interface NuxtDevToolsInspectorProps {
135
  matched?: ElementTraceInfo;
136
  hasParent?: boolean;
137
  mouse: { x: number; y: number };
138
}
139
```
140

141
[Web Components](./web-components.md)
142

143
### DevTools Kit Extensions
144

145
Developer toolkit for extending devtools with custom tabs, RPC functions, terminals, and initialization hooks.
146

147
```typescript { .api }
148
function addCustomTab(
149
  tab: ModuleCustomTab | (() => ModuleCustomTab | Promise<ModuleCustomTab>),
150
  nuxt?: Nuxt
151
): void;
152

153
function extendServerRpc<ClientFunctions, ServerFunctions>(
154
  namespace: string,
155
  functions: ServerFunctions,
156
  nuxt?: Nuxt
157
): BirpcGroup<ClientFunctions, ServerFunctions>;
158

159
function startSubprocess(
160
  execaOptions: SubprocessOptions,
161
  tabOptions: TerminalState,
162
  nuxt?: Nuxt
163
): SubprocessController;
164

165
function onDevToolsInitialized(
166
  fn: (info: NuxtDevtoolsInfo) => void,
167
  nuxt?: Nuxt
168
): void;
169
```
170

171
[DevTools Kit Extensions](./devtools-kit-extensions.md)
172

173
### NPM Package Management
174

175
Utilities for managing NPM packages and checking for updates.
176

177
```typescript { .api }
178
/**
179
 * Get the main package.json of the project
180
 * @param nuxt - Nuxt instance (optional)
181
 * @returns Promise resolving to package.json content
182
 */
183
function getMainPackageJSON(nuxt?: Nuxt): Promise<PackageJson>;
184

185
/**
186
 * Check for updates of a specific package
187
 * @param name - Package name to check
188
 * @param current - Current version (optional)
189
 * @param nuxt - Nuxt instance (optional)
190
 * @returns Promise resolving to update information or undefined
191
 */
192
function checkForUpdateOf(
193
  name: string, 
194
  current?: string, 
195
  nuxt?: Nuxt
196
): Promise<PackageUpdateInfo | undefined>;
197
```
198

199
## Types
200

201
### Core DevTools Client Types
202

203
```typescript { .api }
204
interface NuxtDevtoolsHostClient {
205
  nuxt: NuxtApp;
206
  hooks: Hookable<NuxtDevtoolsClientHooks>;
207
  getIframe: () => HTMLIFrameElement | undefined;
208
  inspector?: {
209
    enable: () => void;
210
    disable: () => void;
211
    toggle: () => void;
212
    isEnabled: Ref<boolean>;
213
    isAvailable: Ref<boolean>;
214
  };
215
  devtools: {
216
    close: () => void;
217
    open: () => void;
218
    toggle: () => void;
219
    reload: () => void;
220
    navigate: (path: string) => void;
221
    popup?: () => any;
222
  };
223
  app: {
224
    reload: () => void;
225
    navigate: (path: string, hard?: boolean) => void;
226
    appConfig: AppConfig;
227
    colorMode: Ref<'dark' | 'light'>;
228
    frameState: Ref<DevToolsFrameState>;
229
    $fetch: $Fetch;
230
  };
231
  metrics: {
232
    clientHooks: () => HookInfo[];
233
    clientPlugins: () => PluginMetric[] | undefined;
234
    clientTimeline: () => TimelineMetrics | undefined;
235
    loading: () => LoadingTimeMetric;
236
  };
237
  revision: Ref<number>;
238
  syncClient: () => NuxtDevtoolsHostClient;
239
}
240

241
interface NuxtDevtoolsIframeClient {
242
  host: NuxtDevtoolsHostClient;
243
  devtools: NuxtDevtoolsClient;
244
}
245

246
interface NuxtDevtoolsClient {
247
  rpc: BirpcReturn<ServerFunctions, ClientFunctions>;
248
  renderCodeHighlight: (code: string, lang?: BuiltinLanguage, options?: CodeHighlightOptions) => {
249
    code: string;
250
    supported: boolean;
251
  };
252
  renderMarkdown: (markdown: string) => string;
253
  colorMode: string;
254
  extendClientRpc: <ServerFunctions = Record<string, never>, ClientFunctions = Record<string, never>>(name: string, functions: ClientFunctions) => BirpcReturn<ServerFunctions, ClientFunctions>;
255
}
256

257
interface DevToolsFrameState {
258
  width: number;
259
  height: number;
260
  top: number;
261
  left: number;
262
  open: boolean;
263
  route: string;
264
  position: 'left' | 'right' | 'bottom' | 'top';
265
  closeOnOutsideClick: boolean;
266
  minimizePanelInactive: number;
267
}
268

269
interface NuxtDevtoolsClientHooks {
270
  'devtools:navigate': (path: string) => void;
271
  'host:inspector:click': (path: string) => void;
272
  'host:inspector:close': () => void;
273
  'host:update:reactivity': () => void;
274
  'host:action:navigate': (path: string) => void;
275
  'host:action:reload': () => void;
276
}
277
```
278

279
### RPC Communication Types
280

281
```typescript { .api }
282
interface ServerFunctions {
283
  // Static RPCs
284
  getServerConfig: () => NuxtOptions;
285
  getServerDebugContext: () => Promise<ServerDebugContext | undefined>;
286
  getServerData: (token: string) => Promise<NuxtServerData>;
287
  getServerRuntimeConfig: () => Record<string, any>;
288
  getModuleOptions: () => ModuleOptions;
289
  getComponents: () => Component[];
290
  getComponentsRelationships: () => Promise<ComponentRelationship[]>;
291
  getAutoImports: () => AutoImportsWithMetadata;
292
  getServerPages: () => NuxtPage[];
293
  getCustomTabs: () => ModuleCustomTab[];
294
  getServerHooks: () => HookInfo[];
295
  getServerLayouts: () => NuxtLayout[];
296
  getStaticAssets: () => Promise<AssetInfo[]>;
297
  getServerRoutes: () => ServerRouteInfo[];
298
  getServerTasks: () => ScannedNitroTasks | null;
299
  getServerApp: () => NuxtApp | undefined;
300

301
  // Options
302
  getOptions: <T extends keyof NuxtDevToolsOptions>(tab: T) => Promise<NuxtDevToolsOptions[T]>;
303
  updateOptions: <T extends keyof NuxtDevToolsOptions>(tab: T, settings: Partial<NuxtDevToolsOptions[T]>) => Promise<void>;
304
  clearOptions: () => Promise<void>;
305

306
  // Updates & NPM
307
  checkForUpdateFor: (name: string) => Promise<PackageUpdateInfo | undefined>;
308
  getNpmCommand: (command: NpmCommandType, packageName: string, options?: NpmCommandOptions) => Promise<string[] | undefined>;
309
  runNpmCommand: (token: string, command: NpmCommandType, packageName: string, options?: NpmCommandOptions) => Promise<{ processId: string } | undefined>;
310

311
  // Terminal
312
  getTerminals: () => TerminalInfo[];
313
  getTerminalDetail: (token: string, id: string) => Promise<TerminalInfo | undefined>;
314
  runTerminalAction: (token: string, id: string, action: TerminalAction) => Promise<boolean>;
315

316
  // Storage
317
  getStorageMounts: () => Promise<StorageMounts>;
318
  getStorageKeys: (base?: string) => Promise<string[]>;
319
  getStorageItem: (token: string, key: string) => Promise<StorageValue>;
320
  setStorageItem: (token: string, key: string, value: StorageValue) => Promise<void>;
321
  removeStorageItem: (token: string, key: string) => Promise<void>;
322

323
  // Actions
324
  telemetryEvent: (payload: object, immediate?: boolean) => void;
325
  customTabAction: (name: string, action: number) => Promise<boolean>;
326
  runWizard: <T extends WizardActions>(token: string, name: T, ...args: GetWizardArgs<T>) => Promise<void>;
327
  openInEditor: (filepath: string) => Promise<boolean>;
328
  restartNuxt: (token: string, hard?: boolean) => Promise<void>;
329
  installNuxtModule: (token: string, name: string, dry?: boolean) => Promise<InstallModuleReturn>;
330
  uninstallNuxtModule: (token: string, name: string, dry?: boolean) => Promise<InstallModuleReturn>;
331
  enableTimeline: (dry: boolean) => Promise<[string, string]>;
332

333
  // Dev Token
334
  requestForAuth: (info?: string, origin?: string) => Promise<void>;
335
  verifyAuthToken: (token: string) => Promise<boolean>;
336
}
337

338
interface ClientFunctions {
339
  refresh: (event: ClientUpdateEvent) => void;
340
  callHook: (hook: string, ...args: any[]) => Promise<void>;
341
  navigateTo: (path: string) => void;
342
  onTerminalData: (_: { id: string, data: string }) => void;
343
  onTerminalExit: (_: { id: string, code?: number }) => void;
344
}
345

346
type ClientUpdateEvent = keyof ServerFunctions;
347
```
348

349
### Package Management Types
350

351
```typescript { .api }
352
interface PackageUpdateInfo {
353
  name: string;
354
  current: string;
355
  latest: string;
356
  needsUpdate: boolean;
357
}
358

359
type PackageManagerName = 'npm' | 'yarn' | 'pnpm' | 'bun';
360
type NpmCommandType = 'install' | 'uninstall' | 'update';
361

362
interface NpmCommandOptions {
363
  dev?: boolean;
364
  global?: boolean;
365
}
366
```
367

368
### Asset and Component Types
369

370
```typescript { .api }
371
interface AssetInfo {
372
  path: string;
373
  type: AssetType;
374
  publicPath: string;
375
  filePath: string;
376
  size: number;
377
  mtime: number;
378
  layer?: string;
379
}
380

381
type AssetType = 'image' | 'font' | 'video' | 'audio' | 'text' | 'json' | 'other';
382

383
interface ComponentRelationship {
384
  id: string;
385
  deps: string[];
386
}
387

388
interface ElementTraceInfo {
389
  file?: string;
390
  line?: number;
391
  column?: number;
392
  name?: string;
393
  [key: string]: any;
394
}
395
```