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

Move nonce fetching from the server ClerkProvider's main body into a
separate DynamicClerkScripts server component wrapped in Suspense.
This allows pages using dynamic=true to remain statically renderable
and compatible with PPR/cacheComponents.

- Create DynamicClerkScripts async server component
- Add getNonce cached function to utils
- Skip client ClerkScripts when server scripts are used
- Pass __internal_skipScripts through KeylessProvider

Author: jacekradko

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

@@ -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_skipScripts = false, 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_skipScripts && <ClerkScripts router='app' />}
         {children}
       </ReactClerkProvider>
     </ClerkNextOptionsProvider>

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,59 @@ 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 dynamicScripts = 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>
+  ) : null;
+
   if (shouldRunAsKeyless) {
     return (
       <KeylessProvider
         rest={propsWithEnvs}
         runningWithClaimedKeys={runningWithClaimedKeys}
+        __internal_skipScripts={dynamic}
       >
+        {dynamicScripts}
         {children}
       </KeylessProvider>
     );
   }
 
-  return <ClientClerkProvider {...propsWithEnvs}>{children}</ClientClerkProvider>;
+  return (
+    <ClientClerkProvider
+      {...propsWithEnvs}
+      __internal_skipScripts={dynamic}
+    >
+      {dynamicScripts}
+      {children}
+    </ClientClerkProvider>
+  );
 }

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

@@ -0,0 +1,69 @@
+import { buildClerkJSScriptAttributes, clerkJSScriptUrl, clerkUIScriptUrl } from '@clerk/react/internal';
+import React from 'react';
+
+import { getNonce } from './utils';
+
+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();
+
+  const opts = {
+    publishableKey,
+    clerkJSUrl,
+    clerkJSVersion,
+    clerkUIUrl,
+    nonce,
+    domain,
+    proxyUrl,
+  };
+
+  const scriptUrl = clerkJSScriptUrl(opts);
+  const attributes = buildClerkJSScriptAttributes(opts);
+
+  return (
+    <>
+      <script
+        src={scriptUrl}
+        data-clerk-js-script
+        async
+        crossOrigin='anonymous'
+        {...attributes}
+      />
+      {/* Use <link rel='preload'> instead of <script> for the UI bundle.
+          This tells the browser to download the resource immediately (high priority)
+          but doesn't execute it, avoiding race conditions with __clerkSharedModules
+          registration (which happens when React code runs @clerk/ui/register).
+          When loadClerkUIScript() later adds a <script> tag, the browser uses the
+          cached resource and executes it without re-downloading. */}
+      {prefetchUI !== false && (
+        <link
+          rel='preload'
+          href={clerkUIScriptUrl(opts)}
+          as='script'
+          crossOrigin='anonymous'
+          nonce={nonce}
+        />
+      )}
+    </>
+  );
+}

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_skipScripts?: boolean;
 }>;
 
 export const KeylessProvider = async (props: KeylessProviderProps) => {
-  const { rest, runningWithClaimedKeys, children } = props;
+  const { rest, runningWithClaimedKeys, __internal_skipScripts, 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_skipScripts={__internal_skipScripts}
       >
         {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_skipScripts={__internal_skipScripts}
     >
       {children}
     </ClientClerkProvider>

packages/nextjs/src/app-router/server/utils.ts

@@ -1,4 +1,5 @@
 import { NextRequest } from 'next/server';
+import React from 'react';
 
 export const isPrerenderingBailout = (e: unknown) => {
   if (!(e instanceof Error) || !('message' in e)) {
@@ -83,3 +84,19 @@ export function getScriptNonceFromHeader(cspHeaderValue: string): string | undef
 
   return nonce;
 }
+
+/**
+ * Fetches the nonce from request headers.
+ * Uses React.cache to deduplicate calls within the same request.
+ */
+export const getNonce = React.cache(async function getNonce(): Promise<string> {
+  // Dynamically import next/headers
+  // @ts-expect-error: Cannot find module 'next/headers' or its corresponding type declarations.ts(2307)
+  const { headers } = await import('next/headers');
+  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') || '') || '';
+});

packages/nextjs/src/types.ts

@@ -23,4 +23,10 @@ export type NextClerkProviderProps<TUi extends Ui = Ui> = Without<ClerkProviderP
    * @default false
    */
   dynamic?: boolean;
+  /**
+   * @internal
+   * If set to true, the client ClerkProvider will not render ClerkScripts.
+   * Used when scripts are rendered server-side in a Suspense boundary.
+   */
+  __internal_skipScripts?: boolean;
 };