Browser SDK

Monitor errors and performance in vanilla JavaScript web applications

The Sentry Browser SDK provides comprehensive error monitoring and performance tracking for JavaScript applications running in the browser.

Installation

npm

npm install @sentry/browser

Basic Setup

Initialize Sentry as early as possible in your application, before any other code runs:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  
  // Performance Monitoring
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
  ],
  
  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for performance monitoring.
  tracesSampleRate: 1.0,
  
  // Capture Replay for 10% of all sessions,
  // plus for 100% of sessions with an error
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

Core Features

Error Tracking

Capture exceptions automatically or manually:

// Automatic - uncaught errors are captured automatically
throw new Error('This will be captured');

// Manual capture
try {
  riskyOperation();
} catch (error) {
  Sentry.captureException(error);
}

// Capture a message
Sentry.captureMessage('Something went wrong', 'warning');

Context & Breadcrumbs

Add context to understand errors better:

// Set user information
Sentry.setUser({
  id: '4711',
  email: '[e-mail]',
  username: 'john_doe',
});

// Add custom tags
Sentry.setTag('page_locale', 'en-US');
Sentry.setTag('user_mode', 'admin');

// Set custom context
Sentry.setContext('character', {
  name: 'Mighty Fighter',
  level: 19,
});

// Add breadcrumbs
Sentry.addBreadcrumb({
  category: 'ui.click',
  message: 'User clicked checkout button',
  level: 'info',
});

Performance Monitoring

Browser Tracing

Track page load performance and navigation:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  integrations: [
    Sentry.browserTracingIntegration({
      // Track interactions and long tasks
      tracePropagationTargets: ['localhost', /^https:\/\/yourserver\.io\/api/],
    }),
  ],
  tracesSampleRate: 1.0,
});

Custom Performance Spans

Track specific operations:

// Start a new span
Sentry.startSpan(
  {
    name: 'expensive-operation',
    op: 'function',
  },
  () => {
    // Your code here
    processLargeDataset();
  },
);

// Manual span control
const span = Sentry.startInactiveSpan({
  name: 'database-query',
  op: 'db.query',
});

performDatabaseQuery().then(() => {
  span.end();
});

Advanced Integrations

Session Replay

Replay user sessions to understand what happened before an error:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  integrations: [
    Sentry.replayIntegration({
      // Mask all text content
      maskAllText: true,
      // Block all media elements
      blockAllMedia: true,
    }),
  ],
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

User Feedback

Collect user feedback when errors occur:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  integrations: [
    Sentry.feedbackIntegration({
      // Automatically show feedback form on error
      autoInject: true,
      colorScheme: 'light',
    }),
  ],
});

Browser Profiling

Profile JavaScript performance:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  integrations: [
    Sentry.browserProfilingIntegration(),
  ],
  profilesSampleRate: 1.0,
});

Additional Integrations

HTTP Client Monitoring

Monitor fetch and XHR requests:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  integrations: [
    Sentry.httpClientIntegration({
      // Track all requests
      failedRequestStatusCodes: [[400, 599]],
    }),
  ],
});

Context Lines

Capture source code context around errors:

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  integrations: [
    Sentry.contextLinesIntegration(),
  ],
});

Reporting Observer

Capture browser interventions and deprecations:

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  integrations: [
    Sentry.reportingObserverIntegration(),
  ],
});

CDN Installation

For quick setup without a bundler:

<script
  src="https://browser.sentry-cdn.com/8.0.0/bundle.min.js"
  integrity="sha384-..."
  crossorigin="anonymous"
></script>

<script>
  Sentry.init({
    dsn: 'YOUR_DSN_HERE',
  });
</script>

Configuration Options

Common Configuration

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  
  // Environment
  environment: 'production',
  release: 'my-app@1.0.0',
  
  // Sampling
  tracesSampleRate: 0.2,
  replaysSessionSampleRate: 0.1,
  
  // Error Filtering
  ignoreErrors: [
    'Non-Error exception captured',
    /^Script error\.?$/,
  ],
  
  // Allowlist of URLs
  allowUrls: [
    /https?:\/\/(.+\.)?example\.com/,
  ],
  
  // Denylist of URLs
  denyUrls: [
    /extensions\//i,
    /^chrome:\/\//i,
  ],
  
  // Before send hook
  beforeSend(event, hint) {
    // Modify or filter events
    if (event.exception) {
      console.log('Error captured:', hint.originalException);
    }
    return event;
  },
  
  // Before breadcrumb hook
  beforeBreadcrumb(breadcrumb, hint) {
    // Filter or modify breadcrumbs
    if (breadcrumb.category === 'ui.click') {
      return null; // Drop the breadcrumb
    }
    return breadcrumb;
  },
});

Transport & Offline Support

Handle offline scenarios:

import * as Sentry from '@sentry/browser';

Sentry.init({
  dsn: 'YOUR_DSN_HERE',
  transport: Sentry.makeBrowserOfflineTransport(Sentry.makeFetchTransport),
});

Best Practices

Initialize Early

Call Sentry.init() before any other JavaScript code runs to catch all errors.

Source Maps

Upload source maps to get readable stack traces in production.

Sampling

Use appropriate sample rates in production to control costs.

Context

Add user context and breadcrumbs to make errors easier to debug.

Next Steps

Source Maps

Learn how to upload source maps

Performance

Deep dive into performance monitoring

Session Replay

Set up session replay

User Feedback

Collect user feedback