feat(tanstackstart-react): Add server-side route parametrization

Extracts route patterns from routeTree.gen.ts at build time and matches URLs at runtime to parametrize server transaction names (e.g., `GET /users/123` becomes `GET /users/$id`).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nicohrubec

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/param.$id.tsx

@@ -0,0 +1,14 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/param/$id')({
+  component: ParamPage,
+});
+
+function ParamPage() {
+  const { id } = Route.useParams();
+  return (
+    <div>
+      <p id="param-value">Param: {id}</p>
+    </div>
+  );
+}

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

@@ -0,0 +1,23 @@
+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('should parametrize server transaction names for dynamic routes', async ({ page }) => {
+  const serverTxPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+    return (
+      transactionEvent?.contexts?.trace?.op === 'http.server' &&
+      typeof transactionEvent?.transaction === 'string' &&
+      transactionEvent.transaction.includes('/param/')
+    );
+  });
+
+  await page.goto('/param/42');
+
+  const serverTx = await serverTxPromise;
+
+  expect(serverTx.transaction).toBe('GET /param/$id');
+});

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

@@ -0,0 +1,70 @@
+import { ATTR_HTTP_ROUTE } from '@opentelemetry/semantic-conventions';
+import { getActiveSpan, getRootSpan, SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, spanToJSON, updateSpanName } from '@sentry/core';
+
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function patternToRegex(pattern: string): RegExp {
+  const segments = pattern
+    .split('/')
+    .map(segment => {
+      if (segment.startsWith('$')) {
+        return '[^/]+';
+      }
+      return escapeRegex(segment);
+    })
+    .join('/');
+  return new RegExp(`^${segments}$`);
+}
+
+/**
+ * Matches a URL pathname against a list of TanStack Start route patterns.
+ * Patterns use `$param` syntax for dynamic segments (e.g., `/users/$id`).
+ *
+ * Patterns are sorted by specificity: more segments first, static segments before dynamic.
+ */
+export function matchUrlToRoutePattern(pathname: string, patterns: string[]): string | undefined {
+  const sorted = [...patterns].sort((a, b) => {
+    const aSegments = a.split('/');
+    const bSegments = b.split('/');
+    if (bSegments.length !== aSegments.length) {
+      return bSegments.length - aSegments.length;
+    }
+    const aDynamic = aSegments.filter(s => s.startsWith('$')).length;
+    const bDynamic = bSegments.filter(s => s.startsWith('$')).length;
+    return aDynamic - bDynamic;
+  });
+
+  for (const pattern of sorted) {
+    if (patternToRegex(pattern).test(pathname)) {
+      return pattern;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Updates the active root span with a parametrized route name.
+ */
+export function updateSpanWithRouteParametrization(method: string, pathname: string, patterns: string[]): void {
+  const matchedPattern = matchUrlToRoutePattern(pathname, patterns);
+  if (!matchedPattern) {
+    return;
+  }
+
+  const activeSpan = getActiveSpan();
+  if (!activeSpan) {
+    return;
+  }
+
+  const rootSpan = getRootSpan(activeSpan);
+  const rootSpanData = spanToJSON(rootSpan).data;
+  if (rootSpanData?.[ATTR_HTTP_ROUTE]) {
+    return;
+  }
+
+  updateSpanName(rootSpan, `${method} ${matchedPattern}`);
+  rootSpan.setAttribute(ATTR_HTTP_ROUTE, matchedPattern);
+  rootSpan.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+}

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

@@ -1,7 +1,10 @@
 import { flushIfServerless } from '@sentry/core';
 import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/node';
+import { updateSpanWithRouteParametrization } from './routeParametrization';
 import { extractServerFunctionSha256 } from './utils';
 
+declare const __SENTRY_ROUTE_PATTERNS__: string[] | undefined;
+
 export type ServerEntry = {
   fetch: (request: Request, opts?: unknown) => Promise<Response> | Response;
 };
@@ -62,6 +65,10 @@ export function wrapFetchWithSentry(serverEntry: ServerEntry): ServerEntry {
             );
           }
 
+          if (typeof __SENTRY_ROUTE_PATTERNS__ !== 'undefined') {
+            updateSpanWithRouteParametrization(method, url.pathname, __SENTRY_ROUTE_PATTERNS__);
+          }
+
           return await target.apply(thisArg, args);
         } finally {
           await flushIfServerless();

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

@@ -0,0 +1,64 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { Plugin } from 'vite';
+
+/**
+ * Extracts route patterns from TanStack Start's generated routeTree.gen.ts
+ * and replaces `__SENTRY_ROUTE_PATTERNS__` references with the extracted patterns.
+ *
+ * Reads the route tree lazily during `transform` to ensure it exists after TanStack Start generates it.
+ */
+export function makeRoutePatternPlugin(): Plugin {
+  let resolvedRoot = '';
+
+  return {
+    name: 'sentry-tanstackstart-route-patterns',
+    enforce: 'post',
+
+    configResolved(config) {
+      resolvedRoot = config.root || process.cwd();
+    },
+
+    transform(code, id) {
+      if (!code.includes('__SENTRY_ROUTE_PATTERNS__')) {
+        return null;
+      }
+
+      const routeTreePath = path.resolve(resolvedRoot, 'src/routeTree.gen.ts');
+      let patterns: string[] = ['/'];
+      try {
+        if (fs.existsSync(routeTreePath)) {
+          patterns = extractRoutePatterns(fs.readFileSync(routeTreePath, 'utf-8'));
+        }
+      } catch {
+        // skip
+      }
+
+      return {
+        code: code.replace(/__SENTRY_ROUTE_PATTERNS__/g, JSON.stringify(patterns)),
+        map: null,
+      };
+    },
+  };
+}
+
+/**
+ * Extracts route path patterns from the content of routeTree.gen.ts.
+ *
+ * Matches patterns like: `path: '/page-b/$id'`
+ *
+ * Only exported for testing.
+ */
+export function extractRoutePatterns(content: string): string[] {
+  const patterns: string[] = [];
+  const regex = /path:\s*['"]([^'"]+)['"]/g;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const pattern = match[1];
+    if (pattern && pattern !== '/') {
+      patterns.push(pattern);
+    }
+  }
+  patterns.push('/');
+  return [...new Set(patterns)];
+}

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

@@ -1,6 +1,7 @@
 import type { BuildTimeOptionsBase } from '@sentry/core';
 import type { Plugin } from 'vite';
 import { makeAutoInstrumentMiddlewarePlugin } from './autoInstrumentMiddleware';
+import { makeRoutePatternPlugin } from './routePatterns';
 import { makeAddSentryVitePlugin, makeEnableSourceMapsVitePlugin } from './sourceMaps';
 import type { TunnelRouteOptions } from './tunnelRoute';
 import { makeTunnelRoutePlugin } from './tunnelRoute';
@@ -67,12 +68,16 @@ export interface SentryTanstackStartOptions extends BuildTimeOptionsBase {
 export function sentryTanstackStart(options: SentryTanstackStartOptions = {}): Plugin[] {
   const tunnelRoutePlugin = options.tunnelRoute ? makeTunnelRoutePlugin(options.tunnelRoute, options.debug) : undefined;
 
-  // only add build-time plugins in production builds
+  // In development, only add route patterns plugin and tunnel route
   if (process.env.NODE_ENV === 'development') {
-    return tunnelRoutePlugin ? [tunnelRoutePlugin] : [];
+    const devPlugins: Plugin[] = [makeRoutePatternPlugin()];
+    if (tunnelRoutePlugin) {
+      devPlugins.push(tunnelRoutePlugin);
+    }
+    return devPlugins;
   }
 
-  const plugins: Plugin[] = [...makeAddSentryVitePlugin(options)];
+  const plugins: Plugin[] = [makeRoutePatternPlugin(), ...makeAddSentryVitePlugin(options)];
 
   if (tunnelRoutePlugin) {
     plugins.push(tunnelRoutePlugin);

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

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { matchUrlToRoutePattern } from '../../src/server/routeParametrization';
+
+describe('matchUrlToRoutePattern', () => {
+  const patterns = ['/', '/page-a', '/page-b/$id', '/users/$userId/posts/$postId', '/api/health'];
+
+  it('matches the root route', () => {
+    expect(matchUrlToRoutePattern('/', patterns)).toBe('/');
+  });
+
+  it('matches a static route', () => {
+    expect(matchUrlToRoutePattern('/page-a', patterns)).toBe('/page-a');
+  });
+
+  it('matches a single-param route', () => {
+    expect(matchUrlToRoutePattern('/page-b/42', patterns)).toBe('/page-b/$id');
+  });
+
+  it('matches a multi-param route', () => {
+    expect(matchUrlToRoutePattern('/users/123/posts/456', patterns)).toBe('/users/$userId/posts/$postId');
+  });
+
+  it('matches a static API route', () => {
+    expect(matchUrlToRoutePattern('/api/health', patterns)).toBe('/api/health');
+  });
+
+  it('returns undefined for unmatched paths', () => {
+    expect(matchUrlToRoutePattern('/unknown', patterns)).toBeUndefined();
+  });
+
+  it('returns undefined for partially matched paths', () => {
+    expect(matchUrlToRoutePattern('/page-b', patterns)).toBeUndefined();
+  });
+
+  it('prefers static over dynamic matches', () => {
+    const patternsWithOverlap = ['/page-b/$id', '/page-b/special'];
+    expect(matchUrlToRoutePattern('/page-b/special', patternsWithOverlap)).toBe('/page-b/special');
+  });
+
+  it('prefers more specific routes (more segments)', () => {
+    const patternsNested = ['/users/$id', '/users/$id/profile'];
+    expect(matchUrlToRoutePattern('/users/123/profile', patternsNested)).toBe('/users/$id/profile');
+  });
+});

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

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { extractRoutePatterns } from '../../src/vite/routePatterns';
+
+describe('extractRoutePatterns', () => {
+  it('extracts route patterns from routeTree.gen.ts content', () => {
+    const content = `
+const PageARoute = PageARouteImport.update({
+  id: '/page-a',
+  path: '/page-a',
+  getParentRoute: () => rootRouteImport,
+})
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+})
+const PageBIdRoute = PageBIdRouteImport.update({
+  id: '/page-b/$id',
+  path: '/page-b/$id',
+  getParentRoute: () => rootRouteImport,
+})
+`;
+    const patterns = extractRoutePatterns(content);
+    expect(patterns).toContain('/page-a');
+    expect(patterns).toContain('/page-b/$id');
+    expect(patterns).toContain('/');
+  });
+
+  it('always includes the root route', () => {
+    const patterns = extractRoutePatterns('');
+    expect(patterns).toEqual(['/']);
+  });
+
+  it('handles nested routes', () => {
+    const content = `
+const UsersIdRoute = UsersIdRouteImport.update({
+  id: '/users/$userId',
+  path: '/users/$userId',
+})
+const UsersIdPostsRoute = UsersIdPostsRouteImport.update({
+  id: '/users/$userId/posts/$postId',
+  path: '/users/$userId/posts/$postId',
+})
+`;
+    const patterns = extractRoutePatterns(content);
+    expect(patterns).toContain('/users/$userId');
+    expect(patterns).toContain('/users/$userId/posts/$postId');
+  });
+});