sentry-browser-sdk

All Skills > SDK Setup > Browser SDK

Sentry Browser SDK

Opinionated wizard that scans your project and guides you through complete Sentry setup for browser JavaScript — vanilla JS, jQuery, static sites, WordPress, and any JS project without a framework-specific SDK.

Invoke This Skill When

• User asks to "add Sentry to a website" or set up Sentry for plain JavaScript
• User wants to install @sentry/browser or configure the Loader Script
• User has a WordPress, Shopify, Squarespace, or static HTML site
• User wants error monitoring, tracing, session replay, or logging without a framework
• No framework-specific SDK applies

Note: SDK versions and APIs below reflect @sentry/browser ≥10.0.0. Always verify against docs.sentry.io/platforms/javascript/ before implementing.

---

Phase 1: Detect

CRITICAL — Check for frameworks first. Framework-specific SDKs provide significantly better coverage and must be recommended before proceeding with @sentry/browser.

Step 1A: Framework Detection (Redirect If Found)

# Check for React
cat package.json 2>/dev/null | grep -E '"react"'

# Check for Next.js
cat package.json 2>/dev/null | grep '"next"'

# Check for Vue
cat package.json 2>/dev/null | grep '"vue"'

# Check for Angular
cat package.json 2>/dev/null | grep '"@angular/core"'

# Check for Svelte / SvelteKit
cat package.json 2>/dev/null | grep -E '"svelte"|"@sveltejs/kit"'

# Check for Remix
cat package.json 2>/dev/null | grep -E '"@remix-run/react"|"@remix-run/node"'

# Check for Nuxt
cat package.json 2>/dev/null | grep '"nuxt"'

# Check for Astro
cat package.json 2>/dev/null | grep '"astro"'

# Check for Ember
cat package.json 2>/dev/null | grep '"ember-source"'

# Check for Node.js server frameworks (wrong SDK entirely)
cat package.json 2>/dev/null | grep -E '"express"|"fastify"|"@nestjs/core"|"koa"'

If a framework is detected, stop and redirect:

Framework detected	Redirect to
next	Load sentry-nextjs-sdk skill — do not proceed here
react (without Next.js)	Load sentry-react-sdk skill — do not proceed here
vue	Suggest @sentry/vue — see docs.sentry.io/platforms/javascript/guides/vue/
@angular/core	Suggest @sentry/angular — see docs.sentry.io/platforms/javascript/guides/angular/
@sveltejs/kit	Load sentry-svelte-sdk skill — do not proceed here
svelte (SPA, no kit)	Suggest @sentry/svelte — see docs.sentry.io/platforms/javascript/guides/svelte/
@remix-run	Suggest @sentry/remix — see docs.sentry.io/platforms/javascript/guides/remix/
nuxt	Suggest @sentry/nuxt — see docs.sentry.io/platforms/javascript/guides/nuxt/
astro	Suggest @sentry/astro — see docs.sentry.io/platforms/javascript/guides/astro/
ember-source	Suggest @sentry/ember — see docs.sentry.io/platforms/javascript/guides/ember/
express / fastify / @nestjs/core	This is a Node.js server — load sentry-node-sdk or sentry-nestjs-sdk skill

Why redirect matters: Framework SDKs add router-aware transactions, error boundaries, component tracking, and often SSR coverage. Using @sentry/browser directly in a React or Next.js app loses all of that.

Only continue with @sentry/browser if no framework is detected.

Step 1B: Installation Method Detection

# Check if there's a package.json at all (bundler environment)
ls package.json 2>/dev/null

# Check package manager
ls package-lock.json yarn.lock pnpm-lock.yaml bun.lockb 2>/dev/null

# Check build tool
ls vite.config.ts vite.config.js webpack.config.js rollup.config.js esbuild.config.js 2>/dev/null
cat package.json 2>/dev/null | grep -E '"vite"|"webpack"|"rollup"|"esbuild"'

# Check for CMS or static site indicators
ls wp-config.php wp-content/ 2>/dev/null   # WordPress
ls _config.yml _config.yaml 2>/dev/null    # Jekyll
ls config.toml 2>/dev/null                 # Hugo
ls .eleventy.js 2>/dev/null                # Eleventy

# Check for existing Sentry
cat package.json 2>/dev/null | grep '"@sentry/'
grep -r "sentry-cdn.com\|js.sentry-cdn.com" . --include="*.html" -l 2>/dev/null | head -3

