sentry-tanstack-start-sdk

> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > TanStack Start React SDK # Sentry TanStack Start React SDK Opinionated wizard that scans your TanStack Start React project and guides you through complete Sentry setup for browser and server runtimes. ## Invoke This Skill When - User asks to "add Sentry to TanStack Start" or "set up Sentry" in a TanStack Start React app - User wants to install or configure `@sentry/tanstackstart-react` - User wants error monitoring, tracing, session replay, logs, or user feedback for TanStack Start React - User asks about `sentryTanstackStart`, `wrapFetchWithSentry`, `instrument.server.mjs`, or TanStack Start middleware instrumentation > **Note:** This SDK is currently alpha and documented as compatible with TanStack Start `1.0 RC`. > Always verify against [docs.sentry.io/platforms/javascript/guides/tanstackstart-react/](https://docs.sentry.io/platforms/javascript/guides/tanstackstart-react/) before implementing. --- ## Phase 1: Detect Run these commands to understand the project before making any recommendations: ```bash # Detect TanStack Start / Router and existing Sentry cat package.json | grep -E '"@tanstack/react-start"|"@tanstack/react-router"|"@sentry/tanstackstart-react"' # Check if Sentry is already present cat package.json | grep '"@sentry/' # Detect key files used by the TanStack Start setup ls src/router.tsx src/start.ts src/server.ts instrument.server.mjs vite.config.ts vite.config.js 2>/dev/null # Check whether source map upload credentials are configured cat .env .env.local .env.sentry-build-plugin 2>/dev/null | grep "SENTRY_AUTH_TOKEN" # Detect deployment hints in scripts cat package.json | grep -E '"dev"|"build"|"start"|NODE_OPTIONS|--import' # Detect logging libraries cat package.json | grep -E '"pino"|"winston"|"loglevel"' # Detect companion backend directories ls ../backend ../server ../api 2>/dev/null cat ../go.mod ../requirements.txt ../Gemfile ../pom.xml 2>/dev/null | head -3 ``` **What to determine:** | Question | Impact | |----------|--------| | `@tanstack/react-start` present? | Confirms this skill is the right setup path | | `@sentry/tanstackstart-react` already installed? | Skip install and go to feature tuning | | `src/router.tsx` exists? | Client-side `Sentry.init` placement | | `src/start.ts` exists? | Global middleware setup for server-side errors | | `src/server.ts` exists? | Server entry instrumentation placement | | `instrument.server.mjs` exists? | Runtime startup instrumentation path | | `vite.config.ts` exists? | Add `sentryTanstackStart` plugin and source maps | | `SENTRY_AUTH_TOKEN` configured? | Source map upload readiness | | Backend directory found? | Trigger Phase 4 cross-link suggestion | --- ## Phase 2: Recommend Present a concrete recommendation based on what you found. Do not ask open-ended questions — lead with a proposal: **Recommended (core coverage):** - ✅ **Error Monitoring** — always; captures unhandled client and server errors - ✅ **Tracing** — high-value for request and route timing across browser and server - ✅ **Session Replay** — recommended for user-facing apps **Optional (enhanced observability):** - ⚡ **Logs** — recommend when structured log search and log-to-trace correlation are needed - ⚡ **User Feedback** — recommend when product teams want in-app issue reports **Recommendation logic:** | Feature | Recommend when... | |---------|------------------| | Error Monitoring | **Always** — non-negotiable baseline | | Tracing | **Usually yes** for TanStack Start; route + fetch instrumentation gives immediate value | | Session Replay | User-facing app, login flows, checkout flows, or hard-to-reproduce UX bugs | | Logs | Existing logging strategy, support workflow, or trace/log correlation needs | | User Feedback | Team wants direct user reports without leaving the app | Propose: *"I recommend Error Monitoring + Tracing + Session Replay. Want me to also enable Logs and User Feedback?"* --- ## Phase 3: Guide ### Install ```bash npm install @sentry/tanstackstart-react --save ``` ### Configure Client-Side Sentry in `src/router.tsx` Initialize Sentry inside the router factory and gate it to the browser: ```tsx import * as Sentry from "@sentry/tanstackstart-react"; import { createRouter } from "@tanstack/react-router"; export const getRouter = () => { const router = createRouter(); if (!router.isServer) { Sentry.init({ dsn: "___PUBLIC_DSN___", dataCollection: { // userInfo: false, // httpBodies: [], }, integrations: [ Sentry.tanstackRouterBrowserTracingIntegration(router), Sentry.replayIntegration(), Sentry.feedbackIntegration({ colorScheme: "system", }), ], enableLogs: true, tracesSampleRate: 1.0, replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, }); } return router; }; ``` ### Configure Server-Side Sentry in `instrument.server.mjs` Create `instrument.server.mjs` in project root: ```javascript import * as Sentry from "@sentry/tanstackstart-react"; Sentry.init({ dsn: "___PUBLIC_DSN___", dataCollection: { // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: // https://docs.sentry.io/platforms/javascript/guides/tanstackstart-react/configuration/options/#dataCollection // userInfo: false, // httpBodies: [], }, enableLogs: true, tracesSampleRate: 1.0, }); ``` ### Configure Vite Plugin in `vite.config.ts` `sentryTanstackStart` should be the last plugin: ```typescript import { defineConfig } from "vite"; import { sentryTanstackStart } from "@sentry/tanstackstart-react/vite"; import { tanstackStart } from "@tanstack/react-start/plugin/vite"; export default defineConfig({ plugins: [ tanstackStart(), sentryTanstackStart({ org: "___ORG_SLUG___", project: "___PROJECT_SLUG___", authToken: process.env.SENTRY_AUTH_TOKEN, }), ], }); ``` If the token is stored in `.env`, load it with `loadEnv` in the Vite config before passing it to the plugin. ### Instrument Server Entry Point in `src/server.ts` Wrap the fetch handler with `wrapFetchWithSentry`: ```typescript import { wrapFetchWithSentry } from "@sentry/tanstackstart-react"; import handler, { createServerEntry } from "@tanstack/react-start/server-entry"; export default createServerEntry( wrapFetchWithSentry({ fetch(request: Request) { return handler.fetch(request); }, }), ); ``` ### Add Global Server Middleware in `src/start.ts` These middleware capture server-side request and function errors: ```tsx import { sentryGlobalFunctionMiddleware, sentryGlobalRequestMiddleware, } from "@sentry/tanstackstart-react"; import { createStart } from "@tanstack/react-start"; export const startInstance = createStart(() => { return { requestMiddleware: [sentryGlobalRequestMiddleware], functionMiddleware: [sentryGlobalFunctionMiddleware], }; }); ``` Sentry middleware should be first in each array. ### Runtime Startup Patterns Choose one runtime method: | Runtime pattern | Use when... | Notes | |---|---|---| | `--import` flag | You can control Node startup flags | Preferred for production monitoring | | Direct import in `src/server.ts` | Host restricts startup flags (for example serverless hosts) | Limits instrumentation to native Node APIs | `--import` examples: ```json { "scripts": { "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' vite dev --port 3000", "build": "vite build && cp instrument.server.mjs .output/server", "start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs" } } ``` Direct import fallback (top of `src/server.ts`): ```typescript import "../instrument.server.mjs"; ``` ### For Each Agreed Feature Walk through features one at a time. Load the reference file, follow steps exactly, and verify before moving on: | Feature | Reference | Load when... | |---------|-----------|-------------| | Error Monitoring | `${SKILL_ROOT}/references/error-monitoring.md` | Always | | Tracing | `${SKILL_ROOT}/references/tracing.md` | Route/API performance visibility needed | | Session Replay | `${SKILL_ROOT}/references/session-replay.md` | User-facing app | | Logs | `${SKILL_ROOT}/references/logging.md` | Structured logs and correlation needed | | User Feedback | `${SKILL_ROOT}/references/user-feedback.md` | In-app feedback collection needed | | TanStack Start Features | `${SKILL_ROOT}/references/tanstackstart-features.md` | Server entry, Vite plugin, source maps, runtime startup | 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 is disabled when empty | | `dataCollection` | `object` | conservative unless set | Fine-grained control over auto-collected categories (`userInfo`, `cookies`, `httpHeaders`, `httpBodies`, `queryParams`, `genAI`). When omitted, the SDK falls back to `sendDefaultPii` (default `false`). Passing the object — even `{}` — flips unset categories to their permissive defaults; opt out per category. | | `integrations` | `Integration[]` | SDK defaults | Include TanStack Router tracing, replay, feedback as needed | | `enableLogs` | `boolean` | `false` | Enables `Sentry.logger.*` APIs | | `tracesSampleRate` | `number` | — | `1.0` in development, lower in production | | `replaysSessionSampleRate` | `number` | — | Fraction of all sessions recorded | | `replaysOnErrorSampleRate` | `number` | — | Fraction of error sessions recorded | | `tunnel` | `string` | — | Optional ad-blocker bypass endpoint | | `debug` | `boolean` | `false` | SDK diagnostic logging | ### TanStack Start-Specific APIs | API | Purpose | |-----|---------| | `tanstackRouterBrowserTracingIntegration(router)` | Browser navigation tracing | | `wrapFetchWithSentry(...)` | Server request tracing + error capture on fetch handler | | `sentryGlobalRequestMiddleware` | Captures request-level server errors | | `sentryGlobalFunctionMiddleware` | Captures server function errors | | `sentryTanstackStart({...})` | Vite plugin for source maps and middleware instrumentation | --- ## Verification Trigger test events to confirm Sentry receives data. ### Issues Test (Frontend) ```tsx <button type="button" onClick={() => { throw new Error("Sentry Test Error"); }} > Break the world </button> ``` ### Tracing Test (Frontend + API Route) ```tsx <button type="button" onClick={async () => { await Sentry.startSpan({ name: "Example Frontend Span", op: "test" }, async () => { const res = await fetch("/api/sentry-example"); if (!res.ok) { throw new Error("Sentry Example Frontend Error"); } }); }} > Break the world </button> ``` ### Logs Test ```javascript Sentry.logger.info("User example action completed"); Sentry.logger.warn("Slow operation detected", { operation: "data_fetch", duration: 3500 }); Sentry.logger.error("Validation failed", { field: "email", reason: "Invalid email" }); ``` Confirm in Sentry: - **Issues**: frontend/server errors appear - **Traces**: browser and server spans appear - **Replays**: session replay appears when enabled - **Logs**: log lines appear when `enableLogs: true` - **User Feedback**: submissions appear when feedback integration is enabled --- ## Phase 4: Cross-Link After completing TanStack Start setup, check whether a companion backend exists without Sentry: ```bash