fix(nextjs): Use preload for shared UI variant to avoid race condition (#7685)

Author: bratsos

.changeset/light-drinks-grow.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Fix race condition that could cause `__clerkSharedModules is not defined` error when using the shared React UI variant.

integration/presets/envs.ts

@@ -55,6 +55,11 @@ const withEmailCodes_destroy_client = withEmailCodes
   .clone()
   .setEnvVariable('public', 'EXPERIMENTAL_PERSIST_CLIENT', 'false');
 
+const withSharedUIVariant = withEmailCodes
+  .clone()
+  .setId('withSharedUIVariant')
+  .setEnvVariable('public', 'CLERK_UI_VARIANT', 'shared');
+
 const withEmailLinks = base
   .clone()
   .setId('withEmailLinks')
@@ -210,6 +215,7 @@ export const envs = {
   withReverification,
   withSessionTasks,
   withSessionTasksResetPassword,
+  withSharedUIVariant,
   withSignInOrUpEmailLinksFlow,
   withSignInOrUpFlow,
   withSignInOrUpwithRestrictedModeFlow,

integration/presets/longRunningApps.ts

@@ -33,6 +33,7 @@ export const createLongRunningApps = () => {
     { id: 'next.appRouter.withSessionTasksResetPassword', config: next.appRouter, env: envs.withSessionTasksResetPassword },
     { id: 'next.appRouter.withLegalConsent', config: next.appRouter, env: envs.withLegalConsent },
     { id: 'next.appRouter.withNeedsClientTrust', config: next.appRouter, env: envs.withNeedsClientTrust },
+    { id: 'next.appRouter.withSharedUIVariant', config: next.appRouter, env: envs.withSharedUIVariant },
 
     /**
      * Quickstart apps

integration/tests/shared-ui-variant.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from '@playwright/test';
+
+import { appConfigs } from '../presets';
+import { createTestUtils, testAgainstRunningApps } from '../testUtils';
+
+testAgainstRunningApps({ withEnv: [appConfigs.envs.withSharedUIVariant] })(
+  'shared React variant @nextjs',
+  ({ app }) => {
+    test.describe.configure({ mode: 'parallel' });
+
+    test('loads without __clerkSharedModules error when using shared UI variant', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+      const errors: string[] = [];
+
+      page.on('console', msg => {
+        if (msg.type() === 'error') {
+          errors.push(msg.text());
+        }
+      });
+
+      page.on('pageerror', error => {
+        errors.push(error.message);
+      });
+
+      await page.route('**/ui.browser.js', async route => {
+        const url = route.request().url().replace('ui.browser.js', 'ui.shared.browser.js');
+        const response = await page.request.fetch(url);
+        await route.fulfill({ response });
+      });
+
+      await page.route('**/_next/static/**/*.js', async route => {
+        await new Promise(resolve => setTimeout(resolve, 300));
+        await route.continue();
+      });
+
+      await u.page.goToRelative('/clerk-status');
+
+      await expect(page.getByText('Status: ready')).toBeVisible({ timeout: 30_000 });
+      await u.po.clerk.toBeLoaded();
+
+      const sharedModulesError = errors.find(e => e.includes('__clerkSharedModules'));
+      expect(sharedModulesError).toBeUndefined();
+    });
+  },
+);

packages/nextjs/src/utils/clerk-script.tsx

@@ -67,6 +67,9 @@ export function ClerkScripts({ router }: { router: ClerkScriptProps['router'] })
     clerkUIVariant: clerkUIVariant ?? DEFAULT_CLERK_UI_VARIANT,
   };
 
+  const uiScriptUrl = clerkUiScriptUrl(opts);
+  const isSharedVariant = opts.clerkUIVariant === 'shared';
+
   return (
     <>
       <ClerkScript
@@ -75,12 +78,22 @@ export function ClerkScripts({ router }: { router: ClerkScriptProps['router'] })
         dataAttribute='data-clerk-js-script'
         router={router}
       />
-      <ClerkScript
-        scriptUrl={clerkUiScriptUrl(opts)}
-        attributes={buildClerkUiScriptAttributes(opts)}
-        dataAttribute='data-clerk-ui-script'
-        router={router}
-      />
+      {isSharedVariant ? (
+        <link
+          rel='preload'
+          href={uiScriptUrl}
+          as='script'
+          crossOrigin='anonymous'
+          nonce={nonce}
+        />
+      ) : (
+        <ClerkScript
+          scriptUrl={uiScriptUrl}
+          attributes={buildClerkUiScriptAttributes(opts)}
+          dataAttribute='data-clerk-ui-script'
+          router={router}
+        />
+      )}
     </>
   );
 }

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -11,6 +11,7 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
     clerkJSUrl: props.clerkJSUrl || process.env.NEXT_PUBLIC_CLERK_JS_URL,
     clerkUiUrl: (props as any).clerkUiUrl || process.env.NEXT_PUBLIC_CLERK_UI_URL,
     clerkJSVersion: props.clerkJSVersion || process.env.NEXT_PUBLIC_CLERK_JS_VERSION,
+    clerkUIVariant: (props as any).clerkUIVariant || process.env.NEXT_PUBLIC_CLERK_UI_VARIANT,
     proxyUrl: props.proxyUrl || process.env.NEXT_PUBLIC_CLERK_PROXY_URL || '',
     domain: props.domain || process.env.NEXT_PUBLIC_CLERK_DOMAIN || '',
     isSatellite: props.isSatellite || isTruthy(process.env.NEXT_PUBLIC_CLERK_IS_SATELLITE),