What to determine:

Question	Impact
package.json exists + bundler?	→ Path A: npm install
WordPress, Shopify, static HTML, no npm?	→ Path B: Loader Script
Script tags only, no Loader Script access?	→ Path C: CDN bundle
Already has @sentry/browser?	Skip install, go straight to feature config
Build tool is Vite / webpack / Rollup / esbuild?	Source maps plugin to configure

---

Phase 2: Recommend

Present a recommendation based on what you found. Lead with a concrete proposal, don't ask open-ended questions.

Recommended (core coverage):

• ✅ Error Monitoring — always; captures unhandled errors and promise rejections
• ✅ Tracing — recommended for any interactive site; tracks page load and user interactions
• ✅ Session Replay — recommended for user-facing apps; records sessions around errors

Optional (enhanced observability):

• ⚡ User Feedback — capture reports directly from users after errors
• ⚡ Logging — structured logs via Sentry.logger.*; requires npm or CDN logs bundle (not available via Loader Script)
• ⚡ Profiling — JS Self-Profiling API; beta, Chromium-only, requires Document-Policy: js-profiling response header

Feature recommendation logic:

Feature	Recommend when...
Error Monitoring	Always — non-negotiable baseline
Tracing	Always for interactive pages — page load + navigation spans are high-value
Session Replay	User-facing app, support flows, or checkout pages
User Feedback	Support-focused app; want in-app bug reports with screenshots
Logging	Structured log search or log-to-trace correlation needed; npm path only
Profiling	Performance-critical, Chromium-only app; Document-Policy: js-profiling header required

Installation path recommendation:

Scenario	Recommended path
Project has package.json + bundler	Path A (npm) — full features, source maps, tree-shaking
WordPress, Shopify, Squarespace, static HTML	Path B (Loader Script) — zero build tooling, always up to date
Static HTML without Loader Script access	Path C (CDN bundle) — manual <script> tag

Propose: "I recommend setting up Error Monitoring + Tracing + Session Replay using Path A (npm). Want me to also add Logging or User Feedback?"

---

Phase 3: Guide

Path A: npm / yarn / pnpm (Recommended — Bundler Projects)

Install

npm install @sentry/browser --save
# or
yarn add @sentry/browser
# or
pnpm add @sentry/browser

Create src/instrument.ts

Sentry must initialize before any other code runs. Put Sentry.init() in a dedicated sidecar file:

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

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN, // Adjust per build tool (see table below)
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_APP_VERSION, // inject at build time

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },

  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],

  // Tracing
  tracesSampleRate: 1.0, // lower to 0.1–0.2 in production
  tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],

  // Session Replay
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  enableLogs: true,
});

DSN environment variable by build tool:

Build Tool	Variable Name	Access in code
Vite	VITE_SENTRY_DSN	import.meta.env.VITE_SENTRY_DSN
Custom webpack	SENTRY_DSN	process.env.SENTRY_DSN
esbuild	SENTRY_DSN	process.env.SENTRY_DSN
Rollup	SENTRY_DSN	process.env.SENTRY_DSN

Entry Point Setup

Import instrument.ts as the very first import in your entry file:

// src/main.ts or src/index.ts
import "./instrument";  // ← MUST be first

// ... rest of your app

Source Maps Setup (Strongly Recommended)

Without source maps, stack traces show minified code. Set up the build plugin to upload source maps automatically:

No dedicated browser wizard: There is no npx @sentry/wizard -i browser flag. The closest is npx @sentry/wizard@latest -i sourcemaps which configures source map upload only for an already-initialized SDK.

Vite (vite.config.ts):

