0
# Svelte Inspector Plugin
1

2
Development-time debugging tool that provides interactive inspection of Svelte components in the browser. The inspector allows developers to visually select DOM elements and jump directly to the corresponding Svelte component source code in their editor.
3

4
## Capabilities
5

6
### Inspector Plugin Factory
7

8
Creates a standalone Vite plugin for Svelte component inspection during development.
9

10
```typescript { .api }
11
/**
12
 * Creates a Vite plugin for Svelte component inspection
13
 * @param options - Optional inspector configuration options
14
 * @returns Vite plugin for development-time component inspection
15
 */
16
function svelteInspector(options?: Partial<Options>): Plugin;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
// Standalone usage (independent of main svelte plugin)
23
import { defineConfig } from 'vite';
24
import { svelteInspector } from '@sveltejs/vite-plugin-svelte-inspector';
25

26
export default defineConfig({
27
  plugins: [
28
    // Other plugins...
29
    svelteInspector({
30
      toggleKeyCombo: 'control-shift',
31
      holdMode: true,
32
      showToggleButton: 'always'
33
    })
34
  ]
35
});
36

37
// Basic usage with defaults
38
export default defineConfig({
39
  plugins: [
40
    svelteInspector() // Uses default options
41
  ]
42
});
43

44
// Integration with main svelte plugin
45
import { svelte } from '@sveltejs/vite-plugin-svelte';
46

47
export default defineConfig({
48
  plugins: [
49
    svelte({
50
      inspector: {
51
        toggleKeyCombo: 'alt-x',
52
        holdMode: false,
53
        showToggleButton: 'active'
54
      }
55
    })
56
  ]
57
});
58
```
59

60
## Inspector Options
61

62
### Toggle and Navigation Options
63

64
Configure how users activate and navigate the inspector.
65

66
```typescript { .api }
67
interface ToggleOptions {
68
  /** 
69
   * Key combination to toggle inspector
70
   * @default 'alt-x'
71
   * 
72
   * Format: any number of modifiers (control, shift, alt, meta) 
73
   * followed by zero or one regular key, separated by -
74
   * Examples: 'control-shift', 'control-o', 'control-alt-s', 'meta-x'
75
   */
76
  toggleKeyCombo?: string;
77

78
  /** 
79
   * Key to open the editor for the currently selected DOM node
80
   * @default 'Enter'
81
   */
82
  openKey?: string;
83

84
  /** 
85
   * Keys to close the inspector
86
   * @default ['Backspace', 'Escape']
87
   */
88
  escapeKeys?: string[];
89

90
  /** 
91
   * Inspector automatically disables when releasing toggleKeyCombo after holding
92
   * @default true
93
   */
94
  holdMode?: boolean;
95
}
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
svelteInspector({
102
  // Modifier-only combination (recommended to avoid conflicts)
103
  toggleKeyCombo: 'control-shift',
104
  
105
  // Custom navigation keys
106
  openKey: 'Space',
107
  escapeKeys: ['Escape', 'q'],
108
  
109
  // Disable hold mode for persistent inspector
110
  holdMode: false
111
});
112

113
// Accessibility-friendly configuration
114
svelteInspector({
115
  toggleKeyCombo: 'control-alt-i',
116
  navKeys: {
117
    parent: 'w',    // Instead of ArrowUp
118
    prev: 'a',      // Instead of ArrowLeft  
119
    child: 's',     // Instead of ArrowDown
120
    next: 'd'       // Instead of ArrowRight
121
  }
122
});
123
```
124

125
### Keyboard Navigation Options
126

127
Define keys for selecting elements via keyboard navigation.
128

129
```typescript { .api }
130
interface NavigationOptions {
131
  /** 
132
   * Keys to select elements with via keyboard
133
   * @default { parent: 'ArrowUp', child: 'ArrowDown', next: 'ArrowRight', prev: 'ArrowLeft' }
134
   * 
135
   * Improves accessibility and helps select elements without hoverable surface area
136
   */
137
  navKeys?: {
138
    /** Select closest parent element */
139
    parent: string;
140
    /** Select first child (or grandchild) element */
141
    child: string;
142
    /** Select next sibling (or parent if no next sibling) */
143
    next: string;
144
    /** Select previous sibling (or parent if no previous sibling) */
145
    prev: string;
146
  };
147
}
148
```
149

150
**Usage Examples:**
151

152
```javascript
153
// Default arrow key navigation
154
svelteInspector({
155
  navKeys: {
156
    parent: 'ArrowUp',
157
    child: 'ArrowDown', 
158
    next: 'ArrowRight',
159
    prev: 'ArrowLeft'
160
  }
161
});
162

163
// Custom navigation for screen reader users
164
svelteInspector({
165
  navKeys: {
166
    parent: 'w',
167
    prev: 'a', 
168
    child: 's',
169
    next: 'd'
170
  }
171
});
172

173
// VI-style navigation
174
svelteInspector({
175
  navKeys: {
176
    parent: 'k',    // up
177
    child: 'j',     // down
178
    prev: 'h',      // left
179
    next: 'l'       // right
180
  }
181
});
182
```
183

