0
# Configuration
1

2
Configuration options for controlling vite-plugin-inspect behavior, filtering, and output settings.
3

4
## Capabilities
5

6
### Main Plugin Function
7

8
Creates a configured Vite plugin instance with inspection capabilities.
9

10
```typescript { .api }
11
/**
12
 * Creates a Vite plugin for inspecting plugin transformations
13
 * @param options - Configuration options for the plugin
14
 * @returns Configured Vite plugin instance
15
 */
16
function Inspect(options?: ViteInspectOptions): Plugin;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { defineConfig } from 'vite';
23
import Inspect from 'vite-plugin-inspect';
24

25
// Basic usage with defaults
26
export default defineConfig({
27
  plugins: [
28
    Inspect()
29
  ],
30
});
31

32
// Development-only inspection
33
export default defineConfig({
34
  plugins: [
35
    Inspect({
36
      dev: true,
37
      build: false,
38
      silent: false
39
    })
40
  ],
41
});
42

43
// Build inspection with custom output
44
export default defineConfig({
45
  plugins: [
46
    Inspect({
47
      dev: false,
48
      build: true,
49
      outputDir: '.vite-inspect-build',
50
      open: true
51
    })
52
  ],
53
});
54
```
55

56
### Configuration Interface
57

58
Complete configuration options interface for the plugin.
59

60
```typescript { .api }
61
interface ViteInspectOptions {
62
  /** Enable the inspect plugin in dev mode (could be some performance overhead) @default true */
63
  dev?: boolean;
64
  /** Enable the inspect plugin in build mode, and output the report to `.vite-inspect` @default false */
65
  build?: boolean;
66
  /** @deprecated use `dev` or `build` option instead. */
67
  enabled?: boolean;
68
  /** Directory for build inspector UI output, only work in build mode @default '.vite-inspect' */
69
  outputDir?: string;
70
  /** Filter for modules to be inspected */
71
  include?: FilterPattern;
72
  /** Filter for modules to not be inspected */
73
  exclude?: FilterPattern;
74
  /** Base URL for inspector UI @default read from Vite's config */
75
  base?: string;
76
  /** Print URL output silently in the terminal @default false */
77
  silent?: boolean;
78
  /** Automatically open inspect page @default false */  
79
  open?: boolean;
80
  /** Remove version query `?v=xxx` and treat them as the same module @default true */
81
  removeVersionQuery?: boolean;
82
  /** Enable embedded mode @default false */
83
  embedded?: boolean;
84
}
85
```
86

87
### Filter Pattern Type
88

89
Type definition for include/exclude filtering patterns.
90

91
```typescript { .api }
92
/**
93
 * Pattern type for filtering modules by path or name
94
 * Can be string, regex, array of patterns, or null to disable filtering
95
 */
96
type FilterPattern = ReadonlyArray<string | RegExp> | string | RegExp | null;
97
```
98

99
**Usage Examples:**
100

101
```typescript
102
// String patterns
103
Inspect({
104
  include: "src/**/*.vue",
105
  exclude: "node_modules/**"
106
})
107

108
// Regex patterns  
109
Inspect({
110
  include: /\.(vue|tsx?)$/,
111
  exclude: /node_modules/
112
})
113

114
// Multiple patterns
115
Inspect({
116
  include: ["src/**/*.vue", "src/**/*.ts"],
117
  exclude: ["node_modules/**", "dist/**"]
118
})
119
```
120

121
### Mode Configuration
122

123
#### Development Mode
124

125
Enable inspection during development with real-time updates.
126

127
```typescript
128
Inspect({
129
  dev: true,        // Enable in dev mode
130
  build: false,     // Disable in build mode  
131
  silent: false,    // Show console messages
132
  open: false       // Don't auto-open browser
133
})
134
```
135

136
Features available in dev mode:
137
- Real-time module transformation tracking
138
- WebSocket-based updates
139
- Interactive web interface at `/__inspect/`
140
- Middleware performance monitoring
141

142
#### Build Mode  
143

144
Enable inspection during build with static report generation.
145

146
```typescript
147
Inspect({
148
  dev: false,
149
  build: true,
150
  outputDir: '.vite-inspect',
151
  open: true
152
})
153
```
154

155
Features available in build mode:
156
- Static HTML report generation
157
- Complete build-time transformation analysis
158
- Offline inspection capability
159
- Automatic browser opening (optional)
160

161
### Filtering Options
162

163
#### Include/Exclude Patterns
164

165
Control which modules are inspected using glob patterns or regular expressions.
166

167
```typescript
168
// Include only Vue and TypeScript files
169
Inspect({
170
  include: ["**/*.vue", "**/*.ts", "**/*.tsx"]
171
})
172

173
// Exclude node_modules and test files
174
Inspect({
175
  exclude: ["node_modules/**", "**/*.test.ts", "**/*.spec.ts"]
176
})
177

178
// Complex filtering
179
Inspect({
180
  include: /src\//,
181
  exclude: [/node_modules/, /\.test\./, /\.spec\./]
182
})
183
```
184

185
#### Version Query Handling
186

187
Configure how version queries in module URLs are handled.
188

189
```typescript
190
Inspect({
191
  removeVersionQuery: true  // Default: treat file.js?v=123 same as file.js
192
})
193
```
194

195
### UI Configuration
196

197
#### Base URL Configuration
198

199
Set custom base URL for the inspector interface.
200

201
```typescript
202
Inspect({
203
  base: '/my-app/',  // Inspector available at /my-app/__inspect/
204
})
205
```
206

207
#### Silent Mode
208

209
Control console output visibility.
210

211
```typescript
212
Inspect({
213
  silent: true  // Suppress URL and status messages
214
})
215
```
216

217
#### Auto-open Browser
218

219
Automatically open inspector in browser on startup.
220

221
```typescript
222
Inspect({
223
  open: true,  // Auto-open inspector page
224
  dev: true    // Only works in dev mode
225
})
226
```
227

228
#### Embedded Mode
229

230
Enable embedded mode for integration with other tools.
231

232
```typescript
233
Inspect({
234
  embedded: true  // Enable embedded mode
235
})
236
```