0
# Vite Plugin Inspect
1

2
Vite Plugin Inspect is a development and debugging tool that provides comprehensive visualization and analysis of Vite plugin transformations. It offers a web-based interface for inspecting the intermediate states of modules during the Vite build process, helping developers understand how plugins transform code, debug transformation issues, and optimize build performance.
3

4
## Package Information
5

6
- **Package Name**: vite-plugin-inspect
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -D vite-plugin-inspect`
10

11
## Core Imports
12

13
```typescript
14
import Inspect from 'vite-plugin-inspect';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const Inspect = require('vite-plugin-inspect');
21
```
22

23
For Nuxt integration:
24

25
```typescript
26
import InspectModule from 'vite-plugin-inspect/nuxt';
27
```
28

29
## Basic Usage
30

31
```typescript
32
// vite.config.ts
33
import { defineConfig } from 'vite';
34
import Inspect from 'vite-plugin-inspect';
35

36
export default defineConfig({
37
  plugins: [
38
    Inspect({
39
      dev: true,        // Enable in dev mode
40
      build: false,     // Disable in build mode
41
      open: false,      // Don't auto-open browser
42
      silent: false     // Show console messages
43
    })
44
  ],
45
});
46
```
47

48
After starting dev server, visit `http://localhost:5173/__inspect/` to access the inspection interface.
49

50
## Architecture
51

52
Vite Plugin Inspect is built around several key components:
53

54
- **Main Plugin**: Core Vite plugin that intercepts and tracks transformations across all other plugins
55
- **Web Interface**: Browser-based UI for visualizing module transformations, dependencies, and performance metrics
56
- **RPC Server**: Real-time communication between the plugin and web interface using WebSocket
57
- **Context Management**: Tracks multiple Vite instances and environments with isolated data
58
- **Build Mode**: Static HTML generation for inspecting build-time transformations
59
- **Performance Tracking**: Middleware and plugin performance monitoring with detailed timing metrics
60

61
## Capabilities
62

63
### Plugin Configuration
64

65
Core configuration options for controlling inspection behavior, filtering, and output settings.
66

67
```typescript { .api }
68
function Inspect(options?: ViteInspectOptions): Plugin;
69

70
interface ViteInspectOptions {
71
  dev?: boolean;
72
  build?: boolean;
73
  outputDir?: string;
74
  include?: FilterPattern;
75
  exclude?: FilterPattern;
76
  base?: string;
77
  silent?: boolean;
78
  open?: boolean;
79
  removeVersionQuery?: boolean;
80
  embedded?: boolean;
81
}
82

83
type FilterPattern = ReadonlyArray<string | RegExp> | string | RegExp | null;
84
```
85

86
[Configuration](./configuration.md)
87

88
### Module Inspection
89

90
Access to detailed information about module transformations, dependencies, and plugin interactions.
91

92
```typescript { .api }
93
interface ModuleInfo {
94
  id: string;
95
  plugins: { name: string; transform?: number; resolveId?: number; }[];
96
  deps: string[];
97
  importers: string[];
98
  virtual: boolean;
99
  totalTime: number;
100
  invokeCount: number;
101
  sourceSize: number;
102
  distSize: number;
103
}
104

105
interface ModuleTransformInfo {
106
  resolvedId: string;
107
  transforms: TransformInfo[];
108
}
109

110
interface TransformInfo {
111
  name: string;
112
  result?: string;
113
  start: number;
114
  end: number;
115
  order?: string;
116
  sourcemaps?: any;
117
  error?: ParsedError;
118
}
119
```
120

121
[Module Inspection](./module-inspection.md)
122

123
### Performance Metrics
124

125
Plugin and server performance monitoring with detailed timing and invocation data.
126

127
```typescript { .api }
128
interface PluginMetricInfo {
129
  name: string;
130
  enforce?: string;
131
  transform: {
132
    invokeCount: number;
133
    totalTime: number;
134
  };
135
  resolveId: {
136
    invokeCount: number;
137
    totalTime: number;
138
  };
139
}
140

141
interface ServerMetrics {
142
  middleware?: Record<string, { name: string; self: number; total: number; }[]>;
143
}
144
```
145

146
[Performance Metrics](./performance-metrics.md)
147

148
### Programmatic API
149

150
RPC functions for programmatic access to inspection data from external tools.
151

152
```typescript { .api }
153
interface ViteInspectAPI {
154
  rpc: RpcFunctions;
155
}
156

157
interface RpcFunctions {
158
  getMetadata(): Promise<Metadata>;
159
  getModulesList(query: QueryEnv): Promise<ModulesList>;
160
  getModuleTransformInfo(query: QueryEnv, id: string, clear?: boolean): Promise<ModuleTransformInfo>;
161
  getPluginMetrics(query: QueryEnv): Promise<PluginMetricInfo[]>;
162
  getServerMetrics(query: QueryEnv): Promise<ServerMetrics>;
163
  resolveId(query: QueryEnv, id: string): Promise<string>;
164
  onModuleUpdated(): Promise<void>;
165
}
166
```
167

168
[Programmatic API](./programmatic-api.md)
169

170
### Nuxt Integration
171

172
Dedicated Nuxt.js module for seamless integration with Nuxt projects.
173

174
```typescript { .api }
175
interface ModuleOptions extends ViteInspectOptions {}
176

177
function defineNuxtModule<T>(options: ModuleOptions): NuxtModule<T>;
178
```
179

180
[Nuxt Integration](./nuxt-integration.md)
181

182
## Types
183

184
```typescript { .api }
185
interface QueryEnv {
186
  vite: string;  // Vite instance ID
187
  env: string;   // Environment name
188
}
189

190
interface QueryId extends QueryEnv {
191
  id: string;    // Module ID
192
}
193

194
interface ParsedError {
195
  message: string;
196
  stack: StackFrame[];
197
  raw?: any;
198
}
199

200
interface ResolveIdInfo {
201
  name: string;
202
  result: string;
203
  start: number;
204
  end: number;
205
  order?: string;
206
  error?: ParsedError;
207
}
208

209
interface InstanceInfo {
210
  root: string;
211
  vite: string;                    // Vite instance ID
212
  environments: string[];          // Environment names
213
  plugins: SerializedPlugin[];     // Plugins
214
  environmentPlugins: Record<string, number[]>; // Environment plugin indices
215
}
216

217
interface Metadata {
218
  instances: InstanceInfo[];
219
  embedded?: boolean;
220
}
221

222
interface SerializedPlugin {
223
  name: string;
224
  enforce?: string;
225
  resolveId: string;
226
  load: string;
227
  transform: string;
228
  generateBundle: string;
229
  handleHotUpdate: string;
230
  api: string;
231
}
232
```