feat(nextjs): Isolate nonce fetch in Suspense boundary for PPR support

.changeset/thin-flies-rush.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Isolate nonce fetch in Suspense boundary for improved PPR support

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -9,11 +9,11 @@ import React from 'react';
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
 import { ClerkNextOptionsProvider, useClerkNextOptions } from '../../client-boundary/NextOptionsContext';
 import type { NextClerkProviderProps } from '../../types';
-import { ClerkScripts } from '../../utils/clerk-script';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { RouterTelemetry } from '../../utils/router-telemetry';
 import { invalidateCacheAction } from '../server-actions';
+import { ClerkScripts } from './ClerkScripts';
 import { useAwaitablePush } from './useAwaitablePush';
 import { useAwaitableReplace } from './useAwaitableReplace';
 
@@ -26,7 +26,7 @@ const LazyCreateKeylessApplication = dynamic(() =>
 );
 
 const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderProps<TUi>) => {
-  const { __internal_invokeMiddlewareOnAuthStateChange = true, children } = props;
+  const { __internal_invokeMiddlewareOnAuthStateChange = true, __internal_scriptsSlot, children } = props;
   const router = useRouter();
   const push = useAwaitablePush();
   const replace = useAwaitableReplace();
@@ -89,7 +89,7 @@ const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderPr
     <ClerkNextOptionsProvider options={mergedProps}>
       <ReactClerkProvider {...mergedProps}>
         <RouterTelemetry />
-        <ClerkScripts router='app' />
+        {__internal_scriptsSlot ?? <ClerkScripts />}
         {children}
       </ReactClerkProvider>
     </ClerkNextOptionsProvider>

packages/nextjs/src/app-router/client/ClerkScripts.tsx

@@ -0,0 +1,27 @@
+import { useClerk } from '@clerk/react';
+import React from 'react';
+
+import { useClerkNextOptions } from '../../client-boundary/NextOptionsContext';
+import { ClerkScriptTags } from '../../utils/clerk-script-tags';
+
+export function ClerkScripts() {
+  const { publishableKey, clerkJSUrl, clerkJSVersion, clerkUIUrl, nonce, prefetchUI } = useClerkNextOptions();
+  const { domain, proxyUrl } = useClerk();
+
+  if (!publishableKey) {
+    return null;
+  }
+
+  return (
+    <ClerkScriptTags
+      publishableKey={publishableKey}
+      clerkJSUrl={clerkJSUrl}
+      clerkJSVersion={clerkJSVersion}
+      clerkUIUrl={clerkUIUrl}
+      nonce={nonce}
+      domain={domain}
+      proxyUrl={proxyUrl}
+      prefetchUI={prefetchUI}
+    />
+  );
+}

packages/nextjs/src/app-router/server/ClerkProvider.tsx

@@ -1,14 +1,14 @@
 import type { Ui } from '@clerk/react/internal';
 import type { InitialState, Without } from '@clerk/shared/types';
-import { headers } from 'next/headers';
-import React from 'react';
+import React, { Suspense } from 'react';
 
 import { getDynamicAuthData } from '../../server/buildClerkProps';
 import type { NextClerkProviderProps } from '../../types';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { ClientClerkProvider } from '../client/ClerkProvider';
+import { DynamicClerkScripts } from './DynamicClerkScripts';
 import { getKeylessStatus, KeylessProvider } from './keyless-provider';
-import { buildRequestLike, getScriptNonceFromHeader } from './utils';
+import { buildRequestLike } from './utils';
 
 const getDynamicClerkState = React.cache(async function getDynamicClerkState() {
   const request = await buildRequestLike();
@@ -17,43 +17,57 @@ const getDynamicClerkState = React.cache(async function getDynamicClerkState() {
   return data;
 });
 
-const getNonceHeaders = React.cache(async function getNonceHeaders() {
-  const headersList = await headers();
-  const nonce = headersList.get('X-Nonce');
-  return nonce
-    ? nonce
-    : // Fallback to extracting from CSP header
-      getScriptNonceFromHeader(headersList.get('Content-Security-Policy') || '') || '';
-});
-
 export async function ClerkProvider<TUi extends Ui = Ui>(
   props: Without<NextClerkProviderProps<TUi>, '__internal_invokeMiddlewareOnAuthStateChange'>,
 ) {
   const { children, dynamic, ...rest } = props;
 
   const statePromiseOrValue = dynamic ? getDynamicClerkState() : undefined;
-  const noncePromiseOrValue = dynamic ? getNonceHeaders() : '';
 
   const propsWithEnvs = mergeNextClerkPropsWithEnv({
     ...rest,
     // Even though we always cast to InitialState here, this might still be a promise.
     // While not reflected in the public types, we do support this for React >= 19 for internal use.
     initialState: statePromiseOrValue as InitialState | undefined,
-    nonce: await noncePromiseOrValue,
   });
 
   const { shouldRunAsKeyless, runningWithClaimedKeys } = await getKeylessStatus(propsWithEnvs);
 
+  // When dynamic mode is enabled, render scripts in a Suspense boundary to isolate
+  // the nonce fetching (which calls headers()) from the rest of the page.
+  // This allows the page to remain statically renderable / use PPR.
+  const scriptsSlot = dynamic ? (
+    <Suspense>
+      <DynamicClerkScripts
+        publishableKey={propsWithEnvs.publishableKey}
+        clerkJSUrl={propsWithEnvs.clerkJSUrl}
+        clerkJSVersion={propsWithEnvs.clerkJSVersion}
+        clerkUIUrl={propsWithEnvs.clerkUIUrl}
+        domain={propsWithEnvs.domain}
+        proxyUrl={propsWithEnvs.proxyUrl}
+        prefetchUI={propsWithEnvs.prefetchUI}
+      />
+    </Suspense>
+  ) : undefined;
+
   if (shouldRunAsKeyless) {
     return (
       <KeylessProvider
         rest={propsWithEnvs}
         runningWithClaimedKeys={runningWithClaimedKeys}
+        __internal_scriptsSlot={scriptsSlot}
       >
         {children}
       </KeylessProvider>
     );
   }
 
-  return <ClientClerkProvider {...propsWithEnvs}>{children}</ClientClerkProvider>;
+  return (
+    <ClientClerkProvider
+      {...propsWithEnvs}
+      __internal_scriptsSlot={scriptsSlot}
+    >
+      {children}
+    </ClientClerkProvider>
+  );
 }

packages/nextjs/src/app-router/server/DynamicClerkScripts.tsx

@@ -0,0 +1,60 @@
+import { headers } from 'next/headers';
+import React from 'react';
+
+import { ClerkScriptTags } from '../../utils/clerk-script-tags';
+import { getScriptNonceFromHeader, isPrerenderingBailout } from './utils';
+
+async function getNonce(): Promise<string> {
+  try {
+    const headersList = await headers();
+    const nonce = headersList.get('X-Nonce');
+    return nonce
+      ? nonce
+      : // Fallback to extracting from CSP header
+        getScriptNonceFromHeader(headersList.get('Content-Security-Policy') || '') || '';
+  } catch (e) {
+    if (isPrerenderingBailout(e)) {
+      throw e;
+    }
+    // Graceful degradation — scripts load without nonce
+    return '';
+  }
+}
+
+type DynamicClerkScriptsProps = {
+  publishableKey: string;
+  clerkJSUrl?: string;
+  clerkJSVersion?: string;
+  clerkUIUrl?: string;
+  domain?: string;
+  proxyUrl?: string;
+  prefetchUI?: boolean;
+};
+
+/**
+ * Server component that fetches nonce from headers and renders Clerk scripts.
+ * This component should be wrapped in a Suspense boundary to isolate the dynamic
+ * nonce fetching from the rest of the page, allowing static rendering/PPR to work.
+ */
+export async function DynamicClerkScripts(props: DynamicClerkScriptsProps) {
+  const { publishableKey, clerkJSUrl, clerkJSVersion, clerkUIUrl, domain, proxyUrl, prefetchUI } = props;
+
+  if (!publishableKey) {
+    return null;
+  }
+
+  const nonce = await getNonce();
+
+  return (
+    <ClerkScriptTags
+      publishableKey={publishableKey}
+      clerkJSUrl={clerkJSUrl}
+      clerkJSVersion={clerkJSVersion}
+      clerkUIUrl={clerkUIUrl}
+      nonce={nonce}
+      domain={domain}
+      proxyUrl={proxyUrl}
+      prefetchUI={prefetchUI}
+    />
+  );
+}

packages/nextjs/src/app-router/server/__tests__/DynamicClerkScripts.test.tsx

@@ -0,0 +1,89 @@
+import type React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { DynamicClerkScripts } from '../DynamicClerkScripts';
+
+vi.mock('next/headers', () => ({
+  headers: vi.fn(),
+}));
+
+import { headers } from 'next/headers';
+
+const mockHeaders = headers as unknown as ReturnType<typeof vi.fn>;
+
+const render = async (element: Promise<React.JSX.Element | null>) => {
+  const resolved = await element;
+  if (!resolved) {
+    return '';
+  }
+  return renderToStaticMarkup(resolved);
+};
+
+const defaultProps = {
+  publishableKey: 'pk_test_123',
+};
+
+describe('DynamicClerkScripts', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns null when publishableKey is empty', async () => {
+    const html = await render(DynamicClerkScripts({ publishableKey: '' }));
+    expect(html).toBe('');
+  });
+
+  it('uses X-Nonce header when present', async () => {
+    mockHeaders.mockResolvedValue(
+      new Map([
+        ['X-Nonce', 'test-nonce-123'],
+        ['Content-Security-Policy', ''],
+      ]),
+    );
+
+    const html = await render(DynamicClerkScripts(defaultProps));
+    expect(html).toContain('nonce="test-nonce-123"');
+  });
+
+  it('falls back to CSP header when X-Nonce is absent', async () => {
+    mockHeaders.mockResolvedValue(
+      new Map([
+        ['X-Nonce', null],
+        ['Content-Security-Policy', "script-src 'nonce-csp-nonce-456'"],
+      ]),
+    );
+
+    const html = await render(DynamicClerkScripts(defaultProps));
+    expect(html).toContain('nonce="csp-nonce-456"');
+  });
+
+  it('renders scripts without a nonce value when neither X-Nonce nor CSP header is present', async () => {
+    mockHeaders.mockResolvedValue(
+      new Map([
+        ['X-Nonce', null],
+        ['Content-Security-Policy', ''],
+      ]),
+    );
+
+    const html = await render(DynamicClerkScripts(defaultProps));
+    expect(html).toContain('data-clerk-js-script');
+    expect(html).not.toContain('nonce="test');
+    expect(html).not.toContain('nonce="csp');
+  });
+
+  it('rethrows prerendering bailout errors', async () => {
+    mockHeaders.mockRejectedValue(new Error('Dynamic server usage: headers'));
+
+    await expect(render(DynamicClerkScripts(defaultProps))).rejects.toThrow('Dynamic server usage: headers');
+  });
+
+  it('gracefully degrades when headers() throws a non-bailout error', async () => {
+    mockHeaders.mockRejectedValue(new Error('some unexpected error'));
+
+    const html = await render(DynamicClerkScripts(defaultProps));
+    expect(html).toContain('data-clerk-js-script');
+    expect(html).not.toContain('nonce="test');
+    expect(html).not.toContain('nonce="csp');
+  });
+});

