Sentry Tanstack Start Sdk

All Skills > SDK Setup > 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/ before implementing.

---

Phase 1: Detect

Run these commands to understand the project before making any recommendations:

# 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:

---

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:

Propose: "I recommend Error Monitoring + Tracing + Session Replay. Want me to also enable Logs and User Feedback?"

---

Phase 3: Guide

Install

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:

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___",
      sendDefaultPii: true,

      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:

import * as Sentry from "@sentry/tanstackstart-react";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  sendDefaultPii: true,
  enableLogs: true,
  tracesSampleRate: 1.0,
});

Configure Vite Plugin in vite.config.ts

sentryTanstackStart should be the last plugin:

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:

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:

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:

--import examples:

{
  "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):

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:

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

---

Configuration Reference

Key Sentry.init() Options

TanStack Start-Specific APIs

---

Verification

Trigger test events to confirm Sentry receives data.

Issues Test (Frontend)

<button
  type="button"
  onClick={() => {
    throw new Error("Sentry Test Error");
  }}
>
  Break the world
</button>

Tracing Test (Frontend + API Route)

<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

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:

ls ../backend ../server ../api ../go ../python 2>/dev/null
cat ../go.mod ../requirements.txt ../pyproject.toml ../Gemfile ../pom.xml 2>/dev/null | head -5

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

---

Troubleshooting

Error Monitoring — Sentry TanStack Start React SDK

Minimum SDK: @sentry/tanstackstart-react (alpha)

Framework target: TanStack Start React 1.0 RC

---

Automatic vs Manual Capture

Core rule:

If an error is caught and not re-thrown, capture it manually.

---

Required Server Error Hooks

Global server middleware (src/start.ts)

import {
  sentryGlobalFunctionMiddleware,
  sentryGlobalRequestMiddleware,
} from "@sentry/tanstackstart-react";
import { createStart } from "@tanstack/react-start";

export const startInstance = createStart(() => {
  return {
    requestMiddleware: [sentryGlobalRequestMiddleware],
    functionMiddleware: [sentryGlobalFunctionMiddleware],
  };
});

Server entry wrapper (src/server.ts)

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);
    },
  }),
);

---

Client-Side Manual Capture

captureException

import * as Sentry from "@sentry/tanstackstart-react";

try {
  await riskyOperation();
} catch (error) {
  Sentry.captureException(error, {
    tags: { area: "checkout" },
    extra: { retryCount: 1 },
  });
}

captureMessage

Sentry.captureMessage("Unexpected state encountered", "warning");

---

Error Boundaries and TanStack Router errorComponent

Errors handled by custom boundaries are not automatically reported unless you send them.

import { useEffect } from "react";
import * as Sentry from "@sentry/tanstackstart-react";
import { createRoute } from "@tanstack/react-router";

const route = createRoute({
  errorComponent: ({ error }) => {
    useEffect(() => {
      Sentry.captureException(error);
    }, [error]);

    return <div>Something went wrong.</div>;
  },
});

For class boundaries, wrap with withErrorBoundary:

import React from "react";
import * as Sentry from "@sentry/tanstackstart-react";

class MyErrorBoundary extends React.Component {
  render() {
    return this.props.children;
  }
}

export const MySentryWrappedErrorBoundary = Sentry.withErrorBoundary(MyErrorBoundary, {
  fallback: <p>Something went wrong.</p>,
});

---

Enrichment APIs

Use standard Sentry context enrichment calls:

Sentry.setUser({ id: "user_123", email: "user@example.com" });
Sentry.setTag("tenant", "acme");
Sentry.setContext("checkout", { step: "payment" });
Sentry.addBreadcrumb({
  category: "ui.click",
  message: "Clicked complete purchase",
  level: "info",
});

---

Troubleshooting

Logs — Sentry TanStack Start React SDK

Minimum SDK: @sentry/tanstackstart-react with Logs support

Framework target: TanStack Start React 1.0 RC

---

Enable Logs

Enable log ingestion in both browser and server Sentry.init calls:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  enableLogs: true,
});

Configure this in:

• src/router.tsx (browser runtime)
• instrument.server.mjs (server runtime)

---

Logging APIs

Use structured logging methods from the Sentry logger:

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",
});

---

Correlating Logs with Traces and Errors

For best analysis value:

1. Enable tracing (tracesSampleRate + integrations). 2. Include useful structured context on logs (operation, tenant, request IDs). 3. Use consistent field names across browser and server logs.

This allows filtering by request context and linking logs to traces/issues.

---

Verification

1. Trigger Sentry.logger.info and Sentry.logger.error in the app. 2. Open Logs in Sentry. 3. Filter by message or metadata fields to confirm ingestion. 4. Open a related issue or trace and verify shared context fields.

---

Troubleshooting

Session Replay — Sentry TanStack Start React SDK

Minimum SDK: @sentry/tanstackstart-react with Replay support

Framework target: TanStack Start React 1.0 RC

---

Replay Setup (src/router.tsx)

