fix(nextjs): Register the route provider before the pageload span is named

The provider was registered after `reactInit` returned, but the pageload span is
named in `browserTracingIntegration`'s `afterAllSetup`, which runs inside it. So
every App Router pageload lost its parameterized name.

Registering it from a default integration's `setup` runs it before any
`afterAllSetup` while still not depending on tracing.

Author: logaretm

packages/nextjs/src/client/index.ts

@@ -3,7 +3,6 @@
 /* eslint-disable import/export */
 import type { Client, EventProcessor, Integration } from '@sentry/core';
 import { addEventProcessor, applySdkMetadata, consoleSandbox, getGlobalScope, GLOBAL_OBJ } from '@sentry/core';
-import { setRouteProvider } from '@sentry/core/browser';
 import type { BrowserOptions } from '@sentry/react';
 import { getDefaultIntegrations as getReactDefaultIntegrations, init as reactInit } from '@sentry/react';
 import { DEBUG_BUILD } from '../common/debug-build';
@@ -13,7 +12,7 @@ import { isRedirectNavigationError } from '../common/nextNavigationErrorUtils';
 import { browserTracingIntegration } from './browserTracingIntegration';
 import { nextjsClientStackFrameNormalizationIntegration } from './clientNormalizationIntegration';
 import { removeIsrSsgTraceMetaTags } from './routing/isrRoutingTracing';
-import { createNextRouteProvider } from './routing/routeProvider';
+import { nextjsRouteProviderIntegration } from './routing/routeProvider';
 import { applyTunnelRouteOption } from './tunnelRoute';
 
 export * from '@sentry/react';
