lexakit-notifications

Production error monitoring via email - Simple alternative to Sentry for small teams

Get beautiful email notifications when your Node.js/NestJS application encounters errors. Perfect for solo developers and small teams who want simple, cost-effective error monitoring without the complexity of Sentry or Rollbar.

Note: Planning to move to @lexakit/notifications scope once the npm organization is created.

Features

• ✅ One-line setup - Add to your app in seconds
• 📧 Beautiful HTML emails - Professional error reports with stack traces
• 🚫 Smart throttling - Won't spam you on cascading failures
• 🎯 Framework-agnostic - Works with any Node.js app or NestJS
• 💰 Cost-effective - Just use your existing email service (SendGrid, etc.)
• 🔒 Private - Your error data stays with you
• ⚡ Lightweight - No heavy SDK, minimal performance impact

Installation

npm install lexakit-notifications @sendgrid/mail

Quick Start

NestJS (Recommended)

One-line setup in main.ts:

import { ErrorMonitorFilter } from 'lexakit-notifications/nestjs';

// In your bootstrap function:
app.useGlobalFilters(new ErrorMonitorFilter(
  new ErrorMonitor({
    notifyEmail: '[email protected]',
    sendgrid: { apiKey: process.env.SENDGRID_API_KEY }
  })
));

Done! Now all 500+ errors will email you automatically.

Standalone Node.js

import { ErrorMonitor } from 'lexakit-notifications';

const errorMonitor = new ErrorMonitor({
  notifyEmail: '[email protected]',
  sendgrid: { apiKey: process.env.SENDGRID_API_KEY }
});

// In your error handler:
try {
  // ... your code
} catch (error) {
  await errorMonitor.notifyError({
    statusCode: 500,
    errorMessage: error.message,
    stack: error.stack,
    url: req.url,
    method: req.method,
    timestamp: new Date().toISOString()
  });
  throw error;
}

Configuration

Basic Configuration

{
  notifyEmail: '[email protected]',  // Your email address
  minStatus: 500,                   // Minimum status code (default: 500)
  sendgrid: {
    apiKey: process.env.SENDGRID_API_KEY
  },
  from: {
    email: '[email protected]',
    name: 'Error Monitor'
  }
}

Advanced Configuration

{
  notifyEmail: ['[email protected]', '[email protected]'],  // Multiple recipients
  minStatus: 400,  // Notify on 400+ errors
  throttle: {
    enabled: true,
    window: 300000,  // 5 minutes (in ms)
    strategy: 'per-endpoint'  // 'per-endpoint' | 'per-recipient' | 'per-type'
  },
  sendgrid: {
    apiKey: process.env.SENDGRID_API_KEY,
    from: {
      email: '[email protected]',
      name: 'Production Alerts'
    }
  }
}

NestJS Integration

Method 1: Global Filter (Simplest)

// main.ts
import { ErrorMonitor } from '@lexakit/notifications';
import { ErrorMonitorFilter } from '@lexakit/notifications/nestjs';

const errorMonitor = new ErrorMonitor({
  notifyEmail: '[email protected]',
  sendgrid: { apiKey: process.env.SENDGRID_API_KEY }
});

app.useGlobalFilters(new ErrorMonitorFilter(errorMonitor));

Method 2: Module with Dependency Injection

// app.module.ts
import { LexaKitNotificationsModule } from '@lexakit/notifications/nestjs';

@Module({
  imports: [
    LexaKitNotificationsModule.forRoot({
      notifyEmail: '[email protected]',
      sendgrid: { apiKey: process.env.SENDGRID_API_KEY }
    })
  ]
})
export class AppModule {}

// Then inject anywhere:
import { LexaKitNotificationsService } from 'lexakit-notifications/nestjs';

@Injectable()
export class MyService {
  constructor(private notifications: LexaKitNotificationsService) {}
  
