0
# Error Overlay System
1

2
Comprehensive error overlay system for development mode providing real-time visual feedback for checker results with customizable appearance and behavior.
3

4
## Capabilities
5

6
### Overlay Configuration
7

8
Configure the development error overlay system with extensive customization options for appearance and behavior.
9

10
```typescript { .api }
11
interface SharedConfig {
12
  /**
13
   * Show overlay on UI view when there are errors or warnings in dev mode
14
   * @default true
15
   */
16
  overlay: boolean | OverlayConfig;
17
}
18

19
interface OverlayConfig {
20
  /**
21
   * Set true if you want the overlay to default to being open if errors/warnings are found
22
   * @default true
23
   */
24
  initialIsOpen?: boolean | 'error';
25
  
26
  /**
27
   * Position of the vite-plugin-checker badge to open and close the diagnostics panel
28
   * @default 'bl'
29
   */
30
  position?: 'tl' | 'tr' | 'bl' | 'br';
31
  
32
  /**
33
   * Extra style string for the badge button (CSS property format)
34
   * Example: 'display: none;' to hide the badge
35
   */
36
  badgeStyle?: string;
37
  
38
  /**
39
   * Extra style string for the diagnostic panel (CSS property format)
40
   * Example: 'opacity: 0.8;' to change panel opacity
41
   */
42
  panelStyle?: string;
43
}
44
```
45

46
**Usage Examples:**
47

48
```typescript
49
// Basic overlay enable
50
checker({
51
  overlay: true,
52
});
53

54
// Custom overlay configuration
55
checker({
56
  overlay: {
57
    initialIsOpen: 'error', // Only auto-open for errors
58
    position: 'tr',         // Top-right position
59
    badgeStyle: 'right: 20px; top: 20px; z-index: 9999;',
60
    panelStyle: 'max-height: 80vh; opacity: 0.95;',
61
  },
62
});
63

64
// Disable overlay
65
checker({
66
  overlay: false,
67
});
68
```
69

70
### Initial Open Behavior
71

72
Control when the overlay automatically opens based on diagnostic severity:
73

74
```typescript { .api }
75
interface OverlayConfig {
76
  /**
77
   * Control automatic overlay opening behavior
78
   * - `true`: Open for both errors and warnings
79
   * - `false`: Never auto-open (manual toggle only)
80
   * - `'error'`: Only auto-open for errors, not warnings
81
   */
82
  initialIsOpen?: boolean | 'error';
83
}
84
```
85

86
**Behavior Examples:**
87

88
```typescript
89
// Always auto-open for any diagnostic
90
overlay: {
91
  initialIsOpen: true,
92
}
93

94
// Only auto-open for errors, not warnings
95
overlay: {
96
  initialIsOpen: 'error',
97
}
98

99
// Never auto-open, require manual interaction
100
overlay: {
101
  initialIsOpen: false,
102
}
103
```
104

105
### Badge Positioning
106

107
Configure the position and styling of the toggle badge that opens/closes the overlay:
108

109
```typescript { .api }
110
interface OverlayConfig {
111
  /**
112
   * Position of the checker badge
113
   * - 'tl': Top-left corner
114
   * - 'tr': Top-right corner  
115
   * - 'bl': Bottom-left corner (default)
116
   * - 'br': Bottom-right corner
117
   */
118
  position?: 'tl' | 'tr' | 'bl' | 'br';
119
}
120
```
121

122
**Position Examples:**
123

124
```typescript
125
// Top-right corner positioning
126
overlay: {
127
  position: 'tr',
128
}
129

130
// Bottom-left corner (default)
131
overlay: {
132
  position: 'bl',
133
}
134

135
// Custom positioning with styles
136
overlay: {
137
  position: 'tr',
138
  badgeStyle: 'top: 60px; right: 20px;', // Offset from navbar
139
}
140
```
141

142
### Custom Styling
143

144
Apply custom CSS styles to both the badge and the diagnostic panel:
145

146
```typescript { .api }
147
interface OverlayConfig {
148
  /**
149
   * Custom CSS styles for the badge button
150
   * Format: HTML element style property string
151
   */
152
  badgeStyle?: string;
153
  
154
  /**
155
   * Custom CSS styles for the diagnostic panel
156
   * Format: HTML element style property string
157
   */
158
  panelStyle?: string;
159
}
160
```
161

162
**Styling Examples:**
163

164
```typescript
165
// Custom badge styling
166
overlay: {
167
  badgeStyle: `
