Refactor TanStack Start tunnel route handling

Author: nikolovlazar

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

@@ -9,14 +9,14 @@
     "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 pnpm build",
-    "test:build:tunnel-static": "pnpm install && E2E_TEST_TUNNEL_ROUTE_MODE=static 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-latest": "pnpm add @tanstack/react-start@latest @tanstack/react-router@latest && pnpm install && pnpm build",
     "test:assert:proxy": "pnpm test",
     "test:assert": "pnpm test:assert:proxy && E2E_TEST_TUNNEL_ROUTE_MODE=dynamic pnpm build && pnpm test:assert:tunnel-generated && E2E_TEST_TUNNEL_ROUTE_MODE=static pnpm build && pnpm test:assert:tunnel-static && E2E_TEST_CUSTOM_TUNNEL_ROUTE=1 pnpm build && pnpm test:assert:tunnel-custom",
-    "test:assert:tunnel-generated": "E2E_TEST_TUNNEL_ROUTE_MODE=dynamic pnpm test",
-    "test:assert:tunnel-static": "E2E_TEST_TUNNEL_ROUTE_MODE=static pnpm test",
+    "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"
   },
   "dependencies": {

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

@@ -21,9 +21,9 @@ const appTunnel = useManagedTunnelRoute
 
 const tunnelRoute =
   tunnelRouteMode === "dynamic"
-    ? { allowedDsns: [appDsn], tunnel: true as const }
+    ? true
     : tunnelRouteMode === "static"
-      ? { allowedDsns: [appDsn], tunnel: "/monitor" }
+      ? "/monitor"
       : undefined;
 
 export default defineConfig({

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

@@ -1,7 +1,7 @@
-import { handleTunnelRequest } from '@sentry/core';
+import { dsnToString, getClient, handleTunnelRequest } from '@sentry/core';
 
 export interface CreateSentryTunnelRouteOptions {
-  allowedDsns: string[];
+  allowedDsns?: string[];
 }
 
 type SentryTunnelRouteHandlerContext = {
@@ -33,9 +33,27 @@ export function createSentryTunnelRoute(options: CreateSentryTunnelRouteOptions)
   return {
     handlers: {
       POST: async ({ request }) => {
+        const allowedDsnsFromOptions =
+          options.allowedDsns && options.allowedDsns.length > 0 ? 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: options.allowedDsns,
+          allowedDsns,
         });
       },
     },

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

@@ -26,8 +26,13 @@ export interface SentryTanstackStartOptions extends BuildTimeOptionsBase {
    * Configures a framework-managed same-origin tunnel route for Sentry envelopes.
    *
    * This creates a TanStack Start server route backed by `createSentryTunnelRoute()` and applies the resulting path
-   * as the default `tunnel` option on the client. Use `tunnel: true` to generate an opaque route path per dev session
-   * or production build, or provide a static absolute path string to control the route name yourself.
+   * as the default `tunnel` option on the client.
+   *
+   * You can pass:
+   * - `true` to generate an opaque route path per dev session or production build.
+   * - `'/custom-path'` to use a fixed static route path.
+   * - `{ allowedDsns, path }` for full control. If `allowedDsns` is omitted or empty, the tunnel route derives the DSN
+   *   from the active server Sentry client at runtime.
    *
    * If you also pass `tunnel` to `Sentry.init()`, that explicit runtime option wins and a warning is emitted because
    * the managed tunnel route is being bypassed.

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

@@ -65,7 +65,9 @@ export function makeAddSentryVitePlugin(options: BuildTimeOptionsBase): Plugin[]
       assets: sourcemaps?.assets,
       disable: sourcemaps?.disable,
       ignore: sourcemaps?.ignore,
-      rewriteSources: sourcemaps?.rewriteSources,
+      // BuildTimeOptionsBase types can lag behind bundler plugin options in some local setups.
+      // Keep runtime support while staying resilient to type version skew.
+      rewriteSources: (sourcemaps as unknown as { rewriteSources?: unknown } | undefined)?.rewriteSources as never,
       filesToDeleteAfterUpload: filesToDeleteAfterUploadPromise,
     },
     telemetry: telemetry ?? true,

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

@@ -1,21 +1,23 @@
 import type { Plugin } from "vite";
 
-export interface TunnelRouteOptions {
-  /**
-   * A list of DSNs that are allowed to use the managed tunnel route.
-   */
-  allowedDsns: string[];
-
-  /**
-   * Controls the public route path used by the managed tunnel route.
-   *
-   * - `true` generates an opaque path once per dev session or production build.
-   * - `'/custom-path'` uses a fixed absolute route path.
-   *
-   * @default true
-   */
-  tunnel?: true | string;
-}
+export type TunnelRouteOptions =
+  | true
+  | string
+  | {
+      /**
+       * A list of DSNs that are allowed to use the managed tunnel route.
+       *
+       * If omitted or empty, the tunnel route will derive the allowed DSN from the active server Sentry SDK at runtime.
+       */
+      allowedDsns?: string[];
+
+      /**
+       * Controls the public route path used by the managed tunnel route.
+       *
+       * If omitted, an opaque path is generated once per dev session or production build.
+       */
+      path?: string;
+    };
 
 const MANAGED_TUNNEL_ROUTE_IMPORT = "SentryManagedTunnelRouteImport";
 const MANAGED_TUNNEL_ROUTE_NAME = "SentryManagedTunnelRoute";
@@ -48,27 +50,45 @@ export function resolveTunnelRoute(tunnel: true | string): string {
   return resolvedTunnelRoute;
 }
 
-function validateTunnelRouteOptions(options: TunnelRouteOptions): string {
-  if (options.allowedDsns.length === 0) {
+type NormalizedTunnelRouteOptions = {
+  resolvedPath: string;
+  allowedDsns: string[] | undefined;
+};
+
+function validateStaticPath(path: string): void {
+  if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
     throw new Error(
-      "[@sentry/tanstackstart-react] `sentryTanstackStart({ tunnelRoute })` requires at least one allowed DSN.",
+      "[@sentry/tanstackstart-react] `tunnelRoute` static paths must start with `/` and must not contain query or hash segments.",
     );
   }
+}
+
+function normalizeTunnelRouteOptions(
+  options: TunnelRouteOptions,
+): NormalizedTunnelRouteOptions {
+  if (options === true) {
+    return { resolvedPath: resolveTunnelRoute(true), allowedDsns: undefined };
+  }
 
-  const tunnelRoute = options.tunnel ?? true;
+  if (typeof options === "string") {
+    validateStaticPath(options);
+    return {
+      resolvedPath: resolveTunnelRoute(options),
+      allowedDsns: undefined,
+    };
+  }
 
-  if (
-    typeof tunnelRoute === "string" &&
-    (!tunnelRoute.startsWith("/") ||
-      tunnelRoute.includes("?") ||
-      tunnelRoute.includes("#"))
-  ) {
-    throw new Error(
-      "[@sentry/tanstackstart-react] `tunnelRoute.tunnel` must be `true` or an absolute route path starting with `/` and without query or hash segments.",
-    );
+  const allowedDsns =
+    options.allowedDsns && options.allowedDsns.length > 0
+      ? options.allowedDsns
+      : undefined;
+  const path = options.path;
+
+  if (path) {
+    validateStaticPath(path);
   }
 
-  return resolveTunnelRoute(tunnelRoute);
+  return { resolvedPath: resolveTunnelRoute(path ?? true), allowedDsns };
 }
 
 function hasRouteConflict(
@@ -146,9 +166,12 @@ export function makeTunnelRoutePlugin(
   options: TunnelRouteOptions,
   debug?: boolean,
 ): Plugin {
-  const resolvedTunnelRoute = validateTunnelRouteOptions(options);
+  const normalized = normalizeTunnelRouteOptions(options);
+  const resolvedTunnelRoute = normalized.resolvedPath;
   const serializedTunnelRoute = JSON.stringify(resolvedTunnelRoute);
-  const serializedAllowedDsns = JSON.stringify(options.allowedDsns);
+  const serializedAllowedDsns = normalized.allowedDsns
+    ? JSON.stringify(normalized.allowedDsns)
+    : undefined;
 
   if (debug) {
     // eslint-disable-next-line no-console
@@ -184,9 +207,7 @@ export const Route = createFileRoute(${serializedTunnelRoute})({
     handlers: {
       async POST({ request }) {
         const Sentry = await import('@sentry/tanstackstart-react');
-        return Sentry.createSentryTunnelRoute({
-          allowedDsns: ${serializedAllowedDsns},
-        }).handlers.POST({ request });
+        return Sentry.createSentryTunnelRoute(${serializedAllowedDsns ? `{ allowedDsns: ${serializedAllowedDsns} }` : `{}`}).handlers.POST({ request });
       },
     },
   },

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

@@ -1,12 +1,14 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 const handleTunnelRequestSpy = vi.fn();
+const getClientSpy = vi.fn();
 
 vi.mock('@sentry/core', async importOriginal => {
   const original = await importOriginal();
   return {
     ...original,
     handleTunnelRequest: (...args: unknown[]) => handleTunnelRequestSpy(...args),
+    getClient: (...args: unknown[]) => getClientSpy(...args),
   };
 });
 
@@ -45,4 +47,46 @@ describe('createSentryTunnelRoute', () => {
     expect(options.allowedDsns).toBe(allowedDsns);
     expect(result).toBe(response);
   });
+
+  it('derives the allowed DSN from the active server Sentry client when allowedDsns is omitted', async () => {
+    const request = new Request('http://localhost:3000/monitoring', { method: 'POST', body: 'envelope' });
+    const response = new Response('ok', { status: 200 });
+
+    getClientSpy.mockReturnValueOnce({
+      getDsn: () => ({
+        protocol: 'http',
+        publicKey: 'public',
+        pass: '',
+        host: 'localhost',
+        port: '3031',
+        path: '',
+        projectId: '1337',
+      }),
+    });
+    handleTunnelRequestSpy.mockResolvedValueOnce(response);
+
+    const route = createSentryTunnelRoute({});
+    const result = await route.handlers.POST({ request });
+
+    expect(handleTunnelRequestSpy).toHaveBeenCalledTimes(1);
+    const [options] = handleTunnelRequestSpy.mock.calls[0]!;
+    expect(options).toEqual({
+      request,
+      allowedDsns: ['http://public@localhost:3031/1337'],
+    });
+    expect(result).toBe(response);
+  });
+
+  it('returns 500 when allowedDsns is omitted and no active server Sentry client DSN exists', async () => {
+    const request = new Request('http://localhost:3000/monitoring', { method: 'POST', body: 'envelope' });
+
+    getClientSpy.mockReturnValueOnce(undefined);
+
+    const route = createSentryTunnelRoute({});
+    const result = await route.handlers.POST({ request });
+
+    expect(handleTunnelRequestSpy).not.toHaveBeenCalled();
+    expect(result.status).toBe(500);
+    await expect(result.text()).resolves.toContain('Tunnel route requires Sentry server SDK initialized with a DSN');
+  });
 });

packages/tanstackstart-react/test/vite/tunnelRoute.test.ts

@@ -61,15 +61,15 @@ describe('tunnelRoute vite plugin', () => {
     expect(resolveTunnelRoute('/monitor')).toBe('/monitor');
   });
 
-  it('rejects empty allowedDsns', () => {
-    expect(() => makeTunnelRoutePlugin({ allowedDsns: [] })).toThrow(
-      '`sentryTanstackStart({ tunnelRoute })` requires at least one allowed DSN',
-    );
-  });
-
   it('rejects invalid static tunnel routes', () => {
-    expect(() => makeTunnelRoutePlugin({ allowedDsns: ['https://public@o0.ingest.sentry.io/0'], tunnel: 'monitor' })).toThrow(
-      '`tunnelRoute.tunnel` must be `true` or an absolute route path',
+    expect(() => makeTunnelRoutePlugin('monitor')).toThrow(
+      'static paths must start with `/` and must not contain query or hash segments',
+    );
+    expect(() => makeTunnelRoutePlugin('/monitor?x=1')).toThrow(
+      'static paths must start with `/` and must not contain query or hash segments',
+    );
+    expect(() => makeTunnelRoutePlugin({ path: 'monitor' })).toThrow(
+      'static paths must start with `/` and must not contain query or hash segments',
     );
   });
 
@@ -102,7 +102,7 @@ describe('tunnelRoute vite plugin', () => {
   it('loads a virtual managed tunnel route module for a static tunnel path', async () => {
     const plugin = makeTunnelRoutePlugin({
       allowedDsns: ['http://public@localhost:3031/1337'],
-      tunnel: '/monitor',
+      path: '/monitor',
     });
 
     expect(plugin.config && plugin.config()).toEqual({
@@ -121,4 +121,14 @@ describe('tunnelRoute vite plugin', () => {
     expect(virtualRouteModule).toContain('createFileRoute("/monitor")');
     expect(virtualRouteModule).toContain('allowedDsns: ["http://public@localhost:3031/1337"]');
   });
+
+  it('omits allowedDsns from the virtual managed tunnel route module when not provided', async () => {
+    const plugin = makeTunnelRoutePlugin('/monitor');
+
+    const virtualRouteModule =
+      plugin.load && (await plugin.load('\0virtual:sentry-tanstackstart-react/tunnel-route'));
+
+    expect(virtualRouteModule).toContain('createFileRoute("/monitor")');
+    expect(virtualRouteModule).toContain('createSentryTunnelRoute({})');
+  });
 });