184
### UI Display Options
185

186
Control the inspector's visual interface and toggle button behavior.
187

188
```typescript { .api }
189
interface UIOptions {
190
  /** 
191
   * When to show the toggle button
192
   * @default 'active'
193
   */
194
  showToggleButton?: 'always' | 'active' | 'never';
195

196
  /** 
197
   * Where to display the toggle button
198
   * @default 'top-right'
199
   */
200
  toggleButtonPos?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
201

202
  /** 
203
   * Inject custom styles when inspector is active
204
   */
205
  customStyles?: boolean;
206
}
207
```
208

209
**Usage Examples:**
210

211
```javascript
212
// Always show toggle button in bottom-left
213
svelteInspector({
214
  showToggleButton: 'always',
215
  toggleButtonPos: 'bottom-left'
216
});
217

218
// Minimal UI - no toggle button
219
svelteInspector({
220
  showToggleButton: 'never'
221
});
222

223
// Custom styling enabled
224
svelteInspector({
225
  customStyles: true,
226
  showToggleButton: 'active',
227
  toggleButtonPos: 'top-left'
228
});
229
```
230

231
## Complete Options Interface
232

233
```typescript { .api }
234
interface Options {
235
  /** Key combo to toggle inspector (default: 'alt-x') */
236
  toggleKeyCombo?: string;
237
  /** Keyboard navigation keys */
238
  navKeys?: {
239
    parent: string;
240
    child: string;
241
    next: string;
242
    prev: string;
243
  };
244
  /** Key to open editor for selected node (default: 'Enter') */
245
  openKey?: string;
246
  /** Keys to close inspector (default: ['Backspace', 'Escape']) */
247
  escapeKeys?: string[];
248
  /** Auto-disable on key release after hold (default: true) */
249
  holdMode?: boolean;
250
  /** When to show toggle button (default: 'active') */
251
  showToggleButton?: 'always' | 'active' | 'never';
252
  /** Toggle button position (default: 'top-right') */
253
  toggleButtonPos?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
254
  /** Inject custom styles when active */
255
  customStyles?: boolean;
256
  /** Internal options (automatically set, not for user configuration) */
257
  __internal?: {
258
    base: string;
259
  };
260
}
261
```
262

263
## Usage Patterns
264

265
### Environment-Based Configuration
266

267
Configure inspector behavior based on development environment.
268

269
```javascript
270
// Environment variable control
271
const isDev = process.env.NODE_ENV === 'development';
272
const enableInspector = process.env.SVELTE_INSPECTOR !== 'false';
273

274
export default defineConfig({
275
  plugins: [
276
    svelte({
277
      inspector: isDev && enableInspector ? {
278
        toggleKeyCombo: 'control-shift',
279
        showToggleButton: 'always'
280
      } : false
281
    })
282
  ]
283
});
284

285
// Conditional inspector loading
286
export default defineConfig({
287
  plugins: [
288
    svelte(),
289
    ...(isDev ? [svelteInspector()] : [])
290
  ]
291
});
292
```
293

294
### Team Development Configuration
295

296
Standardize inspector settings across development teams.
297

298
```javascript
299
// shared-config.js
300
export const inspectorConfig = {
301
  toggleKeyCombo: 'control-alt-i',
302
  holdMode: false,
303
  showToggleButton: 'always',
304
  toggleButtonPos: 'bottom-right',
305
  navKeys: {
306
    parent: 'ArrowUp',
307
    child: 'ArrowDown',
308
    next: 'ArrowRight', 
309
    prev: 'ArrowLeft'
310
  }
311
};
312

313
// vite.config.js
314
import { inspectorConfig } from './shared-config.js';
315

316
export default defineConfig({
317
  plugins: [
318
    svelte({
319
      inspector: inspectorConfig
320
    })
321
  ]
322
});
323
```
324

325
### Integration with Editor Setup
326

327
Configure inspector to work with different code editors.
328

329
```javascript
330
// For VS Code users
331
svelteInspector({
332
  toggleKeyCombo: 'control-shift-i',  // Matches VS Code inspector
333
  openKey: 'F12',                     // Matches VS Code "Go to Definition"
334
  holdMode: true
335
});
336

337
// For Vim users  
338
svelteInspector({
339
  toggleKeyCombo: 'control-alt-i',
340
  navKeys: {
341
    parent: 'k',
342
    child: 'j', 
343
    prev: 'h',
344
    next: 'l'
345
  },
346
  openKey: 'Enter',
347
  escapeKeys: ['Escape', 'q']
348
});
349
```
350

351
## Error Handling and Debugging
352

353
The inspector plugin includes comprehensive error handling and debugging capabilities:
354

355
- **Environment Detection**: Automatically disables in production builds
356
- **Conflict Resolution**: Warns about key combination conflicts
357
- **File System Integration**: Handles editor opening errors gracefully  
358
- **Browser Compatibility**: Works across modern browsers with fallbacks
359

360
Enable debug logging to troubleshoot inspector issues:
361

362
```bash
363
DEBUG=vite-plugin-svelte-inspector:* npm run dev
364
```