sentry-browser-sdk

> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > 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/](https://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) ```bash # 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/](https://docs.sentry.io/platforms/javascript/guides/vue/) | | `@angular/core` | Suggest `@sentry/angular` — see [docs.sentry.io/platforms/javascript/guides/angular/](https://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/](https://docs.sentry.io/platforms/javascript/guides/svelte/) | | `@remix-run` | Suggest `@sentry/remix` — see [docs.sentry.io/platforms/javascript/guides/remix/](https://docs.sentry.io/platforms/javascript/guides/remix/) | | `nuxt` | Suggest `@sentry/nuxt` — see [docs.sentry.io/platforms/javascript/guides/nuxt/](https://docs.sentry.io/platforms/javascript/guides/nuxt/) | | `astro` | Suggest `@sentry/astro` — see [docs.sentry.io/platforms/javascript/guides/astro/](https://docs.sentry.io/platforms/javascript/guides/astro/) | | `ember-source` | Suggest `@sentry/ember` — see [docs.sentry.io/platforms/javascript/guides/ember/](https://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 ```bash # 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 ```bash 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: ```typescript 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: ```typescript // 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`):** ```typescript 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`):** ```javascript 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`):** ```javascript 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`):** ```javascript 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, }), ], }); ```