@@ -81,11 +80,6 @@ export function init(options: BrowserOptions): Client | undefined {
 
   const client = reactInit(opts);
 
-  // Registered here rather than from `browserTracingIntegration` so route parameterization does not
-  // depend on tracing: the route manifests are injected at build time, so anything that needs a route
-  // name (bfcache metrics, web vitals) can resolve one even with tracing disabled.
-  setRouteProvider(createNextRouteProvider(), client);
-
   const filterNextRedirectError: EventProcessor = (event, hint) =>
     isRedirectNavigationError(hint?.originalException) || event.exception?.values?.[0]?.value === 'NEXT_REDIRECT'
       ? null
@@ -112,6 +106,7 @@ export function init(options: BrowserOptions): Client | undefined {
 
 function getDefaultIntegrations(options: BrowserOptions): Integration[] {
   const customDefaultIntegrations = getReactDefaultIntegrations(options);
+  customDefaultIntegrations.push(nextjsRouteProviderIntegration());
   // This evaluates to true unless __SENTRY_TRACING__ is text-replaced with "false",
   // in which case everything inside will get tree-shaken away
   if (typeof __SENTRY_TRACING__ === 'undefined' || __SENTRY_TRACING__) {

packages/nextjs/src/client/routing/routeProvider.ts

@@ -1,5 +1,6 @@
+import { defineIntegration } from '@sentry/core';
 import type { RouteProvider } from '@sentry/core/browser';
-import { createUrlRouteProvider } from '@sentry/core/browser';
+import { createUrlRouteProvider, setRouteProvider } from '@sentry/core/browser';
 import { maybeParameterizeRoute, stripBasePath, stripTrailingSlash } from './parameterization';
 import { getNextRouteFromPathname } from './pagesRouterRoutingInstrumentation';
 
@@ -24,3 +25,18 @@ function resolveNextRoute(url: URL): string | undefined {
 export function createNextRouteProvider(): RouteProvider {
   return createUrlRouteProvider(resolveNextRoute);
 }
+
+/**
+ * Registers the Next.js route provider.
+ *
+ * An integration rather than part of `browserTracingIntegration` so route parameterization does not depend
+ * on tracing: the route manifests are injected at build time, so anything that needs a route name (bfcache
+ * metrics, web vitals) can resolve one even with tracing disabled. Registered in `setup` because the pageload
+ * span is named in `browserTracingIntegration`'s `afterAllSetup`.
+ */
+export const nextjsRouteProviderIntegration = defineIntegration(() => ({
+  name: 'NextjsRouteProvider',
+  setup(client) {
+    setRouteProvider(createNextRouteProvider(), client);
+  },
+}));

packages/nextjs/test/client/appRouterRoutingInstrumentation.test.ts

@@ -11,11 +11,13 @@ import '@sentry/core';
 import '@sentry/react';
 import '../../src/client/routing/appRouterRoutingInstrumentation';
 import type * as AppRouterInstrumentation from '../../src/client/routing/appRouterRoutingInstrumentation';
+import type * as RouteProvider from '../../src/client/routing/routeProvider';
 import type { RouteManifest } from '../../src/config/manifest/types';
 
 type Core = typeof SentryCore;
 type React = typeof SentryReact;
 type Instrumentation = typeof AppRouterInstrumentation;
+type RouteProviderModule = typeof RouteProvider;
 
 interface NextRouter {
   back: () => void;
@@ -61,14 +63,18 @@ async function setup(traceLifecycle: 'stream' | 'static'): Promise<{
   const core: Core = await import('@sentry/core');
   const react: React = await import('@sentry/react');
   const instrumentation: Instrumentation = await import('../../src/client/routing/appRouterRoutingInstrumentation');
+  const routeProvider: RouteProviderModule = await import('../../src/client/routing/routeProvider');
 
   const client = new react.BrowserClient({
     dsn: 'http://examplePublicKey@localhost/0',
     transport: () => core.createTransport({ recordDroppedEvent: () => undefined }, () => core.resolvedSyncPromise({})),
     stackParser: () => [],
     tracesSampleRate: 1,
     traceLifecycle,
-    integrations: [react.browserTracingIntegration({ instrumentPageLoad: false, instrumentNavigation: false })],
+    integrations: [
+      routeProvider.nextjsRouteProviderIntegration(),
+      react.browserTracingIntegration({ instrumentPageLoad: false, instrumentNavigation: false }),
+    ],
   });
   core.setCurrentClient(client);
   client.init();

packages/nextjs/test/client/routeProvider.test.ts

@@ -4,7 +4,11 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { BrowserClient, setCurrentClient } from '@sentry/react';
 import { createNextRouteProvider } from '../../src/client/routing/routeProvider';
 
-const globalWithManifest = GLOBAL_OBJ as typeof GLOBAL_OBJ & { _sentryRouteManifest?: string };
+const globalWithManifest = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+  _sentryRouteManifest?: string;
+  _sentryBasePath?: string;
+  __BUILD_MANIFEST?: { sortedPages?: string[] };
+};
 
 let originalDocument: unknown;
 
@@ -43,6 +47,8 @@ describe('createNextRouteProvider', () => {
 
   afterEach(() => {
     delete globalWithManifest._sentryRouteManifest;
+    delete globalWithManifest._sentryBasePath;
+    delete globalWithManifest.__BUILD_MANIFEST;
     (GLOBAL_OBJ as { document?: unknown }).document = originalDocument;
   });
 
@@ -67,4 +73,26 @@ describe('createNextRouteProvider', () => {
 
     expect(resolveRoute('https://example.com/nope/deep', client)).toBeUndefined();
   });
+
+  describe('Pages Router', () => {
+    beforeEach(() => {
+      globalWithManifest.__BUILD_MANIFEST = { sortedPages: ['/', '/_app', '/_error', '/posts/[slug]'] };
+    });
+
+    it('falls back to the Pages Router manifest when the App Router manifest has no match', () => {
+      const client = makeClient();
+      setRouteProvider(createNextRouteProvider(), client);
+
+      expect(resolveRoute('https://example.com/posts/hello', client)).toBe('/posts/[slug]');
+    });
+
+    it('strips `basePath` before matching, since Pages Router routes are generated without it', () => {
+      globalWithManifest._sentryBasePath = '/docs';
+      const client = makeClient();
+      setRouteProvider(createNextRouteProvider(), client);
+
+      expect(resolveRoute('https://example.com/docs/posts/hello', client)).toBe('/posts/[slug]');
+      expect(resolveRoute('https://example.com/docs', client)).toBe('/');
+    });
+  });
 });

packages/nextjs/test/clientSdk.test.ts

@@ -1,5 +1,5 @@
 import type { Integration } from '@sentry/core';
-import { debug, getMainCarrier, SentryNonRecordingSpan } from '@sentry/core';
+import { debug, getMainCarrier, GLOBAL_OBJ, SentryNonRecordingSpan, spanToJSON } from '@sentry/core';
 import * as SentryReact from '@sentry/react';
 import { getClient, WINDOW } from '@sentry/react';
 import { JSDOM } from 'jsdom';
@@ -188,6 +188,28 @@ describe('Client init()', () => {
         delete globalThis.__SENTRY_TRACING__;
       });
 
+      it('names the pageload span after the parameterized route', () => {
+        const globalWithManifest = GLOBAL_OBJ as typeof GLOBAL_OBJ & { _sentryRouteManifest?: string };
+        globalWithManifest._sentryRouteManifest = JSON.stringify({
+          staticRoutes: [{ path: '/' }],
+          dynamicRoutes: [],
+          isrRoutes: [],
+        });
+
+        init({ dsn: TEST_DSN, tracesSampleRate: 1.0 });
+
+        expect(spanToJSON(SentryReact.getActiveSpan()!)).toMatchObject({
+          name: '/',
+          attributes: {
+            'sentry.op': 'pageload',
+            'sentry.segment.name.source': 'route',
+            'url.template': '/',
+          },
+        });
+
+        delete globalWithManifest._sentryRouteManifest;
+      });
+
       it("doesn't run Next.js router instrumentation for bot user agents", () => {
         Object.defineProperty(WINDOW, 'navigator', {
           value: {