@errorlens/sdk

A lightweight error tracking SDK for frontend applications. Automatically captures JavaScript errors, unhandled promise rejections, and network failures.

Features

• 📦 Lightweight - Only ~5KB minified & gzipped
• 🚀 Zero Dependencies - No external dependencies required
• 🔍 Smart Error Grouping - Automatically groups similar errors
• 📊 Breadcrumb Tracking - Records user actions leading up to errors
• 🎯 Flexible Configuration - Works with React, Next.js, Vue, vanilla JS, and more
• 🔗 Network Monitoring - Captures fetch and XHR failures
• 💾 Smart Buffering - Batches errors for efficient transmission

Installation

npm install @errorlens/sdk
# or
yarn add @errorlens/sdk
# or
pnpm add @errorlens/sdk

📚 Interactive Guide

New to ErrorLens? Run the interactive CLI guide to learn about features and see a demo:

npx errorlens-guide

This will walk you through:

• ✅ Feature overview
• ✅ Installation steps
• ✅ Configuration options
• ✅ Interactive demo app
• ✅ Dashboard walk-through
• ✅ Advanced settings
• ✅ Quick start guide

Quick Start

1. Initialize the SDK

import errorLens from '@errorlens/sdk';

errorLens.init({
  endpoint: 'https://your-errorlens-server.com/api/errors',
  projectId: 'my-project',
  environment: process.env.NODE_ENV,
  release: '1.0.0',
});

2. That's it!

The SDK automatically captures:

• Uncaught JavaScript errors
• Unhandled promise rejections
• Network request failures (fetch & XHR)
• Console errors

Configuration

interface ErrorLensConfig {
  endpoint: string;              // Required: Your ErrorLens API endpoint
  projectId: string;             // Required: Unique project identifier
  environment?: string;          // Optional: 'production', 'staging', etc (default: 'development')
  release?: string;              // Optional: Your app version
  enabled?: boolean;             // Optional: Enable/disable capture (default: true)
  maxBreadcrumbs?: number;       // Optional: Max breadcrumbs to store (default: 50)
  sampleRate?: number;           // Optional: Sample rate 0-1 (default: 1.0)
}

Usage

Capture Custom Errors

try {
  riskyOperation();
} catch (error) {
  errorLens.captureError(error, {
    context: 'checkout',
    userId: user.id,
  });
}

Capture Messages

errorLens.captureMessage('User initiated payment', 'info', {
  amount: 99.99,
});

Add Breadcrumbs

// Automatic breadcrumbs are added for errors and console messages
// Add custom breadcrumbs for user actions:

errorLens.addBreadcrumb({
  type: 'action',
  category: 'user-interaction',
  message: 'User clicked checkout button',
  data: {
    buttonId: 'checkout-btn',
    timestamp: Date.now(),
  },
  level: 'info',
});

Set User Context

errorLens.setUser({
  id: 'user-123',
  email: '[email protected]',
  username: 'johndoe',
});

// Clear user context
errorLens.clearUser();

Manual Flush

// Errors are automatically flushed every 5 seconds or when buffer reaches 10 errors
// Force flush if needed:
await errorLens.flush();

Framework-Specific Setup

React

import { useEffect } from 'react';
import errorLens from '@errorlens/sdk';

export default function App() {
  useEffect(() => {
    errorLens.init({
      endpoint: process.env.REACT_APP_ERROR_ENDPOINT,
      projectId: 'my-app',
      environment: process.env.NODE_ENV,
    });
  }, []);

  return <div>...</div>;
}

Next.js

// pages/_app.tsx or app/layout.tsx
import errorLens from '@errorlens/sdk';

if (typeof window !== 'undefined') {
  errorLens.init({
    endpoint: process.env.NEXT_PUBLIC_ERROR_ENDPOINT,
    projectId: 'my-nextjs-app',
    environment: process.env.NODE_ENV,
  });
}

export default function App() {
  // ...
}

Vue

// main.ts
import { createApp } from 'vue';
import errorLens from '@errorlens/sdk';
import App from './App.vue';

if (typeof window !== 'undefined') {
  errorLens.init({
    endpoint: import.meta.env.VITE_ERROR_ENDPOINT,
    projectId: 'my-vue-app',
    environment: import.meta.env.MODE,
  });
}

const app = createApp(App);
app.mount('#app');

Error Payload Example

Each error sent includes:

{
  "type": "js_error",
  "message": "Cannot read property 'foo' of undefined",
  "stack": "Error: Cannot read property 'foo' of undefined\n  at Object.<anonymous>...",
  "filename": "app.js",
  "lineno": 42,
  "colno": 15,
  "url": "https://example.com/app",
  "userAgent": "Mozilla/5.0...",
  "breadcrumbs": [
    {
      "type": "action",
      "category": "navigation",
      "message": "User clicked link",
      "timestamp": 1234567890
    }
  ],
  "timestamp": 1234567890
}

Best Practices

1. Initialize early - Call errorLens.init() in your app root/entry point
2. Use environment variables - Store your endpoint in env vars, not code
3. Set user context - Call setUser() after authentication
4. Add meaningful breadcrumbs - Track important user actions
5. Sample in production - Use sampleRate: 0.1 to reduce load if needed
6. Version your app - Set release to track which version had the error

Performance

• Bundle size: ~5KB minified & gzipped
• No dependencies: Pure JavaScript, zero external dependencies
• Async transmission: Errors sent asynchronously in background
• Smart batching: Multiple errors sent in single request when possible
• Configurable sampling: Reduce traffic with sample rate

Troubleshooting

SDK not capturing errors?

• Check that enabled is not false
• Verify endpoint is correct and accessible
• Check browser console for initialization errors
• Ensure projectId is provided

High bandwidth usage?

• Reduce sampleRate (e.g., 0.1 for 10%)
• Increase maxBreadcrumbs (larger value = less frequent flushes)
• Check your error rate on the dashboard

Missing user data?

• Call setUser() after authentication
• Check that user data is stringified if using metadata

Support

For issues, questions, or contributions, visit the ErrorLens repository.

License

MIT © Vidhya Sagar Thakur