fix(nextjs): replace __internal_skipScripts with scriptsSlot composition pattern

Replace the boolean `__internal_skipScripts` prop with a `__internal_scriptsSlot`
React node prop. The server provider now passes dynamic scripts as a slot prop
instead of rendering them as sibling children, preventing duplicate script
rendering in nested `<ClerkProvider dynamic>` scenarios.

Author: jacekradko

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

@@ -32,7 +32,7 @@ const LazyCreateKeylessApplication = dynamic(() =>
 );
 
 const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderProps<TUi>) => {
-  const { __internal_invokeMiddlewareOnAuthStateChange = true, __internal_skipScripts = false, children } = props;
+  const { __internal_invokeMiddlewareOnAuthStateChange = true, __internal_scriptsSlot, children } = props;
   const router = useRouter();
   const push = useAwaitablePush();
   const replace = useAwaitableReplace();
@@ -109,7 +109,7 @@ const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderPr
     <ClerkNextOptionsProvider options={mergedProps}>
       <ReactClerkProvider {...mergedProps}>
         <RouterTelemetry />
-        {!__internal_skipScripts && <ClerkScripts />}
+        {__internal_scriptsSlot ?? <ClerkScripts />}
         {children}
       </ReactClerkProvider>
     </ClerkNextOptionsProvider>

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

@@ -36,7 +36,7 @@ export async function ClerkProvider<TUi extends Ui = Ui>(
   // 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 ? (
+  const scriptsSlot = dynamic ? (
     <Suspense>
       <DynamicClerkScripts
         publishableKey={propsWithEnvs.publishableKey}
@@ -48,16 +48,15 @@ export async function ClerkProvider<TUi extends Ui = Ui>(
         prefetchUI={propsWithEnvs.prefetchUI}
       />
     </Suspense>
-  ) : null;
+  ) : undefined;
 
   if (shouldRunAsKeyless) {
     return (
       <KeylessProvider
         rest={propsWithEnvs}
         runningWithClaimedKeys={runningWithClaimedKeys}
-        __internal_skipScripts={dynamic}
+        __internal_scriptsSlot={scriptsSlot}
       >
-        {dynamicScripts}
         {children}
       </KeylessProvider>
     );
@@ -66,9 +65,8 @@ export async function ClerkProvider<TUi extends Ui = Ui>(
   return (
     <ClientClerkProvider
       {...propsWithEnvs}
-      __internal_skipScripts={dynamic}
+      __internal_scriptsSlot={scriptsSlot}
     >
-      {dynamicScripts}
       {children}
     </ClientClerkProvider>
   );

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

@@ -32,11 +32,11 @@ export async function getKeylessStatus(
 type KeylessProviderProps = PropsWithChildren<{
   rest: Without<NextClerkProviderProps, '__internal_invokeMiddlewareOnAuthStateChange' | 'children'>;
   runningWithClaimedKeys: boolean;
-  __internal_skipScripts?: boolean;
+  __internal_scriptsSlot?: React.ReactNode;
 }>;
 
 export const KeylessProvider = async (props: KeylessProviderProps) => {
-  const { rest, runningWithClaimedKeys, __internal_skipScripts, 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')
@@ -53,7 +53,7 @@ export const KeylessProvider = async (props: KeylessProviderProps) => {
       <ClientClerkProvider
         {...mergeNextClerkPropsWithEnv(rest)}
         disableKeyless
-        __internal_skipScripts={__internal_skipScripts}
+        __internal_scriptsSlot={__internal_scriptsSlot}
       >
         {children}
       </ClientClerkProvider>
@@ -70,7 +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}
+      __internal_scriptsSlot={__internal_scriptsSlot}
     >
       {children}
     </ClientClerkProvider>

packages/nextjs/src/types.ts

@@ -1,6 +1,7 @@
 import type { ClerkProviderProps } from '@clerk/react';
 import type { Ui } from '@clerk/react/internal';
 import type { Without } from '@clerk/shared/types';
+import type React from 'react';
 
 export type NextClerkProviderProps<TUi extends Ui = Ui> = Without<ClerkProviderProps<TUi>, 'publishableKey'> & {
   /**
@@ -25,8 +26,8 @@ export type NextClerkProviderProps<TUi extends Ui = Ui> = Without<ClerkProviderP
   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.
+   * When provided, the client ClerkProvider will render this slot instead of the default ClerkScripts.
+   * Used by the server provider to pass scripts rendered in a Suspense boundary.
    */
-  __internal_skipScripts?: boolean;
+  __internal_scriptsSlot?: React.ReactNode;
 };