dev experience
This commit is contained in:
300
apps/website/docs/DEVELOPER_EXPERIENCE.md
Normal file
300
apps/website/docs/DEVELOPER_EXPERIENCE.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# Developer Experience Enhancement - Maximum Transparency
|
||||
|
||||
This document describes the enhanced developer experience features added to the GridPilot website for maximum transparency in development environments.
|
||||
|
||||
## Overview
|
||||
|
||||
The enhanced developer experience provides comprehensive error handling, logging, monitoring, and replay capabilities specifically designed for development environments. All features are automatically disabled in production unless explicitly enabled.
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Global Error Handler (`GlobalErrorHandler`)
|
||||
|
||||
**Location:** `lib/infrastructure/GlobalErrorHandler.ts`
|
||||
|
||||
**Features:**
|
||||
- Captures all uncaught JavaScript errors
|
||||
- Handles unhandled promise rejections
|
||||
- Overrides console.error for framework errors
|
||||
- Enhanced stack traces with source map information
|
||||
- Detailed error overlays in development
|
||||
- Maximum logging verbosity in development
|
||||
|
||||
**Usage:**
|
||||
```typescript
|
||||
import { getGlobalErrorHandler } from '@/lib/infrastructure/GlobalErrorHandler';
|
||||
|
||||
const handler = getGlobalErrorHandler();
|
||||
handler.report(error, { customContext: 'value' });
|
||||
```
|
||||
|
||||
**Dev Overlay:**
|
||||
- Shows when uncaught errors occur
|
||||
- Displays error type, message, stack trace
|
||||
- Shows environment information
|
||||
- Provides quick actions (copy, reload, log)
|
||||
- Dismissible with ESC or ENTER
|
||||
|
||||
### 2. Enhanced React Error Boundary
|
||||
|
||||
**Location:** `components/errors/EnhancedErrorBoundary.tsx`
|
||||
|
||||
**Features:**
|
||||
- Wraps React components with error handling
|
||||
- Integrates with global error handler
|
||||
- Shows React-specific error overlays
|
||||
- Captures component stack traces
|
||||
- Provides recovery mechanisms
|
||||
|
||||
**Usage:**
|
||||
```tsx
|
||||
import { EnhancedErrorBoundary } from '@/components/errors/EnhancedErrorBoundary';
|
||||
|
||||
<EnhancedErrorBoundary enableDevOverlay={true}>
|
||||
<YourApp />
|
||||
</EnhancedErrorBoundary>
|
||||
```
|
||||
|
||||
### 3. API Request Logger (`ApiRequestLogger`)
|
||||
|
||||
**Location:** `lib/infrastructure/ApiRequestLogger.ts`
|
||||
|
||||
**Features:**
|
||||
- Logs all API requests and responses
|
||||
- Captures timing information
|
||||
- Masks sensitive data automatically
|
||||
- Tracks retry attempts
|
||||
- Provides request history and statistics
|
||||
|
||||
**Usage:**
|
||||
```typescript
|
||||
import { getGlobalApiLogger } from '@/lib/infrastructure/ApiRequestLogger';
|
||||
|
||||
const logger = getGlobalApiLogger();
|
||||
const requestId = logger.logRequest(url, method, headers, body);
|
||||
logger.logResponse(requestId, response, body, duration);
|
||||
```
|
||||
|
||||
**Auto-Interception:**
|
||||
```typescript
|
||||
// Automatically logs all fetch requests
|
||||
const loggedFetch = logger.createLoggedFetch();
|
||||
window.fetch = loggedFetch;
|
||||
```
|
||||
|
||||
### 4. Debug Mode Toggle (`DebugModeToggle`)
|
||||
|
||||
**Location:** `components/dev/DebugModeToggle.tsx`
|
||||
|
||||
**Features:**
|
||||
- Floating button to control debug features
|
||||
- Shows real-time metrics (errors, API calls, failures)
|
||||
- Quick access to test actions
|
||||
- Persistent state in localStorage
|
||||
- Global variable exposure
|
||||
|
||||
**Quick Actions:**
|
||||
- Test Error: Triggers a test error
|
||||
- Test API: Makes a failing API call
|
||||
- Copy Info: Copies debug information
|
||||
- Clear Logs: Clears all histories
|
||||
|
||||
**Global Variables:**
|
||||
- `window.__GRIDPILOT_GLOBAL_HANDLER__`
|
||||
- `window.__GRIDPILOT_API_LOGGER__`
|
||||
- `window.__GRIDPILOT_REACT_ERRORS__`
|
||||
|
||||
### 5. Error Analytics Dashboard (`ErrorAnalyticsDashboard`)
|
||||
|
||||
**Location:** `components/errors/ErrorAnalyticsDashboard.tsx`
|
||||
|
||||
**Features:**
|
||||
- Real-time error statistics
|
||||
- API performance metrics
|
||||
- Environment information
|
||||
- Error timeline (last 10 minutes)
|
||||
- Search and filter capabilities
|
||||
- Export functionality
|
||||
|
||||
**Tabs:**
|
||||
- **Errors:** Error types, recent errors, timeline
|
||||
- **API:** Request stats, slowest requests
|
||||
- **Environment:** Browser, platform, performance
|
||||
- **Raw:** Export and maintenance tools
|
||||
|
||||
### 6. Error Replay System (`ErrorReplay`)
|
||||
|
||||
**Location:** `lib/infrastructure/ErrorReplay.ts`
|
||||
|
||||
**Features:**
|
||||
- Captures complete error context
|
||||
- Persists replays across sessions
|
||||
- Replays errors with exact context
|
||||
- Export replay data
|
||||
- Auto-capture in development
|
||||
|
||||
**Replay Context Includes:**
|
||||
- Error details and stack
|
||||
- Environment (user agent, viewport, etc.)
|
||||
- API request history
|
||||
- React error history
|
||||
- Timestamp and metadata
|
||||
|
||||
**Usage:**
|
||||
```typescript
|
||||
import { getGlobalReplaySystem } from '@/lib/infrastructure/ErrorReplay';
|
||||
|
||||
const system = getGlobalReplaySystem();
|
||||
const replay = system.captureReplay(error, context);
|
||||
await system.replay(replay.metadata.replayId);
|
||||
```
|
||||
|
||||
## Integration in Layout
|
||||
|
||||
All components are automatically integrated in `app/layout.tsx`:
|
||||
|
||||
```tsx
|
||||
// Development-only initialization
|
||||
if (process.env.NODE_ENV === 'development') {
|
||||
initializeGlobalErrorHandling({
|
||||
showDevOverlay: true,
|
||||
verboseLogging: true,
|
||||
captureEnhancedStacks: true,
|
||||
});
|
||||
initializeApiLogger({
|
||||
logToConsole: true,
|
||||
logBodies: true,
|
||||
logResponses: true,
|
||||
});
|
||||
}
|
||||
|
||||
// Wrapped app with error boundaries
|
||||
<EnhancedErrorBoundary enableDevOverlay={true}>
|
||||
{/* App content */}
|
||||
|
||||
{/* Development tools */}
|
||||
{process.env.NODE_ENV === 'development' && (
|
||||
<>
|
||||
<DevToolbar />
|
||||
<DebugModeToggle />
|
||||
<ErrorAnalyticsDashboard refreshInterval={5000} />
|
||||
</>
|
||||
)}
|
||||
</EnhancedErrorBoundary>
|
||||
```
|
||||
|
||||
## DevToolbar Integration
|
||||
|
||||
The existing DevToolbar now includes:
|
||||
|
||||
1. **Notifications Section** - Test notification system
|
||||
2. **API Status Section** - Health checks and monitoring
|
||||
3. **Demo Login Section** - Role-based testing
|
||||
4. **Replay Section** - Error replay management
|
||||
|
||||
## Environment Detection
|
||||
|
||||
All features respect the environment:
|
||||
|
||||
```typescript
|
||||
const isDev = process.env.NODE_ENV === 'development';
|
||||
|
||||
// Features only activate in development
|
||||
if (isDev) {
|
||||
// Enable enhanced logging
|
||||
// Show dev overlays
|
||||
// Capture replays
|
||||
}
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. **Error Occurs** → Global Handler captures it
|
||||
2. **Enhanced Logging** → Detailed console output
|
||||
3. **Dev Overlay** → Shows if enabled
|
||||
4. **Replay Capture** → Auto-captured in dev
|
||||
5. **Analytics Update** → Dashboard reflects changes
|
||||
6. **API Logger** → Logs all requests/responses
|
||||
|
||||
## Quick Debugging Workflow
|
||||
|
||||
### Scenario 1: API Error
|
||||
1. Error occurs → Dev overlay appears
|
||||
2. Check overlay for details
|
||||
3. Open Error Analytics Dashboard
|
||||
4. View API tab for request details
|
||||
5. Use Replay section to reproduce
|
||||
|
||||
### Scenario 2: Component Crash
|
||||
1. React Error Boundary catches it
|
||||
2. Shows React-specific overlay
|
||||
3. Check console for full stack
|
||||
4. View Analytics Dashboard for context
|
||||
5. Use Debug Mode Toggle to test fixes
|
||||
|
||||
### Scenario 3: Performance Issue
|
||||
1. Open Error Analytics Dashboard
|
||||
2. Check API tab for slow requests
|
||||
3. Use Debug Mode Toggle to trigger test calls
|
||||
4. Monitor metrics in real-time
|
||||
|
||||
## Production Considerations
|
||||
|
||||
All features are **development-only** by default:
|
||||
|
||||
- Global error handler: Only initializes in dev
|
||||
- Dev overlays: Only show in dev
|
||||
- Verbose logging: Only in dev
|
||||
- Replay capture: Only in dev
|
||||
- Analytics Dashboard: Hidden in production
|
||||
|
||||
To enable in production (use with caution):
|
||||
|
||||
```tsx
|
||||
<ErrorAnalyticsDashboard showInProduction={true} />
|
||||
```
|
||||
|
||||
## Performance Impact
|
||||
|
||||
- **Development:** Full logging and monitoring
|
||||
- **Production:** Zero overhead (all features disabled)
|
||||
- **Memory:** Limited history (max 100 items per type)
|
||||
- **Storage:** Replays persisted in localStorage
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Features Not Showing
|
||||
- Check `NODE_ENV` is set to 'development'
|
||||
- Verify components are wrapped in error boundaries
|
||||
- Check browser console for initialization errors
|
||||
|
||||
### Replay Not Working
|
||||
- Ensure localStorage is available
|
||||
- Check replay ID exists
|
||||
- Verify error was captured
|
||||
|
||||
### API Logging Not Working
|
||||
- Confirm fetch override is applied
|
||||
- Check request filter settings
|
||||
- Verify logger is initialized
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use in Development:** Keep all features enabled during development
|
||||
2. **Review Logs:** Regularly check Analytics Dashboard
|
||||
3. **Test Replays:** Use replay system to verify fixes
|
||||
4. **Export Data:** Save important error states
|
||||
5. **Clear History:** Periodically clear old data
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential additions:
|
||||
- External error reporting (Sentry integration)
|
||||
- Real-time collaboration debugging
|
||||
- Error trend analysis
|
||||
- Automated replay testing
|
||||
- Performance profiling integration
|
||||
|
||||
---
|
||||
|
||||
**Note:** All these features are designed to provide maximum transparency and debugging capabilities in development environments while maintaining zero overhead in production.
|
||||
Reference in New Issue
Block a user