import { defineConfig } from "vite";
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
  build: { sourcemap: "hidden" },
  plugins: [
    // sentryVitePlugin MUST be last
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

webpack (webpack.config.js):

const { sentryWebpackPlugin } = require("@sentry/webpack-plugin");

module.exports = {
  devtool: "hidden-source-map",
  plugins: [
    sentryWebpackPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
};

Rollup (rollup.config.js):

import { sentryRollupPlugin } from "@sentry/rollup-plugin";

export default {
  output: { sourcemap: "hidden" },
  plugins: [
    sentryRollupPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
};

esbuild (build.js):

const { sentryEsbuildPlugin } = require("@sentry/esbuild-plugin");

require("esbuild").build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  sourcemap: "hidden",
  plugins: [
    sentryEsbuildPlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

⚠️ esbuild plugin does not fully support splitting: true. Use sentry-cli instead if code splitting is enabled.

Using sentry-cli (any toolchain / CI):

# After your build step:
npx @sentry/cli sourcemaps inject ./dist
npx @sentry/cli sourcemaps upload ./dist

Add .env for auth (never commit):

SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=my-org-slug
SENTRY_PROJECT=my-project-slug

---

Path B: Loader Script (WordPress, Static Sites, Shopify, Squarespace)

Best for: Sites without a build system. The Loader Script is a single <script> tag that lazily loads the full SDK, always stays up to date via Sentry's CDN, and buffers errors before the SDK loads.

Get the Loader Script: Sentry UI → Settings → Projects → (your project) → SDK Setup → Loader Script

Copy the generated tag and place it as the first script on every page:

<!DOCTYPE html>
<html>
  <head>
    <!-- Configure BEFORE the loader tag -->
    <script>
      window.sentryOnLoad = function () {
        Sentry.init({
          // DSN is already configured in the loader URL
          tracesSampleRate: 1.0,
          replaysSessionSampleRate: 0.1,
          replaysOnErrorSampleRate: 1.0,
        });
      };
    </script>

    <!-- Loader Script FIRST — before all other scripts -->
    <script
      src="https://js.sentry-cdn.com/YOUR_PUBLIC_KEY.min.js"
      crossorigin="anonymous"
    ></script>
  </head>
  ...
</html>

Loader loading modes:

Mode	How	When SDK loads
Lazy (default)	Nothing extra	On first error or manual Sentry call
Eager	Add data-lazy="no" to <script>	After all page scripts finish
Manual	Call Sentry.forceLoad()	Whenever you call it

Safe to call before SDK loads (buffered):

• Sentry.captureException()
• Sentry.captureMessage()
• Sentry.captureEvent()
• Sentry.addBreadcrumb()
• Sentry.withScope()

For other methods, use Sentry.onLoad():

<script>
  window.Sentry && Sentry.onLoad(function () {
    Sentry.setUser({ id: "123" });
  });
</script>

Set release via global (optional):

<script>
  window.SENTRY_RELEASE = { id: "[email protected]" };
</script>

Loader Script limitations:

• ❌ No Sentry.logger.* (logging) — npm path only
• ❌ No framework-specific features (React ErrorBoundary, Vue Router tracking, etc.)
• ❌ Tracing headers only added to fetch calls made after SDK loads
• ❌ Version changes take a few minutes to propagate via CDN cache
• ⚠️ Use defer (not async) on all other scripts when using the loader

CSP requirements:

script-src: https://browser.sentry-cdn.com https://js.sentry-cdn.com
connect-src: *.sentry.io

---

Path C: CDN Bundles (Manual Script Tags)

Best for: Pages that can't use the Loader Script but need synchronous loading.

Pick the bundle that matches your feature needs and place it before all other scripts:

Errors only (minimal footprint):

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

Errors + Tracing:

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

Errors + Session Replay:

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

Errors + Tracing + Replay (recommended full setup):

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.min.js"
  integrity="sha384-oo2U4zsTxaHSPXJEnXtaQPeS4Z/qbTqoBL9xFgGxvjJHKQjIrB+VRlu97/iXBtzw"
  crossorigin="anonymous"
></script>

Errors + Tracing + Replay + User Feedback:

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.feedback.min.js"
  integrity="sha384-SmHU39Qs9cua0KLtq3A6gis1/cqM1nZ6fnGzlvWAPiwhBDO5SmwFQV65BBpJnB3n"
  crossorigin="anonymous"
></script>

Full bundle (all features):

<script
  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.feedback.logs.metrics.min.js"
  integrity="sha384-gOjSzRxwpXpy0FlT6lg/AVhagqrsUrOWUO7jm6TJwuZ9YVHtYK0MBA2hW2FGrIGl"
  crossorigin="anonymous"
></script>

CDN bundle variants summary:

Bundle	Features	When to use
bundle.min.js	Errors only	Absolute minimum footprint
bundle.tracing.min.js	+ Tracing	Performance monitoring
bundle.replay.min.js	+ Replay	Session recording
bundle.tracing.replay.min.js	+ Tracing + Replay	Full observability
bundle.tracing.replay.feedback.min.js	+ User Feedback	+ in-app feedback widget
bundle.logs.metrics.min.js	+ Logs + Metrics	Structured logs (CDN)
bundle.tracing.replay.feedback.logs.metrics.min.js	Everything	Max coverage

Initialize after the script tag:

<script>
  Sentry.init({
    dsn: "https://[email protected]/YOUR_PROJECT",
    environment: "production",
    release: "[email protected]",
    integrations: [
      Sentry.browserTracingIntegration(),
      Sentry.replayIntegration({
        maskAllText: true,
        blockAllMedia: true,
      }),
    ],
    tracesSampleRate: 1.0,
    tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/],
    replaysSessionSampleRate: 0.1,
    replaysOnErrorSampleRate: 1.0,
  });
</script>

CDN CSP requirements:

script-src: https://browser.sentry-cdn.com https://js.sentry-cdn.com
connect-src: *.sentry.io

---

For Each Agreed Feature

Walk through features one at a time. Load the reference file, follow its steps, verify before moving on:

Feature	Reference	Load when...
Error Monitoring	${SKILL_ROOT}/references/error-monitoring.md	Always (baseline)
Tracing	${SKILL_ROOT}/references/tracing.md	Page load / API call tracing
Session Replay	${SKILL_ROOT}/references/session-replay.md	User-facing app
Logging	${SKILL_ROOT}/references/logging.md	Structured log search; npm or CDN logs bundle (not Loader Script)
Profiling	${SKILL_ROOT}/references/profiling.md	Performance-critical, Chromium-only
User Feedback	${SKILL_ROOT}/references/user-feedback.md	Capture user reports after errors

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

---

Configuration Reference

Key Sentry.init() Options

Option	Type	Default	Notes
dsn	string	—	Required. SDK disabled when empty
environment	string	"production"	e.g., "staging", "development"
release	string	—	e.g., "[email protected]" or git SHA — links errors to releases
sendDefaultPii	boolean	false	Includes IP addresses and request headers. Will be deprecated in v11 — use dataCollection instead
dataCollection	object	—	Fine-grained control over collected data (v10.54+). See table below
tracesSampleRate	number	—	0–1; 1.0 in dev, 0.1–0.2 in prod
tracesSampler	function	—	Per-transaction sampling; overrides rate
tracePropagationTargets	(string|RegExp)[]	same-origin	Outgoing URLs that receive distributed tracing headers
replaysSessionSampleRate	number	—	Fraction of all sessions recorded
replaysOnErrorSampleRate	number	—	Fraction of error sessions recorded
enableLogs	boolean	false	Enable Sentry.logger.* API (npm or CDN logs bundle; not Loader Script)
attachStackTrace	boolean	false	Stack traces on captureMessage() calls
maxBreadcrumbs	number	100	Breadcrumbs stored per event
debug	boolean	false	Verbose SDK output to console
tunnel	string	—	Proxy URL to bypass ad blockers
ignoreErrors	(string|RegExp)[]	[]	Drop errors matching these patterns
denyUrls	(string|RegExp)[]	[]	Drop errors from scripts at these URLs
allowUrls	(string|RegExp)[]	[]	Only capture errors from these script URLs
spotlight	boolean|string	false	Forward events to Spotlight local dev overlay

Browser-Specific Options

Option	Type	Default	Notes
cdnBaseUrl	string	—	Base URL for lazy-loading integrations
skipBrowserExtensionCheck	boolean	false	Skip check for browser extension context

dataCollection Option (v10.54+)

Fine-grained control over what data the SDK collects. Replaces the simple sendDefaultPii boolean with granular settings. When omitted, falls back to sendDefaultPii for backwards compatibility.

Field	Type	Default	Notes
userInfo	boolean	true	Auto-populate user.* fields from instrumentation
cookies	boolean | { allow: string[] } | { deny: string[] }	true	Cookie collection; true = all (filtered), false = none, allow/deny = specific keys
httpHeaders	{ request?, response? }	{ request: true, response: true }	HTTP header collection; each can be boolean or allow/deny object
httpBodies	string[]	["incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse"]	HTTP body types to collect (when dataCollection is explicitly set)
queryParams	boolean | { allow: string[] } | { deny: string[] }	true	Query parameter collection with sensitive value filtering
genAI	{ inputs?, outputs? }	{ inputs: true, outputs: true }	Generative AI input/output recording
stackFrameVariables	boolean	true	Capture local variable values in stack frames
frameContextLines	number	5	Source code context lines around stack frames

Example:

Sentry.init({
  dsn: "...",
  dataCollection: {
    userInfo: true,
    cookies: { deny: ["session_id", "auth_token"] },
    httpHeaders: {
      request: { deny: ["authorization", "cookie"] },
      response: true,
    },
    queryParams: { allow: ["utm_source", "utm_campaign"] },
  },
});

window.SENTRY_RELEASE Global (CDN / Loader Path)

Set the release version before the SDK loads:

<script>
  window.SENTRY_RELEASE = { id: "[email protected]" };
</script>

---

Verification

Trigger test events to confirm Sentry is receiving data:

npm / CDN path:

<!-- Add temporarily to your page -->
<button onclick="throw new Error('Sentry Browser Test Error')">
  Test Error
</button>

Performance verification (npm path):

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

Sentry.startSpan({ name: "Test Span", op: "test" }, () => {
  // your operation
});

Manual capture:

Sentry.captureException(new Error("Manual test"));
Sentry.captureMessage("Manual test message", "info");

Check the Sentry dashboard:

• Issues → error appears within seconds
• Traces → page load transaction visible
• Replays → session recording visible after page interaction
• Logs → structured log entries if logging enabled (npm or CDN logs bundle)

Set debug: true in Sentry.init() and check the browser console if nothing appears.

---

Phase 4: Cross-Link

After completing browser setup, check for a companion backend missing Sentry coverage:

ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod 2>/dev/null | head -3
cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3
cat ../Gemfile 2>/dev/null | head -3
cat ../pom.xml 2>/dev/null | grep '<artifactId>' | head -3
cat ../composer.json 2>/dev/null | head -3

If a backend exists without Sentry configured, suggest the matching skill:

Backend detected	Suggest skill
Go (go.mod)	sentry-go-sdk
Python (requirements.txt, pyproject.toml)	sentry-python-sdk
Ruby (Gemfile)	sentry-ruby-sdk
PHP (composer.json)	sentry-php-sdk
.NET (*.csproj, *.sln)	sentry-dotnet-sdk
Java (pom.xml, build.gradle)	See docs.sentry.io/platforms/java/
Node.js (Express, Fastify)	sentry-node-sdk
NestJS (@nestjs/core)	sentry-nestjs-sdk

---

Troubleshooting

Issue	Solution
Events not appearing	Set debug: true, check DSN, open browser console for SDK errors
Source maps not working	Build in production mode (npm run build); verify SENTRY_AUTH_TOKEN is set
Minified stack traces	Source maps not uploading — check build plugin config; run npx @sentry/wizard@latest -i sourcemaps
CDN bundle not found	Check version number in URL; see browser.sentry-cdn.com for latest
SRI integrity error	Hash mismatch — re-copy the full <script> tag including integrity attribute from this skill
Loader Script not firing	Verify it's the first <script> on the page; check for CSP errors in console
Tracing not working with Loader	Fetch calls before SDK loads won't be traced — wrap early calls in Sentry.onLoad()
sentryOnLoad not called	Must define window.sentryOnLoad before the loader <script> tag
Logging not available	Sentry.logger.* requires npm or a CDN bundle with .logs. in its name — not supported via Loader Script
Profiling not working	Verify Document-Policy: js-profiling header on document responses; Chromium-only
Ad blockers dropping events	Set tunnel: "/sentry-tunnel" and add a server-side relay endpoint
Session replay not recording	Confirm replayIntegration() is in init; check replaysSessionSampleRate > 0
Replay CSP errors	Add worker-src 'self' blob: and child-src 'self' blob: to your CSP
tracePropagationTargets not matching	Check regex escaping; default is same-origin only
Events blocked by browser extension	Add denyUrls: [/chrome-extension:\/\//] to filter extension errors
High event volume	Lower sampleRate (errors) and tracesSampleRate from 1.0 in production
Source maps uploaded after deploy	Source maps must be uploaded before errors occur — integrate into CI/CD
esbuild splitting conflict	sentryEsbuildPlugin doesn't support splitting: true — use sentry-cli instead