Runtime error monitoring package with React provider that automatically reports errors to webhook endpoints
npm install wingman-monitorbash
npm install wingman-monitor
`
Quick Start
$3
`bash
npx wingman init YOUR_ACCESS_TOKEN
`
Optional parameters:
`bash
npx wingman init YOUR_ACCESS_TOKEN --webhook https://your-webhook-url.com/errors --env production
`
$3
`javascript
// ES6/TypeScript
import { WingmanMonitor } from 'wingman-monitor';
// CommonJS
const { WingmanMonitor } = require('wingman-monitor');
// Create and start the monitor
const monitor = new WingmanMonitor();
monitor.start();
`
$3
Wingman will now automatically capture and report runtime errors to your webhook endpoint.
CLI Commands
$3
`bash
npx wingman init [options]
`
Options:
- --webhook : Custom webhook URL (default: https://api.wingman-monitor.com/webhook)
- --env : Environment name (default: development)
$3
`bash
npx wingman status
`
$3
`bash
npx wingman enable
npx wingman disable
`
Advanced Usage
$3
`javascript
import { WingmanMonitor } from 'wingman-monitor';
const monitor = new WingmanMonitor();
await monitor.start();
// Report custom errors
try {
// Your code here
} catch (error) {
await monitor.reportCustomError(error, {
userId: 'user123',
action: 'checkout',
additionalData: 'custom metadata'
});
}
`
$3
The .wingman.json configuration file is created automatically when you run wingman init:
`json
{
"accessToken": "your-access-token",
"webhookUrl": "https://your-webhook-url.com/errors",
"environment": "production",
"enabled": true,
"createdAt": "2025-06-24T12:00:00.000Z"
}
`
$3
Wingman sends error reports in the following format:
`json
{
"message": "Error message",
"stack": "Error stack trace",
"timestamp": "2025-06-24T12:00:00.000Z",
"environment": "production",
"projectInfo": {
"name": "my-app",
"version": "1.0.0",
"url": "https://github.com/user/repo"
},
"errorType": "uncaughtException",
"severity": "critical",
"metadata": {
"additional": "data"
},
"accessToken": "your-access-token",
"projectPath": "/path/to/project"
}
`
$3
- uncaughtException: Uncaught exceptions in Node.js
- unhandledRejection: Unhandled promise rejections
- windowError: Browser window errors
- windowUnhandledRejection: Browser unhandled promise rejections
- consoleError: Errors logged to console
- customError: Manually reported errors
$3
- low: Minor issues, console errors
- medium: Standard errors, custom errors
- high: Unhandled rejections
- critical: Uncaught exceptions
API Reference
$3
#### Constructor
`javascript
new WingmanMonitor(projectPath?: string)
`
#### Methods
##### start(): Promise
Starts error monitoring. Loads configuration and sets up error handlers.
##### stop(): void
Stops error monitoring and removes error handlers.
##### reportCustomError(error: Error, metadata?: Record
Manually report a custom error with optional metadata.
##### isActive(): boolean
Returns whether monitoring is currently active.
$3
#### Constructor
`javascript
new ConfigManager(projectPath?: string)
`
#### Methods
##### initialize(config: WingmanConfig): Promise
Initialize configuration with provided settings.
##### load(): Promise
Load configuration from .wingman.json file.
##### save(config: Partial
Save configuration updates to file.
##### isEnabled(): boolean
Check if monitoring is enabled.
Environment Variables
You can also configure Wingman using environment variables:
- WINGMAN_ACCESS_TOKEN: Access token for authentication
- WINGMAN_WEBHOOK_URL: Webhook URL for error reports
- WINGMAN_ENVIRONMENT: Environment name
- WINGMAN_ENABLED: Enable/disable monitoring (true/false)
Best Practices
1. Use different access tokens for different environments
2. Set appropriate webhook URLs for each environment
3. Test your webhook endpoint before deploying
4. Monitor the monitoring: Ensure Wingman itself doesn't cause issues
5. Use custom error reporting for business-logic specific errors
Webhook Endpoint Requirements
Your webhook endpoint should:
- Accept POST requests
- Handle JSON payload
- Return appropriate HTTP status codes (200-299 for success)
- Include authentication validation using the access token
Example webhook handler (Express.js):
`javascript
app.post('/webhook/errors', (req, res) => {
const { accessToken, message, errorType, severity } = req.body;
// Validate access token
if (accessToken !== process.env.EXPECTED_TOKEN) {
return res.status(401).json({ error: 'Unauthorized' });
}
// Process the error report
console.log([${severity}] ${errorType}: ${message});
// Store in database, send alerts, etc.
res.status(200).json({ success: true });
});
``