> ## Documentation Index
> Fetch the complete documentation index at: https://sentrydocs.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript SDK
> Install and configure Sentry in JavaScript and TypeScript applications
Sentry provides first-class JavaScript SDK support for browsers, Node.js, and every major framework. All packages live under the `@sentry` npm scope.
## Choose your package
Vanilla browser apps and any framework not listed here.
Node.js servers, scripts, and serverless functions.
Next.js apps (App Router and Pages Router). Instruments both client and server.
React apps. Adds `ErrorBoundary` and component stack traces.
Vue 3 (and Vue 2) applications.
Angular applications. Instruments the Angular ErrorHandler.
## Installation
```bash theme={null}
npm install @sentry/browser
```
```bash theme={null}
npm install @sentry/node
```
```bash theme={null}
npm install @sentry/nextjs
npx @sentry/wizard -i nextjs
```
The wizard creates the required config files and wraps your Next.js config automatically.
```bash theme={null}
npm install @sentry/react
```
```bash theme={null}
npm install @sentry/vue
```
```bash theme={null}
npm install @sentry/angular
```
## Basic initialization
Call `Sentry.init()` as early as possible — before any other application code runs.
```javascript browser (main.js) theme={null}
import * as Sentry from "@sentry/browser";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
environment: "production",
release: "my-app@1.0.0",
tracesSampleRate: 1.0,
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
});
```
```javascript node (instrument.js) theme={null}
import * as Sentry from "@sentry/node";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
environment: "production",
release: "my-app@1.0.0",
tracesSampleRate: 1.0,
});
```
```typescript next.js (sentry.client.config.ts) theme={null}
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
environment: process.env.NODE_ENV,
release: process.env.NEXT_PUBLIC_RELEASE,
tracesSampleRate: 1.0,
replaysOnErrorSampleRate: 1.0,
});
```
For Node.js, import `instrument.js` at the very top of your entry point using `--import ./instrument.js` (ESM) or `require('./instrument.js')` (CJS) so Sentry initializes before any other modules load.
## Capturing errors
### Automatic capture
Once initialized, Sentry automatically captures unhandled exceptions and promise rejections. No additional code is needed for those.
### Manual capture
```javascript theme={null}
try {
processOrder(cart);
} catch (error) {
Sentry.captureException(error);
}
```
### Capture a message
```javascript theme={null}
Sentry.captureMessage("Payment processor returned an unexpected status", "warning");
```
The second argument sets the severity level: `"fatal"`, `"error"`, `"warning"`, `"info"`, or `"debug"`.
## Setting context
Context enriches events so you can filter and search in Sentry.
```javascript theme={null}
// Identify the current user
Sentry.setUser({ id: "42", email: "user@example.com" });
// Add a searchable tag
Sentry.setTag("section", "checkout");
// Add arbitrary extra data (not indexed)
Sentry.setExtra("orderId", "12345");
```
To clear user context (e.g., after sign-out):
```javascript theme={null}
Sentry.setUser(null);
```
## Breadcrumbs
Breadcrumbs are a trail of events captured before an error occurs. Sentry automatically records navigation, console output, XHR requests, and DOM clicks. You can also add custom breadcrumbs:
```javascript theme={null}
Sentry.addBreadcrumb({
message: "User clicked the checkout button",
category: "ui.click",
level: "info",
data: {
cartItems: 3,
},
});
```
## Performance monitoring
Use transactions and spans to measure performance across operations.
```javascript theme={null}
// Wrap code in a span — Sentry creates the transaction automatically
await Sentry.startSpan(
{ name: "checkout", op: "task" },
async () => {
await Sentry.startSpan(
{ op: "http.request", name: "POST /api/order" },
async () => {
await submitOrder(cart);
}
);
}
);
```
For automatic instrumentation of `fetch`, `XMLHttpRequest`, and browser navigation, include the `BrowserTracing` integration (built into `@sentry/browser` in SDK v8+):
```javascript theme={null}
import * as Sentry from "@sentry/browser";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [Sentry.browserTracingIntegration()],
tracesSampleRate: 1.0,
});
```
## React error boundary
Wrap components with `ErrorBoundary` to catch rendering errors and display a fallback UI:
```jsx theme={null}
import { ErrorBoundary } from "@sentry/react";
function App() {
return (
Something went wrong. Please refresh the page.}>
);
}
```
You can also pass a `onError` callback to run custom logic when the boundary catches:
```jsx theme={null}
}
onError={(error, componentStack) => {
analytics.track("render_error", { error: error.message });
}}
>
```
## Filtering events with beforeSend
Use `beforeSend` to inspect, modify, or drop events before they leave the browser:
```javascript theme={null}
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
beforeSend(event, hint) {
// Drop events from browser extensions
if (event.exception?.values?.[0]?.stacktrace?.frames?.some(
(f) => f.filename?.includes("chrome-extension://")
)) {
return null;
}
// Scrub a sensitive field
if (event.user) {
delete event.user.email;
}
return event;
},
});
```
Return `null` to drop the event entirely. Return the (modified) event to send it.
## Source maps
Source maps let Sentry show original TypeScript or minified source in stack traces. Upload them during your build:
```bash theme={null}
npx @sentry/cli releases files my-app@1.0.0 upload-sourcemaps ./dist
```
Use the `@sentry/vite-plugin` or `@sentry/webpack-plugin` to upload source maps automatically on every build.