Tunnel route helper + Dynamic tunnel route generator for TanStack Start React

dev-packages/e2e-tests/test-applications/tanstackstart-react/package.json

@@ -9,8 +9,17 @@
  "test": "playwright test",
  "clean": "npx rimraf node_modules pnpm-lock.yaml",
  "test:build": "pnpm install && pnpm build",
+ "test:build:tunnel-generated": "pnpm install && E2E_TEST_TUNNEL_ROUTE_MODE=dynamic E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm build",
+ "test:build:tunnel-static": "pnpm install && E2E_TEST_TUNNEL_ROUTE_MODE=static E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm build",
+ "test:build:tunnel-custom": "pnpm install && E2E_TEST_CUSTOM_TUNNEL_ROUTE=1 pnpm build",
+ "test:build:tunnel-object": "pnpm install && E2E_TEST_TUNNEL_ROUTE_MODE=object E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm build",
  "test:build-latest": "pnpm add @tanstack/react-start@latest @tanstack/react-router@latest && pnpm install && pnpm build",
- "test:assert": "pnpm test"
+ "test:assert:proxy": "pnpm test",
+ "test:assert": "pnpm test:assert:proxy",
+ "test:assert:tunnel-generated": "E2E_TEST_TUNNEL_ROUTE_MODE=dynamic E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm test",
+ "test:assert:tunnel-static": "E2E_TEST_TUNNEL_ROUTE_MODE=static E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm test",
+ "test:assert:tunnel-custom": "E2E_TEST_CUSTOM_TUNNEL_ROUTE=1 pnpm test",
+ "test:assert:tunnel-object": "E2E_TEST_TUNNEL_ROUTE_MODE=object E2E_TEST_DSN=http://public@localhost:3031/1337 pnpm test"
  },
  "dependencies": {
  "@sentry/tanstackstart-react": "file:../../packed/sentry-tanstackstart-react-packed.tgz",
@@ -35,5 +44,29 @@
  },
  "volta": {
  "extends": "../../package.json"
+ },
+ "sentryTest": {
+ "variants": [
+ {
+ "label": "tunnel-generated",
+ "build-command": "pnpm test:build:tunnel-generated",
+ "assert-command": "pnpm test:assert:tunnel-generated"
+ },
+ {
+ "label": "tunnel-static",
+ "build-command": "pnpm test:build:tunnel-static",
+ "assert-command": "pnpm test:assert:tunnel-static"
+ },
+ {
+ "label": "tunnel-custom",
+ "build-command": "pnpm test:build:tunnel-custom",
+ "assert-command": "pnpm test:assert:tunnel-custom"
+ },
+ {
+ "label": "tunnel-object",
+ "build-command": "pnpm test:build:tunnel-object",
+ "assert-command": "pnpm test:assert:tunnel-object"
+ }
+ ]
  }
 }

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/globals.d.ts

@@ -0,0 +1,2 @@
+declare const __APP_DSN__: string;
+declare const __APP_TUNNEL__: string | undefined;

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/router.tsx

