sentry-tanstack-start-sdk

어떤 스킬인가요?

Full Sentry SDK setup for TanStack Start React. Use when asked to "add Sentry to TanStack Start", "install @sentry/tanstackstart-react", or configure error monitoring, tracing, session replay, logs, or user feedback in a TanStack Start React app.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# 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

| Area | Auto Captured? | Mechanism |
|------|----------------|-----------|
| Unhandled client exceptions | ✅ Yes | Browser global handlers after `Sentry.init` |
| Unhandled promise rejections (client) | ✅ Yes | Browser global handlers |
| Server request exceptions | ✅ Yes | `sentryGlobalRequestMiddleware` + `wrapFetchWithSentry` |
| Server function exceptions | ✅ Yes | `sentryGlobalFunctionMiddleware` |
| Errors swallowed by custom boundaries | ❌ No | Call `Sentry.captureException` manually |
| SSR render exceptions | ❌ No | Call `Sentry.captureException` manually |

Core rule:

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

---

## Required Server Error Hooks

### Global server middleware (`src/start.ts`)

```tsx
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`)

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

---

## Client-Side Manual Capture

### `captureException`

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

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

### `captureMessage`

```tsx
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.

```tsx
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`:

```tsx
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:

```tsx
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

| Issue | Solution |
|-------|----------|
| Server errors missing | Verify both `wrapFetchWithSentry` and global middleware are in place |
| Error boundary issues not appearing | Add explicit `captureException` inside `errorComponent` or boundary hooks |
| Missing user context | Call `setUser` after auth state is known |
| Duplicate dev errors | Validate behavior in production build; development tooling may rethrow |

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

```tsx
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:

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

---

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

| Issue | Solution |
|-------|----------|
| Logs not visible | Confirm `enableLogs: true` in active runtime init |
| Missing metadata fields | Pass structured objects as second argument to logger methods |
| Too much log volume | Reduce noisy log calls or gate debug/info logs by environment |
| Logs disconnected from traces | Ensure tracing is enabled and context keys are consistent |

# 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`.

```tsx
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

| Goal | Suggested config |
|------|------------------|
| Fast rollout / validation | `replaysSessionSampleRate: 0.1`, `replaysOnErrorSampleRate: 1.0` |
| Cost-sensitive production | Lower session sample rate (`0.02` to `0.05`), keep error sample high |
| Incident investigation mode | Temporarily increase session sample rate |

---

## Privacy and Data Controls

Adjust Replay privacy behavior based on product requirements:

```tsx
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

| Issue | Solution |
|-------|----------|
| Replay not appearing | Ensure `replayIntegration()` is included and sample rates are non-zero |
| Replays only on error | Increase `replaysSessionSampleRate` |
| Sensitive content visible | Enable masking/blocking options and audit replay config |
| Replay volume too high | Lower `replaysSessionSampleRate` and keep error replay rate high |

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

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

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:

```bash
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
```

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

```typescript
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:

```json
{
  "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.

```typescript
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:

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

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

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Build succeeds but no source maps in Sentry | Verify `sentryTanstackStart` is configured and token is available at build time |
| `process.env.SENTRY_AUTH_TOKEN` undefined | Use `loadEnv` in Vite config or `.env.sentry-build-plugin` |
| Works in dev but not production | Ensure `instrument.server.mjs` is copied into final server output and imported at runtime |
| Missing middleware spans | Ensure Sentry plugin is enabled and tracing is configured |

# Tracing — Sentry TanStack Start React SDK

> Minimum SDK: `@sentry/tanstackstart-react` (alpha)  
> Framework target: TanStack Start React `1.0 RC`

---

## What Tracing Captures

| Layer | Integration | Result |
|------|-------------|--------|
| Browser route transitions | `tanstackRouterBrowserTracingIntegration(router)` | Navigation and route-level transaction timing |
| Server request handling | `wrapFetchWithSentry(...)` | Server request spans and request-level errors |
| Server middleware/functions | `sentryGlobalRequestMiddleware` / `sentryGlobalFunctionMiddleware` | Middleware and server function timing context |
| Custom operations | `Sentry.startSpan` | Business operations and async block timing |

---

## Browser Tracing Setup (`src/router.tsx`)

```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`

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

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

### `src/server.ts`

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

---

## Custom Span Example

```tsx
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

| Environment | Suggested `tracesSampleRate` |
|-------------|-------------------------------|
| Development | `1.0` |
| Production (starting point) | `0.1` to `0.3` |
| High-volume traffic | Tune with lower fixed rate or use server-side dynamic sampling |

---

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

| Issue | Solution |
|-------|----------|
| No browser transactions | Ensure router integration gets the actual router instance |
| No server spans | Verify runtime loads `instrument.server.mjs` (`--import` path or direct import path) |
| Trace disconnected between client and server | Confirm both browser and server init are active in the same environment |
| Too many traces | Reduce `tracesSampleRate` for production |

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

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

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

---

## Common Configuration Options

```tsx
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:

```tsx
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

| Issue | Solution |
|-------|----------|
| Feedback button not shown | Ensure `feedbackIntegration()` is in browser `integrations` |
| Styling/position conflicts | Customize trigger placement and check app z-index layers |
| Missing user details | Set Sentry user context before feedback submission |
| Feedback not linked to errors | Use `showReportDialog` with the returned `eventId` |

---
name: sentry-tanstack-start-sdk
description: Full Sentry SDK setup for TanStack Start React. Use when asked to "add Sentry to TanStack Start", "install @sentry/tanstackstart-react", or configure error monitoring, tracing, session replay, logs, or user feedback in a TanStack Start React app.
license: Apache-2.0
category: sdk-setup
parent: sentry-sdk-setup
disable-model-invocation: true
---

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

| Backend detected | Suggest skill |
|------------------|--------------|
| Go (`go.mod`) | `sentry-go-sdk` |
| Python (`requirements.txt`, `pyproject.toml`) | `sentry-python-sdk` |
| Ruby (`Gemfile`) | `sentry-ruby-sdk` |
| Java (`pom.xml`, `build.gradle`) | Use `@sentry/java` docs |
| Node.js backend services | `sentry-node-sdk` |

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Events not appearing | Set `debug: true`, verify DSN, and ensure client/server init files both run |
| No server traces | Confirm `src/server.ts` uses `wrapFetchWithSentry` and runtime loads `instrument.server.mjs` |
| Server errors missing from route handlers | Ensure `sentryGlobalRequestMiddleware` and `sentryGlobalFunctionMiddleware` are first in arrays |
| Source maps not resolving | Verify `SENTRY_AUTH_TOKEN`, `org`, and `project` in `sentryTanstackStart` config |
| `SENTRY_AUTH_TOKEN` undefined in Vite config | Use `loadEnv(mode, process.cwd(), "")` or `.env.sentry-build-plugin` |
| Replay not recording | Ensure `replayIntegration()` is in `integrations` and sample rates are non-zero |
| Feedback widget not visible | Confirm `feedbackIntegration()` is configured and check CSS z-index conflicts |
| Logs missing in Sentry | Set `enableLogs: true` and use `Sentry.logger.*` APIs |
| Direct-import setup misses library spans | Prefer `--import` startup when possible; direct import supports native Node instrumentation only |
| SSR rendering exceptions not auto-captured | Capture manually with `Sentry.captureException` in error boundaries / fallback handlers |