markdown

@rezabakhshi/error-tracker-node

Node.js SDK for Error Tracker - Real-time error monitoring for backend applications. Automatically captures errors in Express, Fastify, and NestJS applications.

Features

• 🚀 Automatic Error Capture - Catches uncaught exceptions and unhandled rejections
• 📊 Real-time Reporting - Sends errors to your Error Tracker dashboard instantly
• 🔌 Framework Support - Built-in middleware for Express, Fastify, and NestJS
• 👤 User Context - Associate errors with specific users
• 🍞 Breadcrumbs - Track events leading up to errors
• 🎯 Manual Error Reporting - Capture custom errors and messages
• ⚡ Lightweight - Minimal overhead for your Node.js applications
• 📦 TypeScript Ready - Full type definitions included

Installation

npm install @rezabakhshi/error-tracker-node
Quick Start
Basic Usage
javascript
import { init, captureException } from '@rezabakhshi/error-tracker-node';

init({
  dsn: 'http://localhost:8000/your-project-id',
  apiKey: 'your-api-key-here',
  environment: 'production',
  release: '1.0.0'
});

try {
  // Your code that might throw an error
  await someAsyncOperation();
} catch (error) {
  captureException(error, { 
    context: 'additional info',
    userId: currentUser.id 
  });
}
Framework Integrations
Express.js
javascript
import express from 'express';
import { errorTrackerExpress } from '@rezabakhshi/error-tracker-node/express';

const app = express();

// Add middleware (after all routes)
app.use(errorTrackerExpress({
  dsn: 'http://localhost:8000/your-project-id',
  apiKey: 'your-api-key-here',
  environment: 'production'
}));

app.get('/error', () => {
  throw new Error('This will be automatically captured!');
});

// Error handling middleware
app.use((err, req, res, next) => {
  res.status(500).json({ error: err.message });
});

app.listen(3000);
Fastify
javascript
import Fastify from 'fastify';
import errorTrackerFastify from '@rezabakhshi/error-tracker-node/fastify';

const app = Fastify();

// Register plugin
await app.register(errorTrackerFastify, {
  dsn: 'http://localhost:8000/your-project-id',
  apiKey: 'your-api-key-here',
  environment: 'production'
});

app.get('/error', async () => {
  throw new Error('This will be automatically captured!');
});

await app.listen({ port: 3000 });
NestJS
Global Interceptor
typescript
import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { ErrorTrackerInterceptor } from '@rezabakhshi/error-tracker-node/nestjs';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: ErrorTrackerInterceptor
    }
  ]
})
export class AppModule {}
With Custom Configuration
typescript
import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { createErrorTrackerInterceptor } from '@rezabakhshi/error-tracker-node/nestjs';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useFactory: () => createErrorTrackerInterceptor({
        dsn: process.env.ERROR_TRACKER_DSN,
        apiKey: process.env.ERROR_TRACKER_API_KEY,
        environment: process.env.NODE_ENV
      })
    }
  ]
})
export class AppModule {}
Controller-Level Interceptor
typescript
import { Controller, Get, UseInterceptors } from '@nestjs/common';
import { ErrorTrackerInterceptor } from '@rezabakhshi/error-tracker-node/nestjs';

@Controller('test')
@UseInterceptors(ErrorTrackerInterceptor)
export class TestController {
  @Get()
  getError() {
    throw new Error('This will be captured!');
  }
}
API Reference
init(options: InitOptions)
Initializes the SDK with your configuration.

Options:

Option	Type	Default	Description
dsn	string	required	Your project DSN from Error Tracker
apiKey	string	required	Your project API key
environment	string	'production'	Environment name (production, staging, etc.)
release	string	undefined	Release/version of your application
enableAutoCapture	boolean	true	Automatically capture unhandled errors
sampleRate	number	1.0	Percentage of errors to capture (0-1)
enableBreadcrumbs	boolean	true	Enable event tracking
maxBreadcrumbs	number	50	Maximum breadcrumbs to store
beforeSend	function	undefined	Modify/cancel events before sending
captureException(error: any, extra?: Record<string, any>)
Captures an error and sends it to Error Tracker.

javascript
captureException(new Error('Something went wrong'), {
  component: 'UserProfile',
  action: 'saveProfile',
  userId: '123'
});
captureMessage(message: string, level?: 'info' | 'warning' | 'error', extra?: Record<string, any>)
Captures a custom message or event.

javascript
captureMessage('User clicked button', 'info', {
  buttonName: 'submit',
  page: 'checkout'
});
setUser(user: { id?: string; email?: string; username?: string })
Sets the current user context for error tracking.

javascript
setUser({
  id: 'user-123',
  email: '[email protected]',
  username: 'john_doe'
});
addBreadcrumb(type: string, message: string, data?: any)
Adds a breadcrumb for debugging.

javascript
addBreadcrumb('navigation', 'User navigated to dashboard', { from: '/home' });
Advanced Configuration
Using Environment Variables
Create a .env file:

env
ERROR_TRACKER_DSN=http://localhost:8000/your-project-id
ERROR_TRACKER_API_KEY=your-api-key-here
NODE_ENV=production
Then use it:

javascript
import { init } from '@rezabakhshi/error-tracker-node';

init({
  dsn: process.env.ERROR_TRACKER_DSN,
  apiKey: process.env.ERROR_TRACKER_API_KEY,
  environment: process.env.NODE_ENV
});
Custom Before Send Hook
javascript
init({
  dsn: 'http://localhost:8000/your-project-id',
  apiKey: 'your-api-key-here',
  environment: 'production',
  beforeSend: (payload) => {
    // Remove sensitive data
    delete payload.headers.authorization;
    delete payload.body.password;
    
    // Add custom tags
    payload.tags = { version: '1.0.0' };
    
    return payload;
  }
});
Sampling Errors
javascript
init({
  dsn: 'http://localhost:8000/your-project-id',
  apiKey: 'your-api-key-here',
  sampleRate: 0.5 // Capture 50% of errors
});
Error Tracking Dashboard
All captured errors appear in your Error Tracker dashboard with:

Error grouping by fingerprint

Occurrence counts and trends

User impact analysis

Request context (headers, URL, method)

Stack traces and breadcrumbs

AI-powered insights and recommendations

Browser Support
Node.js Version	Support
14.x	✅
16.x	✅
18.x	✅
20.x	✅
22.x	✅
Related Packages
@rezabakhshi/error-tracker-browser - Browser SDK for frontend error tracking

Troubleshooting
Errors not appearing in dashboard?
Verify your DSN and API key are correct

Check your backend is running

Look for console error messages

Check network tab for failed requests

SDK not initializing?
Make sure you call init() before capturing errors:

javascript
// ✅ Correct
init({ dsn: '...', apiKey: '...' });
captureException(error);

// ❌ Incorrect
captureException(error); // SDK not initialized yet
init({ dsn: '...', apiKey: '...' });
License
MIT

Links
Error Tracker Platform

Documentation

GitHub Repository

Report Issue

Made with ❤️ by Reza Bakhshi