The @sentry/browser package provides error tracking and performance monitoring for browser JavaScript applications.
Prerequisites
- Node.js 18 or newer
- A Sentry account and project DSN
Installation
Install the Package
Install @sentry/browser using your preferred package manager:npm install @sentry/browser
Initialize Sentry
Initialize Sentry as early as possible in your application. Call Sentry.init() before any other code runs:import * as Sentry from '@sentry/browser';
Sentry.init({
dsn: 'YOUR_DSN_HERE',
// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for tracing.
tracesSampleRate: 1.0,
// Set `tracePropagationTargets` to control what URLs
// distributed tracing should be enabled for
tracePropagationTargets: ['localhost', /^https:\/\/yourserver\.io\/api/],
});
The dsn (Data Source Name) tells the SDK where to send events. You can find your DSN in your Sentry project settings.
Verify Installation
Test that Sentry is working by triggering a test error:// This will create an error and send it to Sentry
Sentry.captureException(new Error('Test error'));
Usage
Capturing Errors
Capture exceptions manually:
import * as Sentry from '@sentry/browser';
try {
// Your code that might throw
someFunctionThatMightFail();
} catch (error) {
Sentry.captureException(error);
}
Setting Context
Add context information to events:
import * as Sentry from '@sentry/browser';
// Set user information
Sentry.setUser({
id: '4711',
email: '[email protected]',
username: 'john_doe'
});
// Set custom tags
Sentry.setTag('user_mode', 'admin');
Sentry.setTag('page_locale', 'en-us');
// Set extra context data
Sentry.setExtra('battery', 0.7);
Sentry.setContext('application_area', {
location: 'checkout'
});
Adding Breadcrumbs
Breadcrumbs help trace user actions leading to an error:
import * as Sentry from '@sentry/browser';
Sentry.addBreadcrumb({
message: 'User clicked checkout button',
category: 'action',
level: 'info',
});
import * as Sentry from '@sentry/browser';
Sentry.init({
dsn: 'YOUR_DSN_HERE',
integrations: [
Sentry.browserTracingIntegration(),
],
tracesSampleRate: 1.0,
});
Session Replay
Capture session replays to see what users experienced:
import * as Sentry from '@sentry/browser';
Sentry.init({
dsn: 'YOUR_DSN_HERE',
integrations: [
Sentry.replayIntegration({
maskAllText: true,
blockAllMedia: true,
}),
],
// Session Replay sample rate
replaysSessionSampleRate: 0.1,
// Session Replay sample rate when an error occurs
replaysOnErrorSampleRate: 1.0,
});
Advanced Configuration
Environment Configuration
Sentry.init({
dsn: 'YOUR_DSN_HERE',
environment: process.env.NODE_ENV || 'development',
release: '[email protected]',
});
Filtering Events
Control which errors are sent to Sentry:
Sentry.init({
dsn: 'YOUR_DSN_HERE',
beforeSend(event, hint) {
// Don't send errors that contain specific text
if (event.exception?.values?.[0]?.value?.includes('Non-Error')) {
return null;
}
return event;
},
});
Custom Integrations
import * as Sentry from '@sentry/browser';
Sentry.init({
dsn: 'YOUR_DSN_HERE',
integrations: [
Sentry.browserTracingIntegration(),
Sentry.replayIntegration(),
Sentry.captureConsoleIntegration({
levels: ['error'],
}),
Sentry.httpClientIntegration(),
],
});
CDN Installation
You can also load Sentry directly from a CDN without npm/yarn:
<script
src="https://browser.sentry-cdn.com/10.42.0/bundle.min.js"
integrity="sha384-..."
crossorigin="anonymous"
></script>
<script>
Sentry.init({
dsn: 'YOUR_DSN_HERE',
});
</script>
Troubleshooting
Source Maps
For production builds, upload source maps to get readable stack traces:
- Install the Sentry Webpack plugin or Vite plugin
- Configure your build tool to generate source maps
- Upload source maps during your build process
Bundle Size
The browser SDK is optimized for tree-shaking. Only import what you need:
// Instead of importing everything
import * as Sentry from '@sentry/browser';
// Import only what you need
import { init, captureException } from '@sentry/browser';
Be mindful of bundle size when adding integrations. Each integration adds to your bundle. Only enable integrations you actually use.
Next Steps