168
    background: linear-gradient(45deg, #ff6b6b, #feca57);
169
    border-radius: 50%;
170
    box-shadow: 0 4px 8px rgba(0,0,0,0.2);
171
    font-weight: bold;
172
  `,
173
}
174

175
// Custom panel styling
176
overlay: {
177
  panelStyle: `
178
    background: rgba(0, 0, 0, 0.9);
179
    backdrop-filter: blur(10px);
180
    border-radius: 12px;
181
    border: 1px solid rgba(255, 255, 255, 0.1);
182
    max-height: 70vh;
183
    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
184
  `,
185
}
186

187
// Hide badge but keep functionality (keyboard shortcut still works)
188
overlay: {
189
  badgeStyle: 'display: none;',
190
}
191

192
// Minimal panel styling
193
overlay: {
194
  panelStyle: 'max-width: 800px; font-size: 14px;',
195
}
196
```
197

198
### Diagnostic Display
199

200
The overlay displays comprehensive diagnostic information from all enabled checkers:
201

202
```typescript { .api }
203
interface DiagnosticToRuntime {
204
  /** Identifier of the checker that generated the diagnostic */
205
  checkerId: string;
206
  
207
  /** Severity level of the diagnostic */
208
  level?: DiagnosticLevel;
209
  
210
  /** Error message */
211
  message?: string;
212
  
213
  /** Stack trace information */
214
  stack?: string;
215
  
216
  /** Source location information */
217
  loc?: {
218
    file?: string;
219
    line?: number;
220
    column?: number;
221
  };
222
  
223
  /** Code frame showing the problematic code */
224
  frame?: string;
225
}
226

227
enum DiagnosticLevel {
228
  Warning = 0,
229
  Error = 1,
230
  Suggestion = 2,  
231
  Message = 3,
232
}
233
```
234

235
### WebSocket Communication
236

237
The overlay system uses Vite's WebSocket connection for real-time updates:
238

239
```typescript { .api }
240
interface ClientDiagnosticPayload {
241
  event: 'vite-plugin-checker:error';
242
  data: {
243
    checkerId: string;
244
    diagnostics: DiagnosticToRuntime[];
245
  };
246
}
247

248
interface ClientReconnectPayload {
249
  event: 'vite-plugin-checker:reconnect';
250
  data: ClientDiagnosticPayload[];
251
}
252
```
253

254
### Interactive Features
255

256
The overlay provides several interactive features:
257

258
**Badge Interaction:**
259
- Click to toggle overlay open/closed
260
- Shows diagnostic count when closed
261
- Visual indicators for error/warning states
262
- Hover effects and animations
263

264
**Panel Interaction:**  
265
- Scroll through multiple diagnostics
266
- Click on file locations to open in editor (IDE integration)
267
- Expand/collapse diagnostic details
268
- Filter by checker type or severity level
269

270
**Keyboard Shortcuts:**
271
- `Escape`: Close overlay
272
- `Arrow Keys`: Navigate between diagnostics
273
- `Enter`: Jump to error location (with IDE integration)
274

275
### Integration Examples
276

277
**React Development Setup:**
278
```typescript
279
checker({
280
  typescript: true,
281
  eslint: {
282
    lintCommand: 'eslint "./src/**/*.{ts,tsx}"',
283
  },
284
  overlay: {
285
    initialIsOpen: 'error',
286
    position: 'br',
287
    badgeStyle: 'bottom: 80px; right: 20px;', // Above dev tools
288
    panelStyle: 'max-height: 60vh; font-family: "JetBrains Mono", monospace;',
289
  },
290
});
291
```
292

293
**Vue Development Setup:**
294
```typescript
295
checker({
296
  vueTsc: true,
297
  vls: true,
298
  eslint: {
299
    lintCommand: 'eslint "./src/**/*.{ts,vue}"',
300
  },
301
  overlay: {
302
    initialIsOpen: true,
303
    position: 'tl',
304
    panelStyle: `
305
      background: rgba(18, 18, 18, 0.95);
306
      border: 1px solid #42b883;
307
      border-radius: 8px;
308
      color: #e8e8e8;
309
    `,
310
  },
311
});
312
```
313

314
**Minimal Overlay Setup:**
315
```typescript
316
checker({
317
  typescript: true,
318
  overlay: {
319
    initialIsOpen: false,
320
    badgeStyle: 'opacity: 0.7; font-size: 12px;',
321
    panelStyle: 'max-height: 40vh;',
322
  },
323
});
324
```
325

326
### Advanced Customization
327

328
**Custom Theme Integration:**
329
```typescript
330
// Dark theme overlay
331
overlay: {
332
  badgeStyle: `
333
    background: #1a1a1a;
334
    border: 1px solid #333;
335
    color: #fff;
336
  `,
337
  panelStyle: `
338
    background: linear-gradient(135deg, #1a1a1a 0%, #2d2d2d 100%);
339
    border: 1px solid #444;
340
    color: #e8e8e8;
341
    font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
342
  `,
343
}
344

345
// Light theme overlay  
346
overlay: {
347
  badgeStyle: `
348
    background: #f8f9fa;
349
    border: 1px solid #dee2e6;
350
    color: #495057;
351
    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
352
  `,
353
  panelStyle: `
354
    background: #ffffff;
355
    border: 1px solid #e9ecef;
356
    color: #495057;
357
    box-shadow: 0 4px 12px rgba(0,0,0,0.15);
358
  `,
359
}
360
```
361

362
**Production-Ready Configuration:**
363
```typescript
364
checker({
365
  typescript: true,
366
  eslint: { lintCommand: 'eslint "./src/**/*.ts"' },
367
  overlay: process.env.NODE_ENV === 'development' ? {
368
    initialIsOpen: 'error',
369
    position: 'br',
370
    badgeStyle: 'bottom: 20px; right: 20px; z-index: 1000;',
371
    panelStyle: 'max-height: 50vh; max-width: 90vw;',
372
  } : false, // Disable in production
373
});
374
```
375

376
### Troubleshooting
377

378
**Overlay not appearing:**
379
- Ensure `overlay: true` is set in configuration
380
- Check browser console for WebSocket connection errors
381
- Verify Vite development server is running properly
382

383
**Badge not visible:**
384
- Check if `badgeStyle` includes `display: none`
385
- Verify z-index values don't conflict with other elements
386
- Ensure position coordinates place badge within viewport
387

388
**Panel styling issues:**
389
- Use browser dev tools to inspect overlay elements
390
- Test CSS syntax in `panelStyle` separately
391
- Consider viewport size when setting max-height/max-width
392

393
**WebSocket connection problems:**
394
- Check if other Vite features (HMR) are working
395
- Verify no firewall blocking WebSocket connections
396
- Check browser network tab for WebSocket messages