Session Replay is configured on the browser side in Sentry.init.

import * as Sentry from "@sentry/tanstackstart-react";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [Sentry.replayIntegration()],

  // Record 10% of all sessions
  replaysSessionSampleRate: 0.1,
  // Record 100% of sessions where an error occurs
  replaysOnErrorSampleRate: 1.0,
});

---

Sampling Strategy

---

Privacy and Data Controls

Adjust Replay privacy behavior based on product requirements:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
});

Use stricter masking for apps handling sensitive user or payment data.

---

Verification

1. Load the app in a browser. 2. Trigger one error and complete a few UI interactions. 3. Open Replays in Sentry and confirm a replay appears. 4. Open the linked issue and verify replay context is attached.

---

Troubleshooting

TanStack Start Features — Sentry TanStack Start React SDK

Framework target: TanStack Start React 1.0 RC

---

sentryTanstackStart Vite Plugin

Add the plugin in vite.config.ts and keep it last:

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,
    }),
  ],
});

This plugin manages source map upload and instruments middleware tracing when tracing is enabled.

---

Environment Token Handling

Set auth token in CI or local environment:

SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___

If loading from .env in Vite config, use loadEnv:

import { defineConfig, loadEnv } from "vite";

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), "");

  return {
    plugins: [
      sentryTanstackStart({
        authToken: env.SENTRY_AUTH_TOKEN,
      }),
    ],
  };
});

---

Runtime Startup Options

Preferred: --import startup

Use this when you can control Node startup flags.

1. Keep root instrument.server.mjs. 2. Copy it to runtime output location during build. 3. Start node with --import.

Example scripts:

{
  "scripts": {
    "build": "vite build && cp instrument.server.mjs .output/server",
    "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' vite dev --port 3000",
    "start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs"
  }
}

Fallback: direct import in server entry

Use when host/runtime does not allow startup flags.

import "../instrument.server.mjs";

Limitation: only native Node.js APIs are instrumented; third-party library instrumentation is limited.

---

Server Entry and Middleware Checklist

For full server coverage, confirm all three are present:

1. instrument.server.mjs with server Sentry.init. 2. src/server.ts wraps handler with wrapFetchWithSentry. 3. src/start.ts includes both Sentry global middleware first in arrays.

---

Optional Tunnel Configuration

To reduce ad-blocker drops, configure tunnel route:

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  tunnel: "/tunnel",
});

Then implement a server endpoint that forwards tunnel traffic to Sentry ingest.

---

Troubleshooting

Tracing — Sentry TanStack Start React SDK

Minimum SDK: @sentry/tanstackstart-react (alpha)

Framework target: TanStack Start React 1.0 RC

---

What Tracing Captures

---

Browser Tracing Setup (src/router.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___",
      integrations: [Sentry.tanstackRouterBrowserTracingIntegration(router)],
      tracesSampleRate: 1.0,
    });
  }

  return router;
};

---

Server Tracing Setup

instrument.server.mjs

import * as Sentry from "@sentry/tanstackstart-react";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  tracesSampleRate: 1.0,
});

src/server.ts

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);
    },
  }),
);

---

Custom Span Example

import * as Sentry from "@sentry/tanstackstart-react";

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");
    }
  },
);

Use startSpan for key flows such as checkout, search, and expensive data loads.

---

Sampling Guidance

---

Verifying Traces

1. Trigger a page navigation and one API call in the app. 2. Open Traces in Sentry. 3. Confirm one trace shows:

• browser transaction/span
• server request span
• linked errors (if thrown)

---

Troubleshooting

User Feedback — Sentry TanStack Start React SDK

Minimum SDK: @sentry/tanstackstart-react with Feedback integration

Framework target: TanStack Start React 1.0 RC

---

Feedback Widget Setup

Enable feedback in the browser-side init (src/router.tsx):

import * as Sentry from "@sentry/tanstackstart-react";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.feedbackIntegration({
      colorScheme: "system",
    }),
  ],
});

---

Common Configuration Options

Sentry.feedbackIntegration({
  autoInject: true,
  colorScheme: "system",
  showName: true,
  showEmail: true,
  isNameRequired: false,
  isEmailRequired: false,
  triggerLabel: "Report a bug",
  formTitle: "Report a bug",
  submitButtonLabel: "Send report",
  successMessageText: "Thanks for the report.",
  tags: {
    area: "tanstack-start-web",
    env: import.meta.env.MODE,
  },
});

---

Feedback From Error Flows

If you want post-error feedback dialogs, capture an error and open the report dialog:

const eventId = Sentry.captureException(new Error("Checkout flow failed"));
Sentry.showReportDialog({
  eventId,
  title: "Something went wrong",
  subtitle: "Want to help us fix this?",
});

---

Verification

1. Open the app and locate the feedback trigger. 2. Submit a sample report. 3. Open User Feedback in Sentry and confirm receipt. 4. If using report dialogs, verify feedback is linked to the issue event.

---

Troubleshooting