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

CHANGELOG.md

@@ -12,6 +12,10 @@
 
  Server and client traces are now automatically connected, allowing you to see the full request lifecycle from server-side rendering through client-side hydration in a single trace.
 
+- **feat(tanstackstart-react): Add server-side route parametrization ([#21147](https://github.com/getsentry/sentry-javascript/pull/21147))**
+
+ Server transaction names are now parametrized automatically (e.g., `GET /users/123` becomes `GET /users/$userId`), improving transaction grouping in Sentry.
+
 ## 10.54.0
 
 ### Important Changes

dev-packages/e2e-tests/test-applications/tanstackstart-react/src/routes/api.user.$id.ts

@@ -0,0 +1,13 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/api/user/$id')({
+ server: {
+ handlers: {
+ GET: async ({ params }) => {
+ return new Response(JSON.stringify({ id: params.id }), {
+ headers: { 'Content-Type': 'application/json' },
+ });
+ },
+ },
+ },
+});

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/src/routes/users.$userId.tsx

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

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

@@ -0,0 +1,13 @@
+import { Outlet, createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/users')({
+ component: UsersLayout,
+});
+
+function UsersLayout() {
+ return (
+ <div>
+ <Outlet />
+ </div>
+ );
+}

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

@@ -0,0 +1,82 @@
+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 and client 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/')
+ );
+ });
+
+ const clientTxPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return (
+ transactionEvent?.contexts?.trace?.op === 'pageload' &&
+ typeof transactionEvent?.transaction === 'string' &&
+ transactionEvent.transaction.includes('/param/')
+ );
+ });
+
+ await page.goto('/param/42');
+
+ const serverTx = await serverTxPromise;
+ const clientTx = await clientTxPromise;
+
+ expect(serverTx.transaction).toBe('GET /param/$id');
+ expect(serverTx.transaction_info?.source).toBe('route');
+
+ expect(clientTx.transaction).toBe('/param/$id');
+ expect(clientTx.transaction_info?.source).toBe('route');
+});
+
+test('should parametrize server and client transaction names for nested dynamic routes', async ({ page }) => {
+ const serverTxPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return (
+ transactionEvent?.contexts?.trace?.op === 'http.server' &&
+ typeof transactionEvent?.transaction === 'string' &&
+ transactionEvent.transaction.includes('/users/')
+ );
+ });
+
+ const clientTxPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return (
+ transactionEvent?.contexts?.trace?.op === 'pageload' &&
+ typeof transactionEvent?.transaction === 'string' &&
+ transactionEvent.transaction.includes('/users/')
+ );
+ });
+
+ await page.goto('/users/123');
+
+ const serverTx = await serverTxPromise;
+ const clientTx = await clientTxPromise;
+
+ expect(serverTx.transaction).toBe('GET /users/$userId');
+ expect(serverTx.transaction_info?.source).toBe('route');
+
+ expect(clientTx.transaction).toBe('/users/$userId');
+ expect(clientTx.transaction_info?.source).toBe('route');
+});
+
+test('should parametrize API route transaction names', async ({ baseURL }) => {
+ const serverTxPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return (
+ transactionEvent?.contexts?.trace?.op === 'http.server' &&
+ typeof transactionEvent?.transaction === 'string' &&
+ transactionEvent.transaction.includes('/api/user/')
+ );
+ });
+
+ await fetch(`${baseURL}/api/user/456`);
+
+ const serverTx = await serverTxPromise;
+
+ expect(serverTx.transaction).toBe('GET /api/user/$id');
+ expect(serverTx.transaction_info?.source).toBe('route');
+});

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