@@ -11,13 +11,13 @@ export const getRouter = () => {
  if (!router.isServer) {
  Sentry.init({
  environment: 'qa', // dynamic sampling bias to keep transactions
- dsn: 'https://public@dsn.ingest.sentry.io/1337',
+ dsn: __APP_DSN__,
  integrations: [Sentry.tanstackRouterBrowserTracingIntegration(router)],
  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
  release: 'e2e-test',
- tunnel: 'http://localhost:3031/', // proxy server
+ tunnel: __APP_TUNNEL__,
  });
  }
 

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/custom-monitor.ts

@@ -0,0 +1,17 @@
+import * as Sentry from '@sentry/tanstackstart-react';
+import { createFileRoute } from '@tanstack/react-router';
+
+const USE_CUSTOM_TUNNEL_ROUTE = process.env.E2E_TEST_CUSTOM_TUNNEL_ROUTE === '1';
+
+const DEFAULT_DSN = 'https://public@dsn.ingest.sentry.io/1337';
+const TUNNEL_DSN = 'http://public@localhost:3031/1337';
+
+// Example of a manually defined tunnel endpoint without relying on the
+// managed route injected by `sentryTanstackStart({ tunnelRoute: ... })`.
+// If you use a custom route like this one, set `tunnel: '/custom-monitor'` in the client SDK's
+// `Sentry.init()` call so browser events are sent to the same endpoint.
+export const Route = createFileRoute('/custom-monitor')({
+ server: Sentry.createSentryTunnelRoute({
+ allowedDsns: [USE_CUSTOM_TUNNEL_ROUTE ? TUNNEL_DSN : DEFAULT_DSN],
+ }),
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/errors.test.ts

@@ -1,6 +1,11 @@
 import { expect, test } from '@playwright/test';
 import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
+const usesManagedTunnelRoute =
+ (process.env.E2E_TEST_TUNNEL_ROUTE_MODE ?? 'off') !== 'off' || process.env.E2E_TEST_CUSTOM_TUNNEL_ROUTE === '1';
+
+test.skip(usesManagedTunnelRoute, 'Default e2e suites run only in the proxy variant');
+
 test('Sends client-side error to Sentry with auto-instrumentation', async ({ page }) => {
  const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
  return errorEvent?.exception?.values?.[0]?.value === 'Sentry Client Test Error';

dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/middleware.test.ts

@@ -1,6 +1,11 @@
 import { expect, test } from '@playwright/test';
 import { waitForTransaction } from '@sentry-internal/test-utils';
 
+const usesManagedTunnelRoute =
+ (process.env.E2E_TEST_TUNNEL_ROUTE_MODE ?? 'off') !== 'off' || process.env.E2E_TEST_CUSTOM_TUNNEL_ROUTE === '1';
+
+test.skip(usesManagedTunnelRoute, 'Default e2e suites run only in the proxy variant');
+
 test('Sends spans for multiple middlewares and verifies they are siblings under the same parent span', async ({
  page,
 }) => {

dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/transaction.test.ts

@@ -1,6 +1,11 @@
 import { expect, test } from '@playwright/test';
 import { waitForTransaction } from '@sentry-internal/test-utils';
 
+const usesManagedTunnelRoute =
+ (process.env.E2E_TEST_TUNNEL_ROUTE_MODE ?? 'off') !== 'off' || process.env.E2E_TEST_CUSTOM_TUNNEL_ROUTE === '1';
+
+test.skip(usesManagedTunnelRoute, 'Default e2e suites run only in the proxy variant');
+
 test('Sends a server function transaction with auto-instrumentation', async ({ page }) => {
  const transactionEventPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
  return (

dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/tunnel.test.ts

@@ -0,0 +1,57 @@
+import { expect, test } from '@playwright/test';
+import { waitForError } from '@sentry-internal/test-utils';
+
+const tunnelRouteMode =
+ process.env.E2E_TEST_TUNNEL_ROUTE_MODE ?? (process.env.E2E_TEST_CUSTOM_TUNNEL_ROUTE === '1' ? 'custom' : 'off');
+const expectedTunnelPathMatcher =
+ tunnelRouteMode === 'static'
+ ? '/monitor'
+ : tunnelRouteMode === 'custom'
+ ? '/custom-monitor'
+ : tunnelRouteMode === 'object'
+ ? '/object-monitor'
+ : /^\/[a-z0-9]{8}$/;
+
+test.skip(tunnelRouteMode === 'off', 'Tunnel assertions only run in the tunnel-route variants');
+
+test('Sends client-side errors through the configured tunnel route', async ({ page }) => {
+ const errorEventPromise = waitForError('tanstackstart-react', errorEvent => {
+ return errorEvent?.exception?.values?.[0]?.value === 'Sentry Client Test Error';
+ });
+
+ await page.goto('/');
+ const pageOrigin = new URL(page.url()).origin;
+
+ await expect(page.locator('button').filter({ hasText: 'Break the client' })).toBeVisible();
+
+ const managedTunnelResponsePromise = page.waitForResponse(response => {
+ const responseUrl = new URL(response.url());
+
+ return (
+ responseUrl.origin === pageOrigin &&
+ response.request().method() === 'POST' &&
+ (typeof expectedTunnelPathMatcher === 'string'
+ ? responseUrl.pathname === expectedTunnelPathMatcher
+ : expectedTunnelPathMatcher.test(responseUrl.pathname))
+ );
+ });
+
+ await page.locator('button').filter({ hasText: 'Break the client' }).click();
+
+ const managedTunnelResponse = await managedTunnelResponsePromise;
+ const managedTunnelUrl = new URL(managedTunnelResponse.url());
+ const errorEvent = await errorEventPromise;
+
+ expect(managedTunnelResponse.status()).toBe(200);
+ expect(managedTunnelUrl.origin).toBe(pageOrigin);
+
+ if (typeof expectedTunnelPathMatcher === 'string') {
+ expect(managedTunnelUrl.pathname).toBe(expectedTunnelPathMatcher);
+ } else {
+ expect(managedTunnelUrl.pathname).toMatch(expectedTunnelPathMatcher);
+ expect(managedTunnelUrl.pathname).not.toBe('/monitor');
+ }
+
+ expect(errorEvent.exception?.values?.[0]?.value).toBe('Sentry Client Test Error');
+ expect(errorEvent.transaction).toBe('/');
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react/vite.config.ts

@@ -5,10 +5,44 @@ import viteReact from '@vitejs/plugin-react-swc';
 import { nitro } from 'nitro/vite';
 import { sentryTanstackStart } from '@sentry/tanstackstart-react/vite';
 
+const tunnelRouteMode = process.env.E2E_TEST_TUNNEL_ROUTE_MODE ?? 'off';
+const useManagedTunnelRoute = tunnelRouteMode !== 'off';
+const useCustomTunnelRoute = process.env.E2E_TEST_CUSTOM_TUNNEL_ROUTE === '1';
+
+const appDsn =
+ useManagedTunnelRoute || useCustomTunnelRoute
+ ? 'http://public@localhost:3031/1337'
+ : 'https://public@dsn.ingest.sentry.io/1337';
+
+const appTunnel = useManagedTunnelRoute
+ ? undefined
+ : useCustomTunnelRoute
+ ? '/custom-monitor'
+ : 'http://localhost:3031/';
+
+function resolveTunnelRouteOption() {
+ switch (tunnelRouteMode) {
+ case 'dynamic':
+ return true;
+ case 'static':
+ return '/monitor';
+ case 'object':
+ return { path: '/object-monitor', allowedDsns: [appDsn] };
+ default:
+ return undefined;
+ }
+}
+
+const tunnelRoute = resolveTunnelRouteOption();
+
 export default defineConfig({
  server: {
  port: 3000,
  },
+ define: {
+ __APP_DSN__: JSON.stringify(appDsn),
+ __APP_TUNNEL__: appTunnel === undefined ? 'undefined' : JSON.stringify(appTunnel),
+ },
  plugins: [
  tsConfigPaths(),
  tanstackStart(),
@@ -20,6 +54,7 @@ export default defineConfig({
  project: process.env.E2E_TEST_SENTRY_PROJECT,
  authToken: process.env.E2E_TEST_AUTH_TOKEN,
  debug: true,
+ tunnelRoute,
  }),
  ],
 });

packages/tanstackstart-react/src/client/index.ts

@@ -2,6 +2,7 @@
 // can be removed once following issue is fixed: https://github.com/import-js/eslint-plugin-import/issues/703
 /* eslint-disable import/export */
 import type { TanStackMiddlewareBase } from '../common/types';
+import type { CreateSentryTunnelRouteOptions } from '../server/tunnelRoute';
 
 export * from '@sentry/react';
 
@@ -26,3 +27,19 @@ export const sentryGlobalRequestMiddleware: TanStackMiddlewareBase = { '~types':
  * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
  */
 export const sentryGlobalFunctionMiddleware: TanStackMiddlewareBase = { '~types': undefined, options: {} };
+
+/**
+ * No-op stub for client-side builds.
+ * The actual implementation is server-only, but this stub is needed to prevent rendering errors.
+ */
+export function createSentryTunnelRoute(_options: CreateSentryTunnelRouteOptions): {
+ handlers: {
+ POST: () => Promise<Response>;
+ };
+} {
+ return {
+ handlers: {
+ POST: async () => new Response(null, { status: 500 }),
+ },
+ };
+}

packages/tanstackstart-react/src/client/sdk.ts

@@ -2,6 +2,7 @@ import type { Client } from '@sentry/core';
 import { applySdkMetadata } from '@sentry/core';
 import type { BrowserOptions as ReactBrowserOptions } from '@sentry/react';
 import { getDefaultIntegrations as getReactDefaultIntegrations, init as initReactSDK } from '@sentry/react';
+import { applyTunnelRouteOption } from './tunnelRoute';
 
 /**
  * Initializes the TanStack Start React SDK
@@ -14,6 +15,7 @@ export function init(options: ReactBrowserOptions): Client | undefined {
  ...options,
  };
 
+ applyTunnelRouteOption(sentryOptions);
  applySdkMetadata(sentryOptions, 'tanstackstart-react', ['tanstackstart-react', 'react']);
 
  return initReactSDK(sentryOptions);

packages/tanstackstart-react/src/client/tunnelRoute.ts

@@ -0,0 +1,35 @@
+import { consoleSandbox } from '@sentry/core';
+import type { BrowserOptions as ReactBrowserOptions } from '@sentry/react';
+
+declare const __SENTRY_TANSTACKSTART_TUNNEL_ROUTE__: string | undefined;
+
+let hasWarnedAboutManagedTunnelRouteOverride = false;
+
+/**
+ * Applies the managed tunnel route from `sentryTanstackStart({ tunnelRoute: ... })` unless the user already
+ * configured an explicit runtime `tunnel` option in `Sentry.init()`.
+ */
+export function applyTunnelRouteOption(options: ReactBrowserOptions): void {
+ const managedTunnelRoute =
+ typeof __SENTRY_TANSTACKSTART_TUNNEL_ROUTE__ !== 'undefined' ? __SENTRY_TANSTACKSTART_TUNNEL_ROUTE__ : undefined;
+
+ if (!managedTunnelRoute) {
+ return;
+ }
+
+ if (options.tunnel) {
+ if (!hasWarnedAboutManagedTunnelRouteOverride) {
+ hasWarnedAboutManagedTunnelRouteOverride = true;
+ consoleSandbox(() => {
+ // eslint-disable-next-line no-console
+ console.warn(
+ '[@sentry/tanstackstart-react] `Sentry.init({ tunnel: ... })` overrides the managed `sentryTanstackStart({ tunnelRoute: ... })` route. Remove the runtime `tunnel` option if you want the managed tunnel route to be used.',
+ );
+ });
+ }
+
+ return;
+ }
+
+ options.tunnel = managedTunnelRoute;
+}

packages/tanstackstart-react/src/index.types.ts

@@ -42,3 +42,4 @@ export declare const wrapMiddlewaresWithSentry: typeof serverSdk.wrapMiddlewares
 export declare const tanstackRouterBrowserTracingIntegration: typeof clientSdk.tanstackRouterBrowserTracingIntegration;
 export declare const sentryGlobalRequestMiddleware: typeof serverSdk.sentryGlobalRequestMiddleware;
 export declare const sentryGlobalFunctionMiddleware: typeof serverSdk.sentryGlobalFunctionMiddleware;
+export declare const createSentryTunnelRoute: typeof serverSdk.createSentryTunnelRoute;

packages/tanstackstart-react/src/server/index.ts

@@ -9,6 +9,7 @@ export { init } from './sdk';
 export { wrapFetchWithSentry } from './wrapFetchWithSentry';
 export { wrapMiddlewaresWithSentry } from './middleware';
 export { sentryGlobalRequestMiddleware, sentryGlobalFunctionMiddleware } from './globalMiddleware';
+export { createSentryTunnelRoute } from './tunnelRoute';
 
 /**
  * A no-op stub of the browser tracing integration for the server. Router setup code is shared between client and server,

packages/tanstackstart-react/src/server/tunnelRoute.ts

@@ -0,0 +1,60 @@
+import { dsnToString, getClient, handleTunnelRequest } from '@sentry/core';
+
+export interface CreateSentryTunnelRouteOptions {
+ allowedDsns?: string[];
+}
+
+type SentryTunnelRouteHandlerContext = {
+ request: Request;
+};
+
+type SentryTunnelRoute = {
+ handlers: {
+ POST: (context: SentryTunnelRouteHandlerContext) => Promise<Response>;
+ };
+};
+
+/**
+ * Creates a TanStack Start server route configuration for tunneling Sentry envelopes.
+ *
+ * @example
+ * ```ts
+ * import { createFileRoute } from '@tanstack/react-router';
+ * import * as Sentry from '@sentry/tanstackstart-react';
+ *
+ * export const Route = createFileRoute('/monitoring')({
+ * server: Sentry.createSentryTunnelRoute({
+ * allowedDsns: ['https://public@o0.ingest.sentry.io/0'],
+ * }),
+ * });
+ * ```
+ */
+export function createSentryTunnelRoute(options: CreateSentryTunnelRouteOptions): SentryTunnelRoute {
+ return {
+ handlers: {
+ POST: async ({ request }) => {
+ const allowedDsnsFromOptions = options.allowedDsns?.length ? options.allowedDsns : undefined;
+
+ const allowedDsns =
+ allowedDsnsFromOptions ??
+ (() => {
+ const client = getClient();
+ const dsn = client?.getDsn();
+ return dsn ? [dsnToString(dsn)] : undefined;
+ })();
+
+ if (!allowedDsns) {
+ return new Response(
+ 'Tunnel route requires Sentry server SDK initialized with a DSN, or pass allowedDsns explicitly.',
+ { status: 500 },
+ );
+ }
+
+ return handleTunnelRequest({
+ request,
+ allowedDsns,
+ });
+ },
+ },
+ };
+}

packages/tanstackstart-react/src/vite/index.ts

@@ -1,2 +1,3 @@
 export { sentryTanstackStart } from './sentryTanstackStart';
 export type { SentryTanstackStartOptions } from './sentryTanstackStart';
+export type { TunnelRouteOptions } from './tunnelRoute';