sentryTanstackStart

Available since: v10.35.0

The sentryTanstackStart Vite plugin simplifies source map configuration for TanStack Start applications. It automatically handles source map generation and upload to Sentry during production builds.

Usage

To automatically upload source maps, you need to provide your Sentry auth token, organization, and project slugs in your Vite configuration. The plugin then, by default, automatically enables hidden source maps and deletes .map files after upload.

Make sure you add your auth token to your CI, if you are using one to deploy your application.

Add your auth token to your environment:

SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___

SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___

import { defineConfig, loadEnv } from "vite";

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

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

import { defineConfig, loadEnv } from "vite";

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

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

Configure sentryTanstackStart in your vite.config.ts:

import { defineConfig } from "vite";
import { sentryTanstackStart } from "@sentry/tanstackstart-react/vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";

export default defineConfig({
  plugins: [
    tanstackStart(),
    // other plugins - sentryTanstackStart should be last
    sentryTanstackStart({
      org: "___ORG_SLUG___",
      project: "___PROJECT_SLUG___",
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

import { defineConfig } from "vite";
import { sentryTanstackStart } from "@sentry/tanstackstart-react/vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";

export default defineConfig({
  plugins: [
    tanstackStart(),
    // other plugins - sentryTanstackStart should be last
    sentryTanstackStart({
      org: "___ORG_SLUG___",
      project: "___PROJECT_SLUG___",
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

Configuration Options

The plugin passes through all options to the underlying @sentry/vite-plugin. See the Sentry Vite Plugin documentation for the full list of available options.

Automatic Middleware Instrumentation

Available since: v10.37.0

The plugin automatically instruments all TanStack Start middlewares for tracing by default. To disable this behavior:

sentryTanstackStart({
  // ...
  autoInstrumentMiddleware: false,
}),

sentryTanstackStart({
  // ...
  autoInstrumentMiddleware: false,
}),

Component Name Annotation

Available since: v10.55.0

The reactComponentAnnotation option annotates your React components with data-sentry-component and data-sentry-source-file attributes at build time. This lets you see component names instead of generic selectors in Session Replay, breadcrumbs, and performance monitoring.

sentryTanstackStart({
  // ...
  reactComponentAnnotation: {
    enabled: true,
  },
}),

sentryTanstackStart({
  // ...
  reactComponentAnnotation: {
    enabled: true,
  },
}),

To exclude specific components from annotation:

sentryTanstackStart({
  // ...
  reactComponentAnnotation: {
    enabled: true,
    ignoredComponents: ["MyInternalComponent"],
  },
}),

sentryTanstackStart({
  // ...
  reactComponentAnnotation: {
    enabled: true,
    ignoredComponents: ["MyInternalComponent"],
  },
}),

Tunnel Route

Available since: v10.51.0

The tunnelRoute option registers a same-origin TanStack Start server route that forwards Sentry envelopes to Sentry's ingest servers. It also automatically sets the client tunnel option in Sentry.init() so browser events go through that route. This helps avoid ad blockers and corporate firewalls that block requests to *.sentry.io.

tunnelRoute accepts three shapes:

tunnelRoute: true (recommended)

Generates an opaque, unguessable route path for each dev session and production build. Because the path changes between builds, ad blockers can't reliably target it.

sentryTanstackStart({
  tunnelRoute: true,
}),

sentryTanstackStart({
  tunnelRoute: true,
}),

Static path

Pass a string to use a fixed route path. This is easier to reason about, but a known path is easier for ad blockers to add to a list.

sentryTanstackStart({
  tunnelRoute: "/monitor",
}),

sentryTanstackStart({
  tunnelRoute: "/monitor",
}),

Object form

Use the object form to control the DSN allowlist or set a static path explicitly:

sentryTanstackStart({
  tunnelRoute: {
    allowedDsns: ["___PUBLIC_DSN___"],
    path: "/monitor",
  },
}),

sentryTanstackStart({
  tunnelRoute: {
    allowedDsns: ["___PUBLIC_DSN___"],
    path: "/monitor",
  },
}),

• allowedDsns — only envelopes targeting one of these DSNs are forwarded. If omitted or empty, the route falls back to the DSN of the active server-side Sentry SDK at runtime.
• path — the public route path. If omitted, an opaque path is generated (same behavior as tunnelRoute: true).