@@ -0,0 +1,66 @@
+import { ATTR_HTTP_ROUTE } from '@opentelemetry/semantic-conventions';
+import {
+ escapeStringForRegex,
+ getActiveSpan,
+ getCurrentScope,
+ getRootSpan,
+ SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+ spanToJSON,
+ updateSpanName,
+} from '@sentry/core';
+
+function patternToRegex(pattern: string): RegExp {
+ const segments = pattern
+ .split('/')
+ .map(segment => {
+ if (segment.startsWith('$')) {
+ return '[^/]+';
+ }
+ return escapeStringForRegex(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 expected to be pre-sorted by specificity (more segments first, static before dynamic).
+ */
+export function matchUrlToRoutePattern(pathname: string, patterns: string[]): string | undefined {
+ const normalizedPathname = pathname.length > 1 ? pathname.replace(/\/$/, '') : pathname;
+ for (const pattern of patterns) {
+ if (patternToRegex(pattern).test(normalizedPathname)) {
+ 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;
+ }
+
+ const transactionName = `${method} ${matchedPattern}`;
+ updateSpanName(rootSpan, transactionName);
+ rootSpan.setAttribute(ATTR_HTTP_ROUTE, matchedPattern);
+ rootSpan.setAttribute(SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, 'route');
+ getCurrentScope().setTransactionName(transactionName);
+}

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

@@ -5,8 +5,11 @@ import {
  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;
 };
@@ -161,6 +164,10 @@ export function wrapFetchWithSentry(serverEntry: ServerEntry): ServerEntry {
  );
  }
 
+ if (typeof __SENTRY_ROUTE_PATTERNS__ !== 'undefined') {
+ updateSpanWithRouteParametrization(method, url.pathname, __SENTRY_ROUTE_PATTERNS__);
+ }
+
  return injectMetaTagsInResponse(await target.apply(thisArg, args));
  } finally {
  await flushIfServerless();

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

@@ -0,0 +1,81 @@
+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.
+ *
+ * The route tree file is read during `transform` rather than `config` because
+ * TanStack Start generates it during the build.
+ */
+export function makeRoutePatternPlugin(): Plugin {
+ let resolvedRoot = '';
+
+ return {
+ name: 'sentry-tanstackstart-route-patterns',
+ enforce: 'post',
+
+ configResolved(config) {
+ resolvedRoot = config.root || process.cwd();
+ },
+
+ transform(code, id) {
+ // this is set in the `wrapFetchWithSentry` where the paths are getting replaced by their parametrized counterparts
+ // so this extraction should only happen once during the build (for the `wrapFetchWithSentry` file)
+ if (!code.includes('__SENTRY_ROUTE_PATTERNS__')) {
+ return null;
+ }
+
+ // extract the patterns from the route tree file
+ 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 full route path patterns from the content of routeTree.gen.ts.
+ *
+ * Parses the `fullPaths` type union which contains the resolved full paths
+ * (e.g., `fullPaths: '/' | '/page-a' | '/users/$userId'`).
+ * This is more reliable than `path:` properties which can be relative for nested routes.
+ */
+export function extractRoutePatterns(content: string): string[] {
+ const fullPathsMatch = content.match(/fullPaths:\s*([\s\S]*?)(?:\n\s*\w|\n\})/);
+ if (!fullPathsMatch) {
+ return [];
+ }
+
+ const patterns: string[] = [];
+ const pathRegex = /['"]([^'"]+)['"]/g;
+ let match;
+ while ((match = pathRegex.exec(fullPathsMatch[1] || '')) !== null) {
+ if (match[1]) {
+ patterns.push(match[1]);
+ }
+ }
+
+ return [...new Set(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;
+ });
+}

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';
@@ -84,18 +85,18 @@ export interface SentryTanstackStartOptions extends BuildTimeOptionsBase {
  * @returns An array of Vite plugins
  */
 export function sentryTanstackStart(options: SentryTanstackStartOptions = {}): Plugin[] {
- const tunnelRoutePlugin = options.tunnelRoute ? makeTunnelRoutePlugin(options.tunnelRoute, options.debug) : undefined;
+ const plugins: Plugin[] = [makeRoutePatternPlugin()];
+
+ if (options.tunnelRoute) {
+ plugins.push(makeTunnelRoutePlugin(options.tunnelRoute, options.debug));
+ }
 
  // only add build-time plugins in production builds
  if (process.env.NODE_ENV === 'development') {
- return tunnelRoutePlugin ? [tunnelRoutePlugin] : [];
+ return plugins;
  }
 
- const plugins: Plugin[] = [...makeAddSentryVitePlugin(options)];
-
- if (tunnelRoutePlugin) {
- plugins.push(tunnelRoutePlugin);
- }
+ plugins.push(...makeAddSentryVitePlugin(options));
 
  // middleware auto-instrumentation
  if (options.autoInstrumentMiddleware !== false) {