packages/nextjs/src/app-router/server/keyless-provider.tsx

@@ -32,10 +32,11 @@ export async function getKeylessStatus(
 type KeylessProviderProps = PropsWithChildren<{
   rest: Without<NextClerkProviderProps, '__internal_invokeMiddlewareOnAuthStateChange' | 'children'>;
   runningWithClaimedKeys: boolean;
+  __internal_scriptsSlot?: React.ReactNode;
 }>;
 
 export const KeylessProvider = async (props: KeylessProviderProps) => {
-  const { rest, runningWithClaimedKeys, children } = props;
+  const { rest, runningWithClaimedKeys, __internal_scriptsSlot, children } = props;
 
   // NOTE: Create or read keys on every render. Usually this means only on hard refresh or hard navigations.
   const newOrReadKeys = await import('../../server/keyless-node.js')
@@ -52,6 +53,7 @@ export const KeylessProvider = async (props: KeylessProviderProps) => {
       <ClientClerkProvider
         {...mergeNextClerkPropsWithEnv(rest)}
         disableKeyless
+        __internal_scriptsSlot={__internal_scriptsSlot}
       >
         {children}
       </ClientClerkProvider>
@@ -68,6 +70,7 @@ export const KeylessProvider = async (props: KeylessProviderProps) => {
         // Explicitly use `null` instead of `undefined` here to avoid persisting `deleteKeylessAction` during merging of options.
         __internal_keyless_dismissPrompt: runningWithClaimedKeys ? deleteKeylessAction : null,
       })}
+      __internal_scriptsSlot={__internal_scriptsSlot}
     >
       {children}
     </ClientClerkProvider>

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -8,11 +8,11 @@ import React from 'react';
 import { useSafeLayoutEffect } from '../client-boundary/hooks/useSafeLayoutEffect';
 import { ClerkNextOptionsProvider } from '../client-boundary/NextOptionsContext';
 import type { NextClerkProviderProps } from '../types';
-import { ClerkScripts } from '../utils/clerk-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
 import { removeBasePath } from '../utils/removeBasePath';
 import { RouterTelemetry } from '../utils/router-telemetry';
+import { ClerkScripts } from './ClerkScripts';
 
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 setClerkJSLoadingErrorPackageName(PACKAGE_NAME);
@@ -56,7 +56,7 @@ export function ClerkProvider<TUi extends Ui = Ui>({ children, ...props }: NextC
         initialState={initialState}
       >
         <RouterTelemetry />
-        <ClerkScripts router='pages' />
+        <ClerkScripts />
         {children}
       </ReactClerkProvider>
     </ClerkNextOptionsProvider>