@devfolio-tryouts/sdk-js

A lightweight browser SDK for capturing and reporting runtime errors to the Error Tracker backend.

Features

• Automatic Error Capture - Catches uncaught errors and unhandled promise rejections
• Manual Error Reporting - Capture errors programmatically with custom metadata
• Batching & Queueing - Efficiently batches errors before sending
• Retry with Exponential Backoff - Automatically retries failed sends
• Lifecycle Hooks - Customize error payloads before sending
• Zero Dependencies - Pure JavaScript, works in any browser

Installation

npm install @devfolio-tryouts/sdk-js

Or use from a CDN:

<script src="https://unpkg.com/@devfolio-tryouts/sdk-js/dist/index.umd.js"></script>

Quick Start

ES Modules

import { init, capture } from '@devfolio-tryouts/sdk-js';

init({
  apiUrl: 'https://your-error-tracker-api.com',
  apiKey: 'your-api-key',
  appId: 'my-app',
  appName: 'My Application',
  env: 'production'
});

// Errors are now automatically captured!
// You can also manually capture:
try {
  riskyOperation();
} catch (error) {
  capture(error, { userId: '123', action: 'checkout' });
}

UMD (Browser Global)

<script src="https://unpkg.com/@devfolio-tryouts/sdk-js/dist/index.umd.js"></script>
<script>
  ErrorTracker.init({
    apiUrl: 'https://your-error-tracker-api.com',
    apiKey: 'your-api-key',
    appId: 'my-app',
    appName: 'My Application',
    env: 'production'
  });
</script>

API Reference

init(options)

Initialize the SDK with configuration options.

Parameters:

• options.apiUrl (string, required) - Backend API URL
• options.apiKey (string, required) - API key for authentication
• options.appId (string, required) - Unique application identifier
• options.appName (string, required) - Human-readable app name
• options.env (string, optional) - Environment (default: 'production')

Example:

init({
  apiUrl: 'https://api.example.com',
  apiKey: 'sk_live_abc123',
  appId: 'my-app-prod',
  appName: 'My App',
  env: 'production'
});

capture(error, metadata)

Manually capture an error with optional metadata.

Parameters:

• error (Error|string|Object) - The error to capture
• metadata (Object, optional) - Additional context

Example:

capture(new Error('Payment failed'), {
  userId: '12345',
  amount: 99.99,
  paymentMethod: 'card'
});

flush()

Manually flush the error queue (normally happens automatically every 2 seconds).

Returns: Promise

Example:

await flush();

setBeforeSend(callback)

Set a hook to modify error payloads before sending.

Parameters:

• callback (Function) - Function that receives and returns the payload

Example:

setBeforeSend((payload) => {
  // Add custom fields
  payload.release = '1.2.3';
  payload.userId = getCurrentUser().id;

  // Filter sensitive data
  if (payload.stack.includes('password')) {
    return null; // Drop this error
  }

  return payload;
});

setOnError(callback)

Set a hook called when network send fails.

Parameters:

• callback (Function) - Function that receives (error, batch)

Example:

setOnError((error, batch) => {
  console.error('Failed to send errors:', error);
  // Could log to alternative service
});

getQueueSize()

Get the current number of errors in the queue.

Returns: number

clearQueue()

Clear all pending errors from the queue.

destroy()

Clean up the SDK - removes listeners, stops flush interval, and clears state.

Example:

destroy();

Advanced Usage

Custom Error Metadata

capture(error, {
  userId: user.id,
  route: window.location.pathname,
  browser: navigator.userAgent,
  customField: 'any value'
});

Filter Errors Before Sending

setBeforeSend((payload) => {
  // Ignore specific errors
  if (payload.message.includes('Script error')) {
    return null; // Don't send
  }

  // Add global context
  payload.sessionId = getSessionId();

  return payload;
});

Handle Send Failures

setOnError((error, failedBatch) => {
  // Log to alternative service
  alternativeLogger.log('Error tracking failed', {
    error: error.message,
    count: failedBatch.length
  });
});

Browser Support

Works in all modern browsers and IE11+.

License

MIT

Support

For issues and questions, please visit the GitHub repository.

Built for Devfolio Tryouts - Demonstrating production-ready error tracking.