|
| 1 | +# Error Tracking and Handling |
| 2 | + |
| 3 | +This app has a global error handling system that automatically catches and logs errors across both server and client side. |
| 4 | + |
| 5 | +## How It Works |
| 6 | + |
| 7 | +All errors are automatically captured by SvelteKit hooks and global listeners. You don't need to wrap everything in try-catch blocks. |
| 8 | + |
| 9 | +**Key Files:** |
| 10 | + |
| 11 | +- [`src/lib/types/error.ts`](https://github.com/Lissy93/networking-toolbox/blob/main/src/lib/types/error.ts) - Error types and custom error classes |
| 12 | +- [`src/lib/utils/logger.ts`](https://github.com/Lissy93/networking-toolbox/blob/main/src/lib/utils/logger.ts) - Environment-aware logger with styled console output |
| 13 | +- [`src/lib/utils/error-manager.ts`](https://github.com/Lissy93/networking-toolbox/blob/main/src/lib/utils/error-manager.ts) - Central error management with deduplication |
| 14 | +- [`src/hooks.server.ts`](https://github.com/Lissy93/networking-toolbox/blob/main/src/hooks.server.ts) - Server-side error hook |
| 15 | +- [`src/hooks.client.ts`](https://github.com/Lissy93/networking-toolbox/blob/main/src/hooks.client.ts) - Client-side error hook with global listeners |
| 16 | +- [`src/routes/+error.svelte`](https://github.com/Lissy93/networking-toolbox/blob/main/src/routes/+error.svelte) - Error page UI |
| 17 | + |
| 18 | +**What Gets Caught Automatically:** |
| 19 | + |
| 20 | +- Server errors (API routes, server load functions) |
| 21 | +- Client errors (component errors, runtime errors) |
| 22 | +- Unhandled promise rejections |
| 23 | +- Window errors (global `window.onerror`) |
| 24 | + |
| 25 | +## For Developers |
| 26 | + |
| 27 | +### Most of the time: Do nothing |
| 28 | + |
| 29 | +The hooks catch everything. Just write your code normally. |
| 30 | + |
| 31 | +### When you want custom context |
| 32 | + |
| 33 | +Use the error manager to add specific context for debugging: |
| 34 | + |
| 35 | +```typescript |
| 36 | +import { errorManager } from '$lib/utils/error-manager'; |
| 37 | + |
| 38 | +try { |
| 39 | + await saveUserData(data); |
| 40 | +} catch (error) { |
| 41 | + errorManager.captureException(error, 'error', { |
| 42 | + component: 'UserSettings', |
| 43 | + action: 'saveData', |
| 44 | + dataSize: data.length |
| 45 | + }); |
| 46 | + throw error; // Re-throw so user sees it |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +### Custom error types |
| 51 | + |
| 52 | +Use `AppError` for domain-specific errors with user-friendly messages: |
| 53 | + |
| 54 | +```typescript |
| 55 | +import { AppError, NetworkError, ValidationError } from '$lib/types/error'; |
| 56 | + |
| 57 | +// Generic app error |
| 58 | +throw new AppError('Database query failed', 'Unable to save your changes'); |
| 59 | + |
| 60 | +// Specific error types |
| 61 | +throw new NetworkError('Connection timeout'); |
| 62 | +throw new ValidationError('Invalid email format', 'Please enter a valid email'); |
| 63 | +``` |
| 64 | + |
| 65 | +### Logging |
| 66 | + |
| 67 | +Use the logger instead of `console.log`: |
| 68 | + |
| 69 | +```typescript |
| 70 | +import { logger } from '$lib/utils/logger'; |
| 71 | + |
| 72 | +logger.debug('Cache hit', { key, size }); |
| 73 | +logger.info('User action completed', { action: 'export', format: 'csv' }); |
| 74 | +logger.warn('Rate limit approaching', { requests: 95, limit: 100 }); |
| 75 | +logger.error('Operation failed', error, { component: 'DataExporter' }); |
| 76 | +``` |
| 77 | + |
| 78 | +The logger automatically adjusts based on environment (more verbose in dev, quieter in prod) and provides styled, collapsible output in the browser. |
| 79 | + |
| 80 | +## Configuration |
| 81 | + |
| 82 | +Set the log level via environment variable: |
| 83 | + |
| 84 | +```bash |
| 85 | +VITE_LOG_LEVEL=debug # Options: debug, info, warn, error |
| 86 | +``` |
| 87 | + |
| 88 | +Defaults to `debug` in development, `warn` in production. |
| 89 | + |
| 90 | +## Expanding with External Services |
| 91 | + |
| 92 | +The error manager uses a transport pattern, making it easy to add services like Sentry or GlitchTip. |
| 93 | + |
| 94 | +### Adding Sentry |
| 95 | + |
| 96 | +1. Install Sentry: |
| 97 | +```bash |
| 98 | +npm install @sentry/sveltekit |
| 99 | +``` |
| 100 | + |
| 101 | +2. Create a Sentry transport in [`src/lib/utils/error-manager.ts`](https://github.com/Lissy93/networking-toolbox/blob/main/src/lib/utils/error-manager.ts): |
| 102 | + |
| 103 | +```typescript |
| 104 | +import * as Sentry from '@sentry/sveltekit'; |
| 105 | + |
| 106 | +class SentryTransport implements ErrorTransport { |
| 107 | + send(error: SerializedError): void { |
| 108 | + Sentry.captureException(new Error(error.message), { |
| 109 | + level: error.level, |
| 110 | + tags: { component: error.context.component }, |
| 111 | + extra: error.context, |
| 112 | + }); |
| 113 | + } |
| 114 | +} |
| 115 | + |
| 116 | +// Add to error manager |
| 117 | +if (import.meta.env.VITE_SENTRY_DSN) { |
| 118 | + errorManager.addTransport(new SentryTransport()); |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +3. Initialize Sentry in your hooks: |
| 123 | + |
| 124 | +```typescript |
| 125 | +// src/hooks.client.ts |
| 126 | +import * as Sentry from '@sentry/sveltekit'; |
| 127 | + |
| 128 | +Sentry.init({ |
| 129 | + dsn: import.meta.env.VITE_SENTRY_DSN, |
| 130 | + environment: import.meta.env.MODE, |
| 131 | +}); |
| 132 | +``` |
| 133 | + |
| 134 | +### Adding GlitchTip |
| 135 | + |
| 136 | +GlitchTip is Sentry-compatible, so use the same approach with a different DSN. |
| 137 | + |
| 138 | +### Custom Transport |
| 139 | + |
| 140 | +Create any transport that implements the `ErrorTransport` interface: |
| 141 | + |
| 142 | +```typescript |
| 143 | +class CustomTransport implements ErrorTransport { |
| 144 | + async send(error: SerializedError): Promise<void> { |
| 145 | + await fetch('/api/log-error', { |
| 146 | + method: 'POST', |
| 147 | + body: JSON.stringify(error), |
| 148 | + }); |
| 149 | + } |
| 150 | +} |
| 151 | + |
| 152 | +errorManager.addTransport(new CustomTransport()); |
| 153 | +``` |
| 154 | + |
| 155 | +## Error Deduplication |
| 156 | + |
| 157 | +The error manager automatically deduplicates identical errors within a 5-second window. This prevents log spam when an error repeats rapidly. |
| 158 | + |
| 159 | +## Testing |
| 160 | + |
| 161 | +See [`tests/unit/utils/error-manager.test.ts`](https://github.com/Lissy93/networking-toolbox/blob/main/tests/unit/utils/error-manager.test.ts) for examples of testing error handling in your code. |
0 commit comments