  async someMethod() {
    await this.notifications.notifyError({
      statusCode: 500,
      errorMessage: 'Something went wrong',
      // ...
    });
  }
}

Method 3: Async Configuration (with ConfigService)

import { LexaKitNotificationsModule } from '@lexakit/notifications/nestjs';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    LexaKitNotificationsModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        notifyEmail: config.get('NOTIFY_EMAIL'),
        sendgrid: {
          apiKey: config.get('SENDGRID_API_KEY')
        }
      }),
      inject: [ConfigService]
    })
  ]
})
export class AppModule {}

Throttling Strategies

Prevent email spam during cascading failures:

per-endpoint (default)

Throttles per status code + URL combination:

• Won't send duplicate emails for same endpoint
• Example: 500-/api/users throttled for 5 minutes

per-recipient

Throttles per email recipient:

• Limits total emails per recipient
• Useful for multiple recipients with different priorities

per-type

Throttles per error type (4xx, 5xx):

• Groups similar errors
• Example: All 5xx errors throttled together

throttle: {
  enabled: true,
  window: 300000,  // 5 minutes
  strategy: 'per-endpoint'
}

Email Template

You'll receive beautiful HTML emails with:

• ✅ Status code badge
• ✅ Error message
• ✅ Full stack trace (syntax highlighted)
• ✅ Request details (method, URL, timestamp)
• ✅ User context (user ID, IP, user agent)
• ✅ Responsive design

Text fallback included for email clients without HTML support.

Environment Variables

# Required
SENDGRID_API_KEY=your_sendgrid_api_key

# Optional
[email protected]
MIN_ERROR_STATUS=500
THROTTLE_WINDOW=300000

Use Cases

Solo Developers

• Quick error alerts without setting up monitoring infrastructure
• Free tier SendGrid covers most small apps

Small Startups

• Cost-effective alternative to $29/mo Sentry plans
• Email alerts reach the whole team instantly

Side Projects

• Know when things break without checking logs
• No credit card required (free SendGrid tier)

Internal Tools

• Simple monitoring for admin dashboards
• Keep error data private

Comparison with Sentry

| Feature | lexakit-notifications | Sentry | |---------|----------------------|--------| | Cost | Free (just email service) | $26+/month | | Setup | One line of code | SDK integration + config | | Data Privacy | Your servers only | Third-party service | | Email Alerts | Built-in, beautiful | Requires configuration | | Performance Monitoring | ❌ | ✅ | | Issue Tracking | ❌ (use email) | ✅ | | Team Collaboration | ✅ (via email) | ✅ (dashboard) | | Best For | Small teams, side projects | Large teams, enterprise |

API Reference

ErrorMonitor

Main class for error monitoring.

const monitor = new ErrorMonitor(config);
await monitor.notifyError(context);

ErrorContext

interface ErrorContext {
  method: string;          // HTTP method
  url: string;             // Request URL
  statusCode: number;      // HTTP status
  errorMessage: string;    // Error message
  stack?: string;          // Stack trace
  userId?: string;         // User ID (if available)
  timestamp: string;       // ISO timestamp
  ipAddress?: string;      // Client IP
  userAgent?: string;      // User agent
}

NotificationResult

interface NotificationResult {
  success: boolean;
  messageId?: string;    // Email message ID
  error?: string;        // Error if failed
  throttled?: boolean;   // If notification was throttled
}

Roadmap

• [ ] Support for more email providers (Resend, AWS SES, Nodemailer)
• [ ] Slack/Discord webhook support
• [ ] Error grouping and deduplication
• [ ] Custom email templates
• [ ] Error frequency reports (daily/weekly digest)

Contributing

Contributions welcome! This is the first package in the LexaKit suite of developer tools.

License

MIT

Author

LexaPlus - https://lexaplus.com
Contact: [email protected]

Part of the LexaKit suite - Production-ready tools for developers.

Made with ❤️ for developers who just want to know when things break.