Browser SDK

Quick Start

Install the package and initialize the SDK in your application entry point.

npm install @tracekit/browser

import { init, captureException } from '@tracekit/browser';

init({
  apiKey: 'your-api-key',
  release: '1.0.0',
  environment: 'production',
});

try {
  riskyOperation();
} catch (err) {
  captureException(err as Error);
}

Configuration Reference

Pass a TracekitBrowserConfig object to init(). Only apiKey is required.

Annotated Configuration

init({
  // Required
  apiKey: 'your-api-key',

  // Identity & environment
  release: '1.0.0',                    // undefined by default
  environment: 'production',            // default: 'production'
  serviceName: 'my-app',               // default: 'browser-app'

  // Sampling & control
  sampleRate: 1.0,                      // 0.0-1.0, default: 1.0
  enabled: true,                        // default: true
  debug: false,                         // default: false

  // Data limits
  maxBreadcrumbs: 100,                  // default: 100

  // Endpoint
  endpoint: 'https://app.tracekit.dev', // default

  // Distributed tracing
  tracePropagationTargets: [            // default: [] (same-origin only)
    'https://api.example.com',
  ],

  // Event filtering
  beforeSend: (event) => {
    if (event.message?.includes('ResizeObserver')) return null;
    return event;
  },

  // Addon integrations (e.g., session replay)
  addons: [],

  // Integration toggles (all default: true)
  integrations: {
    globalError: true,    // window.onerror + unhandledrejection
    console: true,        // console.* breadcrumbs
    fetch: true,          // fetch() breadcrumbs + traceparent
    xhr: true,            // XHR breadcrumbs + traceparent
    dom: true,            // click event breadcrumbs
    navigation: true,     // pushState/popState breadcrumbs
  },
});

Options Reference

Integration Toggles

All built-in integrations default to true. Disable individual integrations by setting them to false.

API Reference

All functions are exported from @tracekit/browser. The SDK must be initialized with init() before calling other functions.

import { init } from '@tracekit/browser';
init({ apiKey: 'your-api-key', release: '1.0.0' });

import { captureException } from '@tracekit/browser';

try {
  JSON.parse(invalidJson);
} catch (err) {
  const eventId = captureException(err as Error, { input: invalidJson });
  console.log('Reported as:', eventId);
}

import { captureMessage } from '@tracekit/browser';

captureMessage('User completed onboarding', 'info');
captureMessage('Payment retry limit exceeded', 'warning');

import { setUser } from '@tracekit/browser';

// After login
setUser({ id: 'user-123', email: '[email protected]', username: 'alice' });

// On logout
setUser(null);

import { setTag } from '@tracekit/browser';

setTag('tenant', 'acme-corp');
setTag('feature_flag', 'new-checkout-v2');

import { setExtra } from '@tracekit/browser';

setExtra('cart_items', 3);
setExtra('last_action', 'add_to_cart');

import { addBreadcrumb } from '@tracekit/browser';

addBreadcrumb({
  type: 'user',
  category: 'auth',
  message: 'User logged in',
  level: 'info',
  data: { method: 'oauth', provider: 'github' },
});

import { getClient } from '@tracekit/browser';

const client = getClient();
if (client) {
  console.log('SDK initialized');
}

Types

All types are exported from @tracekit/browser for use in your TypeScript code.

BrowserEvent

Breadcrumb

UserContext

SeverityLevel

A union type for event severity:

type SeverityLevel = 'fatal' | 'error' | 'warning' | 'info' | 'debug';

StackFrame

Integration

Usage Examples

Setting user context after login

import { setUser } from '@tracekit/browser';

async function handleLogin(email: string, password: string) {
  const user = await authService.login(email, password);
  setUser({
    id: user.id,
    email: user.email,
    username: user.displayName,
  });
}

function handleLogout() {
  authService.logout();
  setUser(null);
}

Adding custom breadcrumbs

import { addBreadcrumb } from '@tracekit/browser';

function addToCart(product: Product) {
  cart.add(product);
  addBreadcrumb({
    type: 'user',
    category: 'cart',
    message: 'Added item to cart',
    level: 'info',
    data: { productId: product.id, price: product.price },
  });
}

Filtering events with beforeSend

import { init } from '@tracekit/browser';

init({
  apiKey: 'your-api-key',
  beforeSend: (event) => {
    // Drop noisy ResizeObserver errors
    if (event.message?.includes('ResizeObserver')) return null;
    // Drop errors from browser extensions
    if (event.stackTrace?.includes('chrome-extension://')) return null;
    // Scrub sensitive data
    if (event.message?.includes('password')) {
      event.message = '[REDACTED]';
    }
    return event;
  },
});

Configuring distributed tracing

import { init } from '@tracekit/browser';

init({
  apiKey: 'your-api-key',
  tracePropagationTargets: [
    'https://api.example.com',         // Exact match
    'https://auth.example.com',        // Another backend
    /^https:\/\/.*\.example\.com/,     // Regex: all subdomains
  ],
});
// Fetch requests to matching URLs receive a traceparent header.
// Your backend reads this header to link frontend and backend traces.

Using with session replay

import { init } from '@tracekit/browser';
import { replayIntegration } from '@tracekit/replay';

const replay = replayIntegration({
  sessionSampleRate: 0.1,   // Record 10% of sessions
  errorSampleRate: 1.0,     // Always record sessions with errors
});

init({
  apiKey: 'your-api-key',
  release: '1.0.0',
  addons: [replay],
});

See the Session Replay documentation for full configuration options.

Troubleshooting

// Express.js example:
app.use(cors({
  origin: 'https://your-app.com',
  allowedHeaders: ['Content-Type', 'Authorization', 'traceparent', 'tracestate'],
}));

init({
  apiKey: 'your-api-key',
  debug: process.env.NODE_ENV === 'development',
});

Complete Example

A real-world setup showing all major features together.

import {
  init,
  captureException,
  captureMessage,
  setUser,
  setTag,
  setExtra,
  addBreadcrumb,
} from '@tracekit/browser';
import { replayIntegration } from '@tracekit/replay';

// 1. Initialize with full configuration
const replay = replayIntegration({
  sessionSampleRate: 0.1,
  errorSampleRate: 1.0,
});

init({
  apiKey: process.env.TRACEKIT_API_KEY!,
  release: process.env.APP_VERSION || '0.0.0',
  environment: process.env.NODE_ENV || 'production',
  serviceName: 'my-frontend',
  tracePropagationTargets: [
    'https://api.myapp.com',
    /^https:\/\/.*\.myapp\.com/,
  ],
  beforeSend: (event) => {
    if (event.message?.includes('ResizeObserver')) return null;
    if (event.stackTrace?.includes('chrome-extension://')) return null;
    return event;
  },
  addons: [replay],
});

// 2. Set user context after authentication
async function onLogin(credentials: { email: string; password: string }) {
  const user = await api.login(credentials);
  setUser({ id: user.id, email: user.email, username: user.name });
  setTag('plan', user.plan);
  setExtra('signup_date', user.createdAt);
  addBreadcrumb({
    type: 'user',
    category: 'auth',
    message: 'User logged in',
    level: 'info',
  });
  captureMessage('User login successful', 'info');
}

// 3. Manual error capture with context
async function loadDashboard() {
  try {
    const data = await api.fetchDashboard();
    renderDashboard(data);
  } catch (err) {
    captureException(err as Error, {
      component: 'Dashboard',
      retryCount: 0,
    });
    showErrorFallback();
  }
}