Merge pull request #20264 from getsentry/lazarnikolov/js-2140-tanstack-start-tunnel-adapter

nikolovlazar · web-flow · commit 5ee2da471b45 · 2026-04-23T15:16:04.000-04:00
Tunnel route helper + Dynamic tunnel route generator for TanStack Start React
diff --git a/dev-packages/e2e-tests/test-applications/tanstackstart-react/package.json b/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"
+      }
+    ]
   }
 }
diff --git a/dev-packages/e2e-tests/test-applications/tanstackstart-react/src/globals.d.ts b/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;
diff --git a/dev-packages/e2e-tests/test-applications/tanstackstart-react/src/router.tsx b/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__,
     });
   }
 
diff --git a/dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/custom-monitor.ts b/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],
+  }),
+});
diff --git a/dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/errors.test.ts b/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';
diff --git a/dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/middleware.test.ts b/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,
 }) => {
diff --git a/dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/transaction.test.ts b/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 (
diff --git a/dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/tunnel.test.ts b/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('/');
+});
diff --git a/dev-packages/e2e-tests/test-applications/tanstackstart-react/vite.config.ts b/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,
     }),
   ],
 });
diff --git a/packages/tanstackstart-react/src/client/index.ts b/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 }),
+    },
+  };
+}
diff --git a/packages/tanstackstart-react/src/client/sdk.ts b/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);
diff --git a/packages/tanstackstart-react/src/client/tunnelRoute.ts b/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;
+}
diff --git a/packages/tanstackstart-react/src/index.types.ts b/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;
diff --git a/packages/tanstackstart-react/src/server/index.ts b/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,
diff --git a/packages/tanstackstart-react/src/server/tunnelRoute.ts b/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,
+        });
+      },
+    },
+  };
+}
diff --git a/packages/tanstackstart-react/src/vite/index.ts b/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';
diff --git a/packages/tanstackstart-react/src/vite/sentryTanstackStart.ts b/packages/tanstackstart-react/src/vite/sentryTanstackStart.ts
diff --git a/packages/tanstackstart-react/src/vite/sourceMaps.ts b/packages/tanstackstart-react/src/vite/sourceMaps.ts
diff --git a/packages/tanstackstart-react/src/vite/tunnelRoute.ts b/packages/tanstackstart-react/src/vite/tunnelRoute.ts
diff --git a/packages/tanstackstart-react/test/client/sdk.test.ts b/packages/tanstackstart-react/test/client/sdk.test.ts
diff --git a/packages/tanstackstart-react/test/client/tunnelRoute.test.ts b/packages/tanstackstart-react/test/client/tunnelRoute.test.ts
diff --git a/packages/tanstackstart-react/test/server/tunnelRoute.test.ts b/packages/tanstackstart-react/test/server/tunnelRoute.test.ts
diff --git a/packages/tanstackstart-react/test/vite/sentryTanstackStart.test.ts b/packages/tanstackstart-react/test/vite/sentryTanstackStart.test.ts
diff --git a/packages/tanstackstart-react/test/vite/tunnelRoute.test.ts b/packages/tanstackstart-react/test/vite/tunnelRoute.test.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+declare const __APP_DSN__: string;`
	`2`	`+declare const __APP_TUNNEL__: string \| undefined;`