feat(nextjs): Only wait for the trace meta tag when cacheComponents is on

The wait exists for a document that resumes a prerendered shell, whose tag
arrives with the resumed part. Without `cacheComponents` a tag is either in
`<head>` from the start or never comes, so waiting only held the pageload
back: fetches before the tag were not attached and the span ended earlier.
The build now injects `_sentryCacheComponents`, and the client only waits
when it is set.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: chargome

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

@@ -1,5 +1,6 @@
 import type { Span } from '@sentry/core';
 import { extractTraceparentData } from '@sentry/core';
+import { GLOBAL_OBJ } from '@sentry/core';
 import { WINDOW } from '@sentry/react';
 
 // `@opentelemetry/api` `TraceFlags`, inlined because core does not export its copies.
@@ -15,6 +16,13 @@ function getDocument(): Document | undefined {
   return WINDOW.document;
 }
 
+const globalWithInjectedValues = GLOBAL_OBJ as typeof GLOBAL_OBJ & { _sentryCacheComponents?: string };
+
+/** Whether the build enabled `cacheComponents`, so a document can resume a prerendered shell. */
+function hasCacheComponents(): boolean {
+  return (process.env._sentryCacheComponents ?? globalWithInjectedValues._sentryCacheComponents) === 'true';
+}
+
 function lastMetaContent(document: Document, name: string): string | undefined {
   const tags = document.querySelectorAll(`meta[name="${name}"]`);
   return tags[tags.length - 1]?.getAttribute('content') || undefined;
@@ -44,12 +52,18 @@ export function hasServerTimingTraceContext(): boolean {
 }
 
 /**
- * Whether the SDK can still expect a `sentry-trace` meta tag to arrive: the document is streaming
- * and nothing else already carries the trace.
+ * Whether the SDK can still expect a `sentry-trace` meta tag to arrive: the app has `cacheComponents`
+ * enabled, so a document can resume a prerendered shell and get its tag with the resumed part, the
+ * document is still streaming, and nothing else already carries the trace. Without `cacheComponents`
+ * a tag is either in `<head>` from the start or never comes, so waiting would only hold the pageload
+ * back.
  */
 export function canWaitForTraceMetaTag(): boolean {
   return (
-    getDocument()?.readyState === 'loading' && typeof MutationObserver !== 'undefined' && !hasServerTimingTraceContext()
+    hasCacheComponents() &&
+    getDocument()?.readyState === 'loading' &&
+    typeof MutationObserver !== 'undefined' &&
+    !hasServerTimingTraceContext()
   );
 }
 

packages/nextjs/src/config/withSentryConfig/buildTime.ts

@@ -69,6 +69,11 @@ export function setUpBuildTimeVariables(
     buildTimeVariables._sentryRelease = releaseName;
   }
 
+  // The client only waits for a late trace meta tag when a document can resume a prerendered shell.
+  if (userNextConfig.cacheComponents) {
+    buildTimeVariables._sentryCacheComponents = 'true';
+  }
+
   // See `client/routing/nextRoutingInstrumentation.ts`.
   if (hasOnlyAppRouterPages(projectDir)) {
     buildTimeVariables._sentryHasPagesRouter = 'false';

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

@@ -275,6 +275,7 @@ describe('appRouterInstrumentPageLoad', () => {
     window.history.replaceState({}, '', '/navigation?from=document');
     Object.defineProperty(document, 'readyState', { value: 'loading', configurable: true });
     vi.spyOn(performance, 'getEntriesByType').mockReturnValue([]);
+    vi.stubEnv('_sentryCacheComponents', 'true');
   });
 
   afterEach(() => {
@@ -286,6 +287,7 @@ describe('appRouterInstrumentPageLoad', () => {
       Object.defineProperty(Document.prototype, 'readyState', originalReadyState);
     }
     vi.restoreAllMocks();
+    vi.unstubAllEnvs();
   });
 
   it('records the URL of the document when the pageload starts after a navigation changed it', async () => {

packages/nextjs/test/client/traceMetaTags.test.ts

@@ -28,6 +28,7 @@ function setReadyState(value: DocumentReadyState): void {
 beforeEach(() => {
   document.head.innerHTML = '';
   document.body.innerHTML = '';
+  vi.stubEnv('_sentryCacheComponents', 'true');
 });
 
 afterEach(() => {
@@ -37,6 +38,7 @@ afterEach(() => {
     Object.defineProperty(Document.prototype, 'readyState', originalReadyState);
   }
   vi.restoreAllMocks();
+  vi.unstubAllEnvs();
   vi.useRealTimers();
 });
 
@@ -77,6 +79,14 @@ describe('canWaitForTraceMetaTag', () => {
     expect(canWaitForTraceMetaTag()).toBe(true);
   });
 
+  it('is false when the build did not enable cacheComponents', () => {
+    vi.stubEnv('_sentryCacheComponents', '');
+    setReadyState('loading');
+    vi.spyOn(performance, 'getEntriesByType').mockReturnValue([]);
+
+    expect(canWaitForTraceMetaTag()).toBe(false);
+  });
+
   it('is false once the document finished parsing', () => {
     setReadyState('interactive');
 

packages/nextjs/test/config/withSentryConfig/buildTime.test.ts

@@ -58,3 +58,17 @@ describe('setUpBuildTimeVariables', () => {
     });
   });
 });
+
+describe('_sentryCacheComponents', () => {
+  it('is set when the Next.js config enables cacheComponents', () => {
+    const config: NextConfigObject = { cacheComponents: true };
+    setUpBuildTimeVariables(config, {}, undefined);
+    expect(config.env?._sentryCacheComponents).toBe('true');
+  });
+
+  it('is left unset otherwise', () => {
+    const config: NextConfigObject = {};
+    setUpBuildTimeVariables(config, {}, undefined);
+    expect(config.env?._sentryCacheComponents).toBeUndefined();
+  });
+});