tessl/npm-vite-plugin-checker
Vite plugin that runs TypeScript type checker on a separate process.
—
Pending
error-overlay.mddocs/
Error Overlay System
Comprehensive error overlay system for development mode providing real-time visual feedback for checker results with customizable appearance and behavior.
Capabilities
Overlay Configuration
Configure the development error overlay system with extensive customization options for appearance and behavior.
interface SharedConfig {
/**
* Show overlay on UI view when there are errors or warnings in dev mode
* @default true
*/
overlay: boolean | OverlayConfig;
}
interface OverlayConfig {
/**
* Set true if you want the overlay to default to being open if errors/warnings are found
* @default true
*/
initialIsOpen?: boolean | 'error';
/**
* Position of the vite-plugin-checker badge to open and close the diagnostics panel
* @default 'bl'
*/
position?: 'tl' | 'tr' | 'bl' | 'br';
/**
* Extra style string for the badge button (CSS property format)
* Example: 'display: none;' to hide the badge
*/
badgeStyle?: string;
/**
* Extra style string for the diagnostic panel (CSS property format)
* Example: 'opacity: 0.8;' to change panel opacity
*/
panelStyle?: string;
}Usage Examples:
// Basic overlay enable
checker({
overlay: true,
});
// Custom overlay configuration
checker({
overlay: {
initialIsOpen: 'error', // Only auto-open for errors
position: 'tr', // Top-right position
badgeStyle: 'right: 20px; top: 20px; z-index: 9999;',
panelStyle: 'max-height: 80vh; opacity: 0.95;',
},
});
// Disable overlay
checker({
overlay: false,
});Initial Open Behavior
Control when the overlay automatically opens based on diagnostic severity:
interface OverlayConfig {
/**
* Control automatic overlay opening behavior
* - `true`: Open for both errors and warnings
* - `false`: Never auto-open (manual toggle only)
* - `'error'`: Only auto-open for errors, not warnings
*/
initialIsOpen?: boolean | 'error';
}Behavior Examples:
// Always auto-open for any diagnostic
overlay: {
initialIsOpen: true,
}
// Only auto-open for errors, not warnings
overlay: {
initialIsOpen: 'error',
}
// Never auto-open, require manual interaction
overlay: {
initialIsOpen: false,
}Badge Positioning
Configure the position and styling of the toggle badge that opens/closes the overlay:
interface OverlayConfig {
/**
* Position of the checker badge
* - 'tl': Top-left corner
* - 'tr': Top-right corner
* - 'bl': Bottom-left corner (default)
* - 'br': Bottom-right corner
*/
position?: 'tl' | 'tr' | 'bl' | 'br';
}Position Examples:
// Top-right corner positioning
overlay: {
position: 'tr',
}
// Bottom-left corner (default)
overlay: {
position: 'bl',
}
// Custom positioning with styles
overlay: {
position: 'tr',
badgeStyle: 'top: 60px; right: 20px;', // Offset from navbar
}Custom Styling
Apply custom CSS styles to both the badge and the diagnostic panel:
interface OverlayConfig {
/**
* Custom CSS styles for the badge button
* Format: HTML element style property string
*/
badgeStyle?: string;
/**
* Custom CSS styles for the diagnostic panel
* Format: HTML element style property string
*/
panelStyle?: string;
}Styling Examples:
// Custom badge styling
overlay: {
badgeStyle: `
background: linear-gradient(45deg, #ff6b6b, #feca57);
border-radius: 50%;
box-shadow: 0 4px 8px rgba(0,0,0,0.2);
font-weight: bold;
`,
}
// Custom panel styling
overlay: {
panelStyle: `
background: rgba(0, 0, 0, 0.9);
backdrop-filter: blur(10px);
border-radius: 12px;
border: 1px solid rgba(255, 255, 255, 0.1);
max-height: 70vh;
box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
`,
}
// Hide badge but keep functionality (keyboard shortcut still works)
overlay: {
badgeStyle: 'display: none;',
}
// Minimal panel styling
overlay: {
panelStyle: 'max-width: 800px; font-size: 14px;',
}Diagnostic Display
The overlay displays comprehensive diagnostic information from all enabled checkers:
interface DiagnosticToRuntime {
/** Identifier of the checker that generated the diagnostic */
checkerId: string;
/** Severity level of the diagnostic */
level?: DiagnosticLevel;
/** Error message */
message?: string;
/** Stack trace information */
stack?: string;
/** Source location information */
loc?: {
file?: string;
line?: number;
column?: number;
};
/** Code frame showing the problematic code */
frame?: string;
}
enum DiagnosticLevel {
Warning = 0,
Error = 1,
Suggestion = 2,
Message = 3,
}WebSocket Communication
The overlay system uses Vite's WebSocket connection for real-time updates:
interface ClientDiagnosticPayload {
event: 'vite-plugin-checker:error';
data: {
checkerId: string;
diagnostics: DiagnosticToRuntime[];
};
}
interface ClientReconnectPayload {
event: 'vite-plugin-checker:reconnect';
data: ClientDiagnosticPayload[];
}Interactive Features
The overlay provides several interactive features:
Badge Interaction:
- Click to toggle overlay open/closed
- Shows diagnostic count when closed
- Visual indicators for error/warning states
- Hover effects and animations
Panel Interaction:
- Scroll through multiple diagnostics
- Click on file locations to open in editor (IDE integration)
- Expand/collapse diagnostic details
- Filter by checker type or severity level
Keyboard Shortcuts:
Escape: Close overlayArrow Keys: Navigate between diagnosticsEnter: Jump to error location (with IDE integration)
Integration Examples
React Development Setup:
checker({
typescript: true,
eslint: {
lintCommand: 'eslint "./src/**/*.{ts,tsx}"',
},
overlay: {
initialIsOpen: 'error',
position: 'br',
badgeStyle: 'bottom: 80px; right: 20px;', // Above dev tools
panelStyle: 'max-height: 60vh; font-family: "JetBrains Mono", monospace;',
},
});Vue Development Setup:
checker({
vueTsc: true,
vls: true,
eslint: {
lintCommand: 'eslint "./src/**/*.{ts,vue}"',
},
overlay: {
initialIsOpen: true,
position: 'tl',
panelStyle: `
background: rgba(18, 18, 18, 0.95);
border: 1px solid #42b883;
border-radius: 8px;
color: #e8e8e8;
`,
},
});Minimal Overlay Setup:
checker({
typescript: true,
overlay: {
initialIsOpen: false,
badgeStyle: 'opacity: 0.7; font-size: 12px;',
panelStyle: 'max-height: 40vh;',
},
});Advanced Customization
Custom Theme Integration:
// Dark theme overlay
overlay: {
badgeStyle: `
background: #1a1a1a;
border: 1px solid #333;
color: #fff;
`,
panelStyle: `
background: linear-gradient(135deg, #1a1a1a 0%, #2d2d2d 100%);
border: 1px solid #444;
color: #e8e8e8;
font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
`,
}
// Light theme overlay
overlay: {
badgeStyle: `
background: #f8f9fa;
border: 1px solid #dee2e6;
color: #495057;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
`,
panelStyle: `
background: #ffffff;
border: 1px solid #e9ecef;
color: #495057;
box-shadow: 0 4px 12px rgba(0,0,0,0.15);
`,
}Production-Ready Configuration:
checker({
typescript: true,
eslint: { lintCommand: 'eslint "./src/**/*.ts"' },
overlay: process.env.NODE_ENV === 'development' ? {
initialIsOpen: 'error',
position: 'br',
badgeStyle: 'bottom: 20px; right: 20px; z-index: 1000;',
panelStyle: 'max-height: 50vh; max-width: 90vw;',
} : false, // Disable in production
});Troubleshooting
Overlay not appearing:
- Ensure
overlay: trueis set in configuration - Check browser console for WebSocket connection errors
- Verify Vite development server is running properly
Badge not visible:
- Check if
badgeStyleincludesdisplay: none - Verify z-index values don't conflict with other elements
- Ensure position coordinates place badge within viewport
Panel styling issues:
- Use browser dev tools to inspect overlay elements
- Test CSS syntax in
panelStyleseparately - Consider viewport size when setting max-height/max-width
WebSocket connection problems:
- Check if other Vite features (HMR) are working
- Verify no firewall blocking WebSocket connections
- Check browser network tab for WebSocket messages
Install with Tessl CLI
npx tessl i tessl/npm-vite-plugin-checker