Configure Error Tracking

1. Audit current state

grep -E '"(@sentry/react|@sentry/vue|@sentry/vite-plugin)"' package.json 2>/dev/null
ls src/libs/error-reporter.ts src/libs/sentry.ts .claude/stack-profile.md 2>/dev/null
grep -rn "VITE_SENTRY_DSN\|VITE_RELEASE" src/ .env* 2>/dev/null | head

Read .claude/stack-profile.md if present: observability.backend other than sentry (e.g. signoz, grafana-lgtm) means this skill does not apply; keep the console stub and follow ../../core/_shared/observability.md. frontend.framework picks the SDK; package_manager replaces pnpm.

Prerequisite: set-up-error-boundaries created src/libs/error-reporter.ts with captureError. This skill swaps that function's body from a console stub to Sentry: a one-file change, which is what the seam is for. No seam, no Sentry: run that skill first.

2. Decide what to do

• No Sentry → full setup (steps 4–8).
• Sentry present but captureError still logs to the console → wire the seam (step 6).
• Wired but no source-map upload → add the Vite plugin (step 7).
• Sentry on v10 config (sendDefaultPii) after an upgrade to 11 → replace it with dataCollection (step 5): v11 collects more by default.

3. Detect framework

React → @sentry/react. Vue → @sentry/vue (init takes the app instance).

4. Install

pnpm add @sentry/react          # Vue: @sentry/vue
pnpm add -D @sentry/vite-plugin

Both 11.x / 5.x as of 2026-10-09 (../_shared/stack-versions.md).

5. Initialize Sentry (no-op without a DSN)

Add two optional keys to the validate-env schema (VITE_SENTRY_DSN is already there; add VITE_RELEASE: z.preprocess(blankToUndefined, z.string().min(1).optional())).

// src/libs/sentry.ts (React)
import * as Sentry from '@sentry/react';
import { env } from '@/libs/env';

export function initSentry(): void {
  if (!env.VITE_SENTRY_DSN) return; // no DSN: do nothing (local dev, forks, tests)

  Sentry.init({
    dsn: env.VITE_SENTRY_DSN,
    environment: import.meta.env.MODE,
    release: env.VITE_RELEASE, // the same value the Vite plugin uploads maps under
    integrations: [
      Sentry.browserTracingIntegration(),
      Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true }),
    ],
    tracesSampleRate: import.meta.env.PROD ? 0.1 : 1.0,
    replaysSessionSampleRate: import.meta.env.PROD ? 0.1 : 0,
    replaysOnErrorSampleRate: 1.0,
    // v11 collects cookies, headers, bodies and user info unless told not to; opt out explicitly.
    dataCollection: { userInfo: false, cookies: false, httpHeaders: false, httpBodies: [] },
  });
}

Call it before rendering, first thing in the entry (src/main.tsx): import { initSentry } from '@/libs/sentry'; initSentry();, and delete installGlobalErrorHandlers(): the SDK installs its own window handlers by default, and keeping both reports twice.

Vue: the same file with import * as Sentry from '@sentry/vue', import type { App } from 'vue', export function initSentry(app: App) and app, as the first Sentry.init option. In main.ts: const app = createApp(App); initSentry(app);, and delete the app.config.errorHandler line and installGlobalErrorHandlers(): init({ app }) attaches Sentry's own error handler.

dataCollection matters: Sentry 11 replaced sendDefaultPii (a type error now) with dataCollection, and its defaults collect user info, cookies, headers and request/response bodies. The line above restores the restrictive v10 behaviour for a browser SPA (error-tracking.md).

6. Wire the captureError seam

Replace the stub body; the boundaries and every other caller stay unchanged:

// src/libs/error-reporter.ts
import * as Sentry from '@sentry/react'; // Vue: '@sentry/vue'

export type ErrorContext = {
  componentStack?: string | undefined;
  url?: string | undefined;
  user?: { id: string } | undefined;
};

export function captureError(error: unknown, context: ErrorContext = {}): void {
  // Without a DSN Sentry drops the event silently; keep the error visible in development.
  if (import.meta.env.DEV) console.error('[captureError]', error, context);
  Sentry.captureException(error, { contexts: { app: context } });
}

Remove installGlobalErrorHandlers from the file once its call is gone (step 5).

7. Upload source maps

// vite.config.ts
import { sentryVitePlugin } from '@sentry/vite-plugin';

const uploadMaps = Boolean(process.env.SENTRY_AUTH_TOKEN);

export default defineConfig({
  // Hidden maps are written but not referenced by the bundle; without an upload they would
  // sit in dist/ and ship, so emit them only when the plugin will upload and delete them.
  build: { sourcemap: uploadMaps ? 'hidden' : false },
  plugins: [
    // ...react(), tailwindcss(), etc.
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN, // build-time secret: never VITE_-prefixed
      release: { name: process.env.VITE_RELEASE }, // must equal the SDK's `release`
      sourcemaps: { filesToDeleteAfterUpload: ['./dist/**/*.map'] },
      disable: !uploadMaps,
    }),
  ],
});

8. Environment

# .env (the DSN is a public client key, safe to commit): VITE_SENTRY_DSN=https://<key>@o0.ingest.sentry.io/0
# CI only, no VITE_ prefix:  SENTRY_ORG  SENTRY_PROJECT  SENTRY_AUTH_TOKEN
# CI build step:             VITE_RELEASE=$(git rev-parse --short HEAD) pnpm build

9. Verify

pnpm typecheck
VITE_RELEASE=test pnpm build          # no token: builds, no .map files in dist/, plugin disabled
SENTRY_AUTH_TOKEN=… VITE_RELEASE=… pnpm build   # in CI: uploads, then dist/ holds no .map files
find dist -name '*.map' | wc -l       # expect 0 in both cases

Trigger a test error (a throw inside an ErrorBoundary) in a DSN-configured build and confirm it lands in Sentry de-minified, with the release and environment tags and no cookies or request headers on the event.

References

• ./error-tracking.md — data collection, sampling, source-map handling, release tagging, no-op without a DSN, provider swap.
• ../set-up-error-boundaries/SKILL.md — the captureError seam this wires.
• ../_shared/stack-versions.md — Sentry SDK and plugin lines.
• ../_shared/conventions.md — libs/ seam location.