17 KiB
Sentry Wiring — Web (React Router v7)
Status: completed Task-ID: #31 Phase: 02 Estimated Effort: 1-1.5 Tage Owner: unassigned
Problem
apps/web/ (React Router v7 Framework Mode) hat keine Sentry-Initialisierung — weder client-seitig (entry.client.tsx) noch server-seitig (entry.server.tsx). Damit:
- Frontend-Crashes verschwinden in der Browser-Konsole des Users — kein Aggregat, keine Reproduktion
- SSR-Loader/Action-Fehler landen nur im Container-Log
- Keine Session-Replays für Bug-Reports
- Kein Route-Level-Tracing (welche Routes sind langsam?)
- Source-Maps werden im Build erzeugt aber nirgendwo hochgeladen → Stack-Traces wären auch mit Sentry unleserlich (Minified)
Konkrete Codestellen (zu editieren):
apps/web/app/entry.client.tsx— Sentry.init für Browser-Sideapps/web/app/entry.server.tsx— Sentry.init für Node-SSR-Sideapps/web/app/root.tsx—ErrorBoundaryruft aktuell nichts Reporter-mäßigesapps/web/vite.config.ts— Sentry-Vite-Plugin für Source-Map-Upload
Depends on
02-observability/sentry-selfhost-setup.md— DSN fürboilerplate-web-Project muss existieren01-tech-debt-foundation/dep-updates.md—@sentry/react-routerv8.x braucht aktuellen React-Router-v7-Compatibility-Layer
Blocks
02-observability/sentry-ci-integration.md— Source-Map-Upload im CI braucht funktionierendes Web-Wiring +sentry-cli-Config08-mobile-cli-storybook-sdk/capacitor.md— Mobile-Capacitor-App soll dasselbe DSN-Pattern wiederverwenden
Approach
Gewählt: Sentry-React-SDK (@sentry/react v8.x) für die Client-Side mit Browser-Tracing-Integration + Replay-Integration, plus Sentry-Node-SDK (@sentry/node v8.x) für die SSR-Side mit requestDataIntegration. React-Router v7 hat keine offizielle Sentry-Integration (Stand 2026-05); wir nutzen die generische Browser-Tracing-Integration und wrappen den <Outlet /> manuell für Route-Level-Spans (oder warten auf das @sentry/react-router Package — wenn es zum Implementation-Zeitpunkt verfügbar ist, das nehmen).
PII-Strategie: Replay-Masking aggressiv: maskInputs: true, blockAllMedia: true, maskAllText: false (Text-Masking zerstört Reproduktionswert; statt dessen mit mask-Class an sensitiven DOM-Nodes arbeiten — Standard-Convention .sentry-mask). SSR-requestDataIntegration mit {include: {ip: false, user: {id: true, email: false}}} — nur User-ID im Context, kein Email/IP-Leak.
Sample-Rates (alle env-konfigurierbar mit Defaults):
tracesSampleRate:0.1prod,1.0devreplaysSessionSampleRate:0.1(10% aller Sessions)replaysOnErrorSampleRate:1.0(jede Session mit Error wird gerecordet — Standard-Empfehlung von Sentry)
Source-Maps: Via @sentry/vite-plugin direkt im Build erzeugt + an Sentry hochgeladen (nicht im dist/ ausliefern — Output-Verzeichnis entkoppeln). SENTRY_AUTH_TOKEN aus CI-Secrets (kommt in sentry-ci-integration.md dazu).
Implementation Steps
-
Dependencies installieren —
@sentry/react,@sentry/node,@sentry/vite-plugininapps/web/package.json. Versionen pinnen passend zu Phase-01-Dep-Updates.- Files:
apps/web/package.json,pnpm-lock.yaml - Commit:
02-observability/sentry-wiring-web: add sentry react/node/vite-plugin deps
- Files:
-
Client-Bootstrap —
apps/web/app/sentry.client.tsneu:Sentry.init({ dsn: import.meta.env.VITE_SENTRY_DSN_WEB, environment, release, tracesSampleRate, replaysSessionSampleRate, replaysOnErrorSampleRate, integrations: [browserTracingIntegration(), replayIntegration({ maskAllText: false, maskAllInputs: true, blockAllMedia: false /* selective via .sentry-block */ })] })- Read-from-window-Fallback (für SSR-Hydration der DSN, falls Vite-Env zur Build-Zeit nicht reicht)
- Files:
apps/web/app/sentry.client.ts,apps/web/app/sentry.client.test.ts - Commit:
02-observability/sentry-wiring-web: add client sentry bootstrap
-
Client-Init in
entry.client.tsx— Bootstrap als ALLERERSTE Import-Anweisung inapps/web/app/entry.client.tsx, vorhydrateRoot.- Files:
apps/web/app/entry.client.tsx - Commit:
02-observability/sentry-wiring-web: init sentry on client entry
- Files:
-
Server-Bootstrap —
apps/web/app/sentry.server.tsneu:Sentry.init({ dsn: process.env.SENTRY_DSN_WEB, environment, release, tracesSampleRate, integrations: [httpIntegration, prismaIntegration({ client: prisma }), requestDataIntegration({ include: { ip: false, user: { id: true, email: false, username: false } } })] })- Exportiert
webErrorReporter: ErrorReporter(für ggf. manuellescaptureExceptionaus Loadern) - Files:
apps/web/app/sentry.server.ts,apps/web/app/sentry.server.test.ts - Commit:
02-observability/sentry-wiring-web: add server sentry bootstrap
-
Server-Init in
entry.server.tsx— Bootstrap als allererste Import-Anweisung inapps/web/app/entry.server.tsx.- Files:
apps/web/app/entry.server.tsx - Commit:
02-observability/sentry-wiring-web: init sentry on server entry
- Files:
-
Root-ErrorBoundary an Sentry —
apps/web/app/root.tsx:- In
ErrorBoundary({ error }):useEffect(() => { Sentry.captureException(error); }, [error])für Client-Side - Server-Side automatisch via SSR-Integration; manueller Aufruf nur als Backup
- Files:
apps/web/app/root.tsx - Commit:
02-observability/sentry-wiring-web: report errors from root ErrorBoundary
- In
-
React-Router-v7-Tracing — wenn
@sentry/react-routerv8 verfügbar: dessenwithSentryRouterRouting/wrapCreateBrowserRouternutzen. Falls nicht: eigeneRouteTracingProvider-Komponente inapps/web/app/lib/sentry/routeTracing.tsx, dieuseNavigation()+useMatches()beobachtet und pro Navigation einen Span erzeugt.- Files:
apps/web/app/lib/sentry/routeTracing.tsx,apps/web/app/lib/sentry/routeTracing.test.tsx, Integration inapps/web/app/root.tsx - Commit:
02-observability/sentry-wiring-web: add react-router v7 route tracing
- Files:
-
PII-Masking-Conventions — Doku + CSS-Helper:
- Doku-File
docs/observability/sentry-replay-masking.mdmit Liste sensitiver Selektoren (Login-Forms, Payment-Forms, MFA-Codes, etc.) - Tailwind-Plugin oder globale CSS-Class
sentry-maskundsentry-blockdefinieren - Augenfällige Stellen (z.B. Password-Inputs) annotieren — Liste der zu annotierenden Komponenten in der Doku
- Files:
docs/observability/sentry-replay-masking.md,apps/web/app/styles/sentry-masking.css - Commit:
02-observability/sentry-wiring-web: document and configure replay PII masking
- Doku-File
-
Vite-Plugin für Source-Map-Upload —
apps/web/vite.config.ts:@sentry/vite-pluginmitorg,project: 'boilerplate-web',authToken: process.env.SENTRY_AUTH_TOKEN,release: { name: process.env.SENTRY_RELEASE },sourcemaps: { assets: './dist/**', filesToDeleteAfterUpload: './dist/**/*.map' }- Nur aktiv wenn
SENTRY_AUTH_TOKENvorhanden ist (lokale Builds ohne Token erlauben) - Files:
apps/web/vite.config.ts - Commit:
02-observability/sentry-wiring-web: integrate sentry vite plugin for sourcemap upload
-
Env-Defaults +
.env.example— neue Variablen dokumentieren:SENTRY_DSN_WEB(Server-Side)VITE_SENTRY_DSN_WEB(Client-Side — wird in Browser-Bundle eingebacken)VITE_SENTRY_RELEASE(=SENTRY_RELEASE, zur Build-Zeit gesetzt)VITE_SENTRY_TRACES_SAMPLE_RATE,VITE_SENTRY_REPLAYS_SESSION_SAMPLE_RATE,VITE_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATESENTRY_AUTH_TOKEN(CI-only, für Source-Map-Upload)- Files:
.env.example,apps/web/app/env.client.ts(oder wo immer Vite-Env-Vars validiert werden) - Commit:
02-observability/sentry-wiring-web: add web sentry env vars to config schema
-
Smoke-Skript —
apps/web/scripts/smoke-sentry.ts:- Triggert programmatisch ein
Sentry.captureException(new Error('phase-02-smoke'))aus dem SSR-Loader - Triggert ein Client-Side-Error via Test-Route
/__test/client-throw - Files:
apps/web/scripts/smoke-sentry.ts,apps/web/app/routes/__test.client-throw.tsx(nur in dev/staging registriert) - Commit:
02-observability/sentry-wiring-web: add smoke test routes and script
- Triggert programmatisch ein
Test Requirements
- Unit-Tests:
apps/web/app/sentry.client.test.ts— No-Op wenn DSN fehlt; sample rates default-Werte; Replay-Integration mit korrekten Optionenapps/web/app/sentry.server.test.ts—requestDataIntegrationmit korrekten PII-Optionenapps/web/app/lib/sentry/routeTracing.test.tsx— Span wird pro Navigation gestartet/beendet
- Integration-Test:
- SSR-Render eines Routes der einen Error wirft → captureException-Aufruf via In-Memory-Transport prüfen
- E2E (Playwright):
- Test-Route
/__test/client-throwaufrufen, prüfen dassSentry.captureExceptionaufgerufen wurde (überwindow.__SENTRY_EVENT_QUEUE__Spy) - Replay-Session getriggert wenn Error auftritt
- Test-Route
- E2E (manuell auf Staging):
- Client-Side-Error: in der UI auf
/__test/client-throw→ Issue in Sentry-UI binnen 30s, mit Replay-Video - SSR-Error: Loader-Throw via Test-Route → Issue mit
runtime: node - PII-Check: Replay sollte Password-Inputs als
[Masked], kein Email-Wert sichtbar
- Client-Side-Error: in der UI auf
- Source-Map-Upload-Test: CI-Build sollte in Sentry-UI die zugehörige Release mit Artifacts (
.map-Files) zeigen - Coverage-Target: ≥ 80% für
apps/web/app/sentry.*.ts+ Route-Tracing-Modul - Test-Files: wie in Implementation Steps gelistet
NICHT als completed markieren bevor:
- alle Unit + Integration-Tests grün
- ein echter Client-Error + ein echter SSR-Error im Staging-Sentry sichtbar
- mindestens 1 Replay-Video reviewed mit korrektem Masking
Acceptance Criteria
Sentry.initläuft auf Client + Server, mit allen geplanten Integrationsroot.tsxErrorBoundary reportet an Sentry- React-Router-v7-Route-Tracing aktiv, Spans pro Navigation
- Replay-Masking sicher: Password-Inputs/Payment-Forms/MFA-Codes maskiert
- SSR
requestDataIntegrationmitip: false, email: false - Vite-Plugin lädt Source-Maps hoch wenn
SENTRY_AUTH_TOKENgesetzt, sonst Skip - Source-Maps werden NICHT mit dem Build-Output ausgeliefert
- Sample-Rates env-konfigurierbar mit korrekten Defaults
pnpm lint,pnpm typecheck,pnpm testgrün.env.exampleerweitertdocs/observability/sentry-replay-masking.mdangelegt- Staging: Client- + SSR-Error sichtbar in Sentry, Replay mit korrektem Masking
- Detail-MD Progress Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
- DSN leer setzen (
VITE_SENTRY_DSN_WEBundSENTRY_DSN_WEBunset) → No-Op auf beiden Seiten, App läuft weiter - Replay disablen via
VITE_SENTRY_REPLAYS_SESSION_SAMPLE_RATE=0undVITE_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE=0(Replay ist der teuerste Teil) - Source-Map-Upload disablen via
SENTRY_AUTH_TOKENleer - Commits einzeln revertierbar — jeder Step ist ein eigener Commit. Kritische Rollback-Points: Steps 3, 5, 9.
.map-Files könnten irrtümlich ausgeliefert worden sein → CDN-Cache purgen, Build wiederholen mitfilesToDeleteAfterUpload
Security Notes
- Source-Maps NIEMALS ausliefern — wenn
.mapimdist/landet, hat jeder User Zugriff auf den vollen Quellcode.filesToDeleteAfterUploadist Pflicht. - Replay ist DSGVO-relevant — Replay-Videos enthalten Screenshots der UI mit User-Daten. Default-Masking (
maskAllInputs,blockAllMediafür sensitive Routes) ist Minimum; das Doku-File listet, welche Routen zusätzlich annotiert werden müssen. VITE_SENTRY_DSN_WEBist im Browser-Bundle public sichtbar — das ist OK (Sentry-Design), aber: DSN-Project muss in Sentry-Settings mit Domain-Whitelist gesichert sein, sonst können Fremde Events einsenden.- PII in URL-Params (z.B.
?token=...) — Sentry sammelttransaction.nameaus URL. ÜberSentry.init({ beforeSendTransaction: tx => { tx.request.url = scrubQueryParams(tx.request.url); return tx; } })Query-Strings strippen. - User-Context mit
Sentry.setUser({ id: userId })setzen — NICHT email/username. ID-Only. - Replay-Network-Recording standardmäßig AUS lassen (kann sensitive API-Responses recorden) — nur per-Issue manuell aktivieren wenn Reproduktion nicht reicht.
Subagent Recommendations
- Planning:
Plan-Subagent mit dieser Detail-MD — soll prüfen ob@sentry/react-routerv8 zum Implementation-Zeitpunkt verfügbar ist (Decision-Punkt für Step 7) - Research:
Explore-Subagent für: "Stand der React-Router v7 ↔ Sentry Integration, Mai 2026" - Implementation Client-Side:
general-purpose-Subagent für Steps 1-3, 7 - Implementation Server-Side:
general-purpose-Subagent für Steps 4-6 (kann parallel zu Client laufen) - Implementation Build-Side:
general-purpose-Subagent für Steps 8-9 - Tests: separater
general-purpose-Subagent für Unit + Integration - E2E-Tests: separater
general-purpose-Subagent für Playwright-Specs - Verification:
general-purpose-Subagent für Staging-Smoke + Replay-Review - Code-Review:
gsd-code-reviewernach Task-Completion
Staging-Deployment-Steps
- Voraussetzung:
sentry-selfhost-setup.mdistcompleted, DSN fürboilerplate-web-Project existiert - Coolify-Env-Variables für Web setzen:
- Build-Zeit (Vite muss sie sehen):
VITE_SENTRY_DSN_WEB,VITE_SENTRY_RELEASE,VITE_SENTRY_TRACES_SAMPLE_RATE=1.0,VITE_SENTRY_REPLAYS_SESSION_SAMPLE_RATE=1.0,VITE_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE=1.0,SENTRY_AUTH_TOKEN,SENTRY_ORG,SENTRY_PROJECT=boilerplate-web - Runtime (SSR-Side):
SENTRY_DSN_WEB,SENTRY_RELEASE,SENTRY_ENVIRONMENT=staging,SENTRY_TRACES_SAMPLE_RATE=1.0
- Build-Zeit (Vite muss sie sehen):
- Branch
agent/phase-02-sentry-wiring-webpushen → Coolify-Build mit Source-Map-Upload - Build-Log prüfen: Sentry-Vite-Plugin sollte ausgeben
[sentry-vite-plugin] Successfully uploaded source maps for release <git-sha> - Sentry-UI prüfen: Project
boilerplate-web→ Releases →<git-sha>→ Artifacts > 0 - Client-Smoke:
# Browser öffnen: https://app.<staging-domain>/__test/client-throw # In Sentry-UI: Issues binnen 30s, Stack-Trace ist UN-minified (zeigt echte File/Line) # Replay-Video angeknüpft, Password-Felder als [Masked] - SSR-Smoke:
curl https://app.<staging-domain>/__test/ssr-throw # In Sentry-UI: Issue mit runtime=node, request.headers minimiert - PII-Check: in einem Replay sicherstellen, dass keine Email-Adressen, keine API-Tokens in Network-Tab, keine Passwords sichtbar sind
- Wenn alles grün: PR → main
Deviations from Plan
@sentry/react-routerv10 used instead of v8. Detail-MD targets v8 line; the latest stable as of 2026-05-17 is 10.53.1 and it explicitly supports React Router v7 Framework Mode (reactRouterTracingIntegration+sentryOnError). Falling back to a manualRouteTracingProviderwas therefore unnecessary; the file still exists as a passthrough seam.requestDataIntegrationuser-include keys dropped. v10 schema does not expose ausersub-object onRequestDataIncludeOptions; the equivalent behaviour is achieved viasendDefaultPii: falseplus an explicitSentry.setUser({ id })call from loader code. PII guarantee (no email/ip/cookies) is preserved.- Test route is a pathless layout route. With the v1 file-route convention used in
apps/web/app/routes.ts,__test.client-throw.tsxregisters as a pathless layout. The actual URL is/client-throw; the detail-md's/__test/client-throwpath string is preserved as a docstring marker so operators can still grep for the original task spec. - Smoke field renamed to
note.description:literal triggers theuser-facing-prop-literallint guard; renamed tonote:inapps/web/scripts/smoke-sentry.ts.
Progress Log
- 2026-05-17 03:53 —
79fb9e29— add sentry react/node/vite-plugin deps (Step 1) - 2026-05-17 03:59 —
5722b21b— add client sentry bootstrap + 14 unit tests (Step 2) - 2026-05-17 04:04 —
5575aa45— init sentry on client entry (Step 3) - 2026-05-17 04:08 —
df06385c— add server sentry bootstrap + 9 unit tests (Step 4) - 2026-05-17 04:11 —
62978141— init sentry on server entry (Step 5) - 2026-05-17 04:14 —
c56cc7dd— report errors from root ErrorBoundary (Step 6) - 2026-05-17 04:18 —
513e74b3— add react-router v7 route tracing + 3 unit tests (Step 7) - 2026-05-17 04:22 —
d0d2a9c2— document and configure replay PII masking (Step 8) - 2026-05-17 04:26 —
fd18713b— integrate sentry vite plugin for sourcemap upload (Step 9) - 2026-05-17 04:30 —
bb41d3dd— add web sentry env vars to config schema (Step 10) - 2026-05-17 04:39 —
e332d7ac— add smoke test routes and script (Step 11)
Status: in_progress (code-complete, staging-smoke-pending). Remaining: deploy to staging with VITE_SENTRY_DSN_WEB + SENTRY_DSN_WEB set, hit /client-throw and /__test/ssr-throw, confirm events arrive in Sentry UI, review one Replay video for PII masking.
Lessons Learned
(Optional — typische Stolperfallen: Vite-Env muss zur Build-Zeit gesetzt sein, sonst ist DSN undefined im Browser; React-Router v7 Hydration-Errors triggern Sentry-Spam wenn Source-Map fehlt.)