From ed92695253a356234d24f5e428790f108924d5ef Mon Sep 17 00:00:00 2001
From: Jacek <jacek@clerk.dev>
Date: Wed, 28 May 2025 21:14:17 -0500
Subject: [PATCH 1/4] feat: failure detection

---
 .../src/__tests__/loadClerkJsScript.test.ts   | 132 ++++++++++++++----
 packages/shared/src/loadClerkJsScript.ts      |  78 +++++++++--
 2 files changed, 165 insertions(+), 45 deletions(-)

diff --git a/packages/shared/src/__tests__/loadClerkJsScript.test.ts b/packages/shared/src/__tests__/loadClerkJsScript.test.ts
index 2e259e10292..ee365188b8a 100644
--- a/packages/shared/src/__tests__/loadClerkJsScript.test.ts
+++ b/packages/shared/src/__tests__/loadClerkJsScript.test.ts
@@ -4,11 +4,8 @@ import {
   loadClerkJsScript,
   setClerkJsLoadingErrorPackageName,
 } from '../loadClerkJsScript';
-import { loadScript } from '../loadScript';
 import { getMajorVersion } from '../versionSelector';
 
-jest.mock('../loadScript');
-
 setClerkJsLoadingErrorPackageName('@clerk/clerk-react');
 const jsPackageMajorVersion = getMajorVersion(JS_PACKAGE_VERSION);
 
@@ -17,8 +14,12 @@ describe('loadClerkJsScript(options)', () => {
 
   beforeEach(() => {
     jest.clearAllMocks();
-    (loadScript as jest.Mock).mockResolvedValue(undefined);
     document.querySelector = jest.fn().mockReturnValue(null);
+    // Mock document.body for script creation
+    Object.defineProperty(document, 'body', {
+      value: document.createElement('body'),
+      writable: true,
+    });
   });
 
   test('throws error when publishableKey is missing', async () => {
@@ -28,48 +29,111 @@ describe('loadClerkJsScript(options)', () => {
   });
 
   test('loads script when no existing script is found', async () => {
-    await loadClerkJsScript({ publishableKey: mockPublishableKey });
-
-    expect(loadScript).toHaveBeenCalledWith(
-      expect.stringContaining(
-        `https://foo-bar-13.clerk.accounts.dev/npm/@clerk/clerk-js@${jsPackageMajorVersion}/dist/clerk.browser.js`,
-      ),
-      expect.objectContaining({
-        async: true,
-        crossOrigin: 'anonymous',
-        beforeLoad: expect.any(Function),
-      }),
+    const loadPromise = loadClerkJsScript({ publishableKey: mockPublishableKey });
+
+    // Find the script that was added to the DOM
+    const addedScript = document.body.querySelector('script[data-clerk-js-script]') as HTMLScriptElement;
+    expect(addedScript).toBeTruthy();
+    expect(addedScript.src).toContain(
+      `https://foo-bar-13.clerk.accounts.dev/npm/@clerk/clerk-js@${jsPackageMajorVersion}/dist/clerk.browser.js`,
     );
+    expect(addedScript.async).toBe(true);
+    expect(addedScript.getAttribute('crossorigin')).toBe('anonymous');
+
+    // Simulate successful load
+    addedScript.dispatchEvent(new Event('load'));
+
+    const result = await loadPromise;
+    expect(result).toBe(addedScript);
+    expect(addedScript.getAttribute('data-clerk-loaded')).toBe('true');
+  });
+
+  test('resolves immediately when script is already loaded', async () => {
+    const mockExistingScript = document.createElement('script');
+    mockExistingScript.setAttribute('data-clerk-loaded', 'true');
+    document.querySelector = jest.fn().mockReturnValue(mockExistingScript);
+
+    const result = await loadClerkJsScript({ publishableKey: mockPublishableKey });
+
+    expect(result).toBe(mockExistingScript);
+    // Should not create a new script
+    expect(document.body.querySelector('script[data-clerk-js-script]')).toBeNull();
   });
 
-  test('uses existing script when found', async () => {
+  test('waits for existing loading script to complete', async () => {
     const mockExistingScript = document.createElement('script');
+    // Script exists but is not marked as loaded yet
     document.querySelector = jest.fn().mockReturnValue(mockExistingScript);
 
     const loadPromise = loadClerkJsScript({ publishableKey: mockPublishableKey });
-    mockExistingScript.dispatchEvent(new Event('load'));
 
-    await expect(loadPromise).resolves.toBe(mockExistingScript);
-    expect(loadScript).not.toHaveBeenCalled();
+    // Simulate the existing script finishing loading
+    setTimeout(() => {
+      mockExistingScript.dispatchEvent(new Event('load'));
+    }, 10);
+
+    const result = await loadPromise;
+    expect(result).toBe(mockExistingScript);
+    expect(mockExistingScript.getAttribute('data-clerk-loaded')).toBe('true');
   });
 
-  test('rejects when existing script fails to load', async () => {
+  test('removes failed script and rejects when existing script fails to load', async () => {
     const mockExistingScript = document.createElement('script');
     document.querySelector = jest.fn().mockReturnValue(mockExistingScript);
+    const removeSpy = jest.spyOn(mockExistingScript, 'remove');
 
     const loadPromise = loadClerkJsScript({ publishableKey: mockPublishableKey });
     mockExistingScript.dispatchEvent(new Event('error'));
 
-    await expect(loadPromise).rejects.toBe('Clerk: Failed to load Clerk');
-    expect(loadScript).not.toHaveBeenCalled();
+    await expect(loadPromise).rejects.toThrow('Clerk: Failed to load Clerk');
+    expect(removeSpy).toHaveBeenCalled();
   });
 
-  test('throws error when loadScript fails', async () => {
-    (loadScript as jest.Mock).mockRejectedValue(new Error('Script load failed'));
+  test('handles race condition when script loads while setting up listeners', async () => {
+    const mockExistingScript = document.createElement('script');
+    document.querySelector = jest.fn().mockReturnValue(mockExistingScript);
 
-    await expect(loadClerkJsScript({ publishableKey: mockPublishableKey })).rejects.toThrow(
-      'Clerk: Failed to load Clerk',
-    );
+    // Simulate script loading between the initial check and listener setup
+    setTimeout(() => {
+      mockExistingScript.setAttribute('data-clerk-loaded', 'true');
+    }, 1);
+
+    const result = await loadClerkJsScript({ publishableKey: mockPublishableKey });
+    expect(result).toBe(mockExistingScript);
+  });
+
+  test('creates script with correct attributes', async () => {
+    const options = {
+      publishableKey: mockPublishableKey,
+      proxyUrl: 'https://proxy.clerk.com',
+      domain: 'custom.com',
+      nonce: 'test-nonce',
+    };
+
+    const loadPromise = loadClerkJsScript(options);
+
+    const addedScript = document.body.querySelector('script[data-clerk-js-script]') as HTMLScriptElement;
+    expect(addedScript.getAttribute('data-clerk-publishable-key')).toBe(mockPublishableKey);
+    expect(addedScript.getAttribute('data-clerk-proxy-url')).toBe('https://proxy.clerk.com');
+    expect(addedScript.getAttribute('data-clerk-domain')).toBe('custom.com');
+    expect(addedScript.nonce).toBe('test-nonce');
+
+    // Complete the load
+    addedScript.dispatchEvent(new Event('load'));
+    await loadPromise;
+  });
+
+  test('rejects and removes script when new script fails to load', async () => {
+    const loadPromise = loadClerkJsScript({ publishableKey: mockPublishableKey });
+
+    const addedScript = document.body.querySelector('script[data-clerk-js-script]') as HTMLScriptElement;
+    const removeSpy = jest.spyOn(addedScript, 'remove');
+
+    // Simulate script load failure
+    addedScript.dispatchEvent(new Event('error'));
+
+    await expect(loadPromise).rejects.toThrow('Clerk: Failed to load Clerk');
+    expect(removeSpy).toHaveBeenCalled();
   });
 });
 
@@ -120,6 +184,7 @@ describe('buildClerkJsScriptAttributes()', () => {
       'all options',
       { publishableKey: mockPublishableKey, proxyUrl: mockProxyUrl, domain: mockDomain },
       {
+        'data-clerk-js-script': '',
         'data-clerk-publishable-key': mockPublishableKey,
         'data-clerk-proxy-url': mockProxyUrl,
         'data-clerk-domain': mockDomain,
@@ -128,14 +193,21 @@ describe('buildClerkJsScriptAttributes()', () => {
     [
       'only publishableKey',
       { publishableKey: mockPublishableKey },
-      { 'data-clerk-publishable-key': mockPublishableKey },
+      {
+        'data-clerk-js-script': '',
+        'data-clerk-publishable-key': mockPublishableKey,
+      },
     ],
     [
       'publishableKey and proxyUrl',
       { publishableKey: mockPublishableKey, proxyUrl: mockProxyUrl },
-      { 'data-clerk-publishable-key': mockPublishableKey, 'data-clerk-proxy-url': mockProxyUrl },
+      {
+        'data-clerk-js-script': '',
+        'data-clerk-publishable-key': mockPublishableKey,
+        'data-clerk-proxy-url': mockProxyUrl,
+      },
     ],
-    ['no options', {}, {}],
+    ['no options', {}, { 'data-clerk-js-script': '' }],
   ])('returns correct attributes with %s', (_, input, expected) => {
     // @ts-ignore input loses correct type because of empty object
     expect(buildClerkJsScriptAttributes(input)).toEqual(expected);
diff --git a/packages/shared/src/loadClerkJsScript.ts b/packages/shared/src/loadClerkJsScript.ts
index 97647e3f0bd..ee3df44f089 100644
--- a/packages/shared/src/loadClerkJsScript.ts
+++ b/packages/shared/src/loadClerkJsScript.ts
@@ -2,7 +2,6 @@ import type { ClerkOptions, SDKMetadata, Without } from '@clerk/types';
 
 import { buildErrorThrower } from './error';
 import { createDevOrStagingUrlCache, parsePublishableKey } from './keys';
-import { loadScript } from './loadScript';
 import { isValidProxyUrl, proxyUrlToAbsoluteURL } from './proxy';
 import { addClerkPrefix } from './url';
 import { versionSelector } from './versionSelector';
@@ -37,9 +36,11 @@ type LoadClerkJsScriptOptions = Without<ClerkOptions, 'isSatellite'> & {
 /**
  * Hotloads the Clerk JS script.
  *
- * Checks for an existing Clerk JS script. If found, it returns a promise
- * that resolves when the script loads. If not found, it uses the provided options to
- * build the Clerk JS script URL and load the script.
+ * Checks for an existing Clerk JS script and handles various loading states:
+ * - If script already loaded successfully: resolves immediately
+ * - If script is currently loading: waits for completion
+ * - If script failed to load: attempts to load again
+ * - If no script exists: loads the script.
  *
  * @param opts - The options used to build the Clerk JS script URL and load the script.
  *               Must include a `publishableKey` if no existing script is found.
@@ -51,14 +52,35 @@ const loadClerkJsScript = async (opts?: LoadClerkJsScriptOptions) => {
   const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
 
   if (existingScript) {
+    if (existingScript.getAttribute('data-clerk-loaded') === 'true') {
+      return Promise.resolve(existingScript);
+    }
+
     return new Promise((resolve, reject) => {
-      existingScript.addEventListener('load', () => {
+      const handleLoad = () => {
+        cleanup();
+        existingScript.setAttribute('data-clerk-loaded', 'true');
         resolve(existingScript);
-      });
+      };
+
+      const handleError = () => {
+        cleanup();
+        existingScript.remove();
+        reject(new Error(FAILED_TO_LOAD_ERROR));
+      };
+
+      const cleanup = () => {
+        existingScript.removeEventListener('load', handleLoad);
+        existingScript.removeEventListener('error', handleError);
+      };
+
+      existingScript.addEventListener('load', handleLoad);
+      existingScript.addEventListener('error', handleError);
 
-      existingScript.addEventListener('error', () => {
-        reject(FAILED_TO_LOAD_ERROR);
-      });
+      if (existingScript.getAttribute('data-clerk-loaded') === 'true') {
+        cleanup();
+        resolve(existingScript);
+      }
     });
   }
 
@@ -67,11 +89,36 @@ const loadClerkJsScript = async (opts?: LoadClerkJsScriptOptions) => {
     return;
   }
 
-  return loadScript(clerkJsScriptUrl(opts), {
-    async: true,
-    crossOrigin: 'anonymous',
-    nonce: opts.nonce,
-    beforeLoad: applyClerkJsScriptAttributes(opts),
+  return new Promise<HTMLScriptElement>((resolve, reject) => {
+    if (!document || !document.body) {
+      reject(new Error('loadClerkJsScript cannot be called when document does not exist'));
+      return;
+    }
+
+    const script = document.createElement('script');
+    script.async = true;
+    script.setAttribute('crossorigin', 'anonymous');
+    if (opts.nonce) {
+      script.nonce = opts.nonce;
+    }
+
+    const handleLoad = () => {
+      script.setAttribute('data-clerk-loaded', 'true');
+      resolve(script);
+    };
+
+    const handleError = () => {
+      script.remove();
+      reject(new Error(FAILED_TO_LOAD_ERROR));
+    };
+
+    script.addEventListener('load', handleLoad);
+    script.addEventListener('error', handleError);
+
+    applyClerkJsScriptAttributes(opts)(script);
+
+    script.src = clerkJsScriptUrl(opts);
+    document.body.appendChild(script);
   }).catch(() => {
     throw new Error(FAILED_TO_LOAD_ERROR);
   });
@@ -81,7 +128,6 @@ const loadClerkJsScript = async (opts?: LoadClerkJsScriptOptions) => {
  * Generates a Clerk JS script URL.
  *
  * @param opts - The options to use when building the Clerk JS script URL.
- *
  * @example
  * clerkJsScriptUrl({ publishableKey: 'pk_' });
  */
@@ -112,6 +158,8 @@ const clerkJsScriptUrl = (opts: LoadClerkJsScriptOptions) => {
 const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
   const obj: Record<string, string> = {};
 
+  obj['data-clerk-js-script'] = '';
+
   if (options.publishableKey) {
     obj['data-clerk-publishable-key'] = options.publishableKey;
   }

From 939985a902175de2471e802abc011b0b45eaa091 Mon Sep 17 00:00:00 2001
From: Jacek <jacek@clerk.dev>
Date: Thu, 29 May 2025 11:20:48 -0500
Subject: [PATCH 2/4] render blocking coordinator

---
 packages/nextjs/src/utils/clerk-js-script.tsx | 247 ++++++++++++++++--
 .../shared/src/clerkJsBlockingCoordinator.ts  | 246 +++++++++++++++++
 packages/shared/src/index.ts                  |   1 +
 packages/shared/src/loadClerkJsScript.ts      | 133 ++++------
 4 files changed, 527 insertions(+), 100 deletions(-)
 create mode 100644 packages/shared/src/clerkJsBlockingCoordinator.ts

diff --git a/packages/nextjs/src/utils/clerk-js-script.tsx b/packages/nextjs/src/utils/clerk-js-script.tsx
index cc39f3534e6..1d56724c416 100644
--- a/packages/nextjs/src/utils/clerk-js-script.tsx
+++ b/packages/nextjs/src/utils/clerk-js-script.tsx
@@ -1,20 +1,167 @@
 import { useClerk } from '@clerk/clerk-react';
 import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
 import NextScript from 'next/script';
-import React from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 
 import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
 
+// TODO: This will work once the exports are properly set up
+// For now, we'll use the blocking coordinator pattern with inline script
+
+type LoadingState = 'idle' | 'loading' | 'loaded' | 'error';
+
 type ClerkJSScriptProps = {
   router: 'app' | 'pages';
+  onLoad?: () => void;
+  onError?: (error: Error) => void;
+  onLoadingStateChange?: (state: LoadingState) => void;
 };
 
+// Inline blocking coordinator script (until we can import properly)
+function getBlockingCoordinatorScript(): string {
+  return `
+(function() {
+  'use strict';
+  
+  if (window.__clerkJSBlockingCoordinator) {
+    return;
+  }
+  
+  var coordinator = {
+    state: 'idle',
+    scriptUrl: null,
+    scriptElement: null,
+    error: null,
+    callbacks: [],
+    
+    shouldAllowScript: function(scriptElement) {
+      if (!scriptElement.hasAttribute('data-clerk-js-script')) {
+        return true;
+      }
+      
+      if (this.scriptElement && this.scriptElement.src === scriptElement.src) {
+        return false;
+      }
+      
+      if (window.Clerk) {
+        this.setState('loaded');
+        return false;
+      }
+      
+      if (this.state === 'loading') {
+        return false;
+      }
+      
+      this.adoptScript(scriptElement);
+      return true;
+    },
+    
+    adoptScript: function(scriptElement) {
+      this.scriptElement = scriptElement;
+      this.scriptUrl = scriptElement.src;
+      this.setState('loading');
+      
+      var self = this;
+      
+      scriptElement.addEventListener('load', function() {
+        scriptElement.setAttribute('data-clerk-loaded', 'true');
+        self.setState('loaded');
+      });
+      
+      scriptElement.addEventListener('error', function() {
+        self.setState('error', new Error('ClerkJS failed to load'));
+      });
+    },
+    
+    registerCallback: function(callback) {
+      this.callbacks.push(callback);
+      
+      if (callback.onStateChange) {
+        callback.onStateChange(this.state);
+      }
+      
+      if (this.state === 'loaded' && callback.onLoad) {
+        callback.onLoad();
+      } else if (this.state === 'error' && callback.onError && this.error) {
+        callback.onError(this.error);
+      }
+    },
+    
+    setState: function(newState, error) {
+      this.state = newState;
+      if (error) this.error = error;
+      
+      for (var i = 0; i < this.callbacks.length; i++) {
+        var callback = this.callbacks[i];
+        try {
+          if (callback.onStateChange) {
+            callback.onStateChange(newState);
+          }
+          
+          if (newState === 'loaded' && callback.onLoad) {
+            callback.onLoad();
+          } else if (newState === 'error' && callback.onError && error) {
+            callback.onError(error);
+          }
+        } catch (e) {
+          console.error('ClerkJS coordinator callback error:', e);
+        }
+      }
+    }
+  };
+  
+  var originalAppendChild = Node.prototype.appendChild;
+  Node.prototype.appendChild = function(child) {
+    if (child.tagName === 'SCRIPT' && child.hasAttribute('data-clerk-js-script')) {
+      if (!coordinator.shouldAllowScript(child)) {
+        return child;
+      }
+    }
+    
+    return originalAppendChild.call(this, child);
+  };
+  
+  window.__clerkJSBlockingCoordinator = coordinator;
+})();
+  `.trim();
+}
+
+// Hook to get the current ClerkJS loading state from the blocking coordinator
+function useClerkJSLoadingState() {
+  const [loadingState, setLoadingState] = useState<LoadingState>('idle');
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const coordinator = (window as any).__clerkJSBlockingCoordinator;
+    if (coordinator) {
+      coordinator.registerCallback({
+        onStateChange: (state: LoadingState) => {
+          setLoadingState(state);
+        },
+      });
+    }
+  }, []);
+
+  return { loadingState };
+}
+
+/**
+ * Enhanced ClerkJS Script component with bulletproof load detection.
+ *
+ * This component renders TWO script tags:
+ * 1. A render-blocking inline script that sets up the coordinator BEFORE any ClerkJS scripts
+ * 2. The actual ClerkJS script tag (which the coordinator will manage)
+ *
+ * The blocking script intercepts script creation and prevents duplicates at the browser level.
+ */
 function ClerkJSScript(props: ClerkJSScriptProps) {
   const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant, nonce } = useClerkNextOptions();
   const { domain, proxyUrl } = useClerk();
+  const scriptRef = useRef<HTMLScriptElement>(null);
 
   /**
-   * If no publishable key, avoid appending an invalid script in the DOM.
+   * If no publishable key, avoid appending invalid scripts in the DOM.
    */
   if (!publishableKey) {
     return null;
@@ -31,26 +178,82 @@ function ClerkJSScript(props: ClerkJSScriptProps) {
   };
   const scriptUrl = clerkJsScriptUrl(options);
 
-  /**
-   * Notes:
-   * `next/script` in 13.x.x when used with App Router will fail to pass any of our `data-*` attributes, resulting in errors
-   * Nextjs App Router will automatically move inline scripts inside `<head/>`
-   * Using the `nextjs/script` for App Router with the `beforeInteractive` strategy will throw an error because our custom script will be mounted outside the `html` tag.
-   */
-  const Script = props.router === 'app' ? 'script' : NextScript;
-
-  return (
-    <Script
-      src={scriptUrl}
-      data-clerk-js-script
-      async
-      // `nextjs/script` will add defer by default and does not get removed when we async is true
-      defer={props.router === 'pages' ? false : undefined}
-      crossOrigin='anonymous'
-      strategy={props.router === 'pages' ? 'beforeInteractive' : undefined}
-      {...buildClerkJsScriptAttributes(options)}
-    />
+  // Handle state changes from the blocking coordinator
+  const handleLoad = useCallback(() => {
+    props.onLoad?.();
+  }, [props]);
+
+  const handleError = useCallback(
+    (error: Error) => {
+      props.onError?.(error);
+    },
+    [props],
   );
+
+  // Subscribe to blocking coordinator state changes
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const coordinator = (window as any).__clerkJSBlockingCoordinator;
+    if (coordinator) {
+      coordinator.registerCallback({
+        onLoad: handleLoad,
+        onError: handleError,
+        onStateChange: (state: LoadingState) => {
+          props.onLoadingStateChange?.(state);
+        },
+      });
+    }
+  }, [handleLoad, handleError, props]);
+
+  const scriptAttributes = buildClerkJsScriptAttributes(options);
+
+  if (props.router === 'app') {
+    // For App Router, use regular script tags
+    return (
+      <>
+        {/* Blocking coordinator script - MUST run first */}
+        <script
+          dangerouslySetInnerHTML={{ __html: getBlockingCoordinatorScript() }}
+          // No async/defer - this must block to set up coordination
+        />
+
+        {/* Actual ClerkJS script - managed by the coordinator */}
+        <script
+          ref={scriptRef}
+          src={scriptUrl}
+          data-clerk-js-script
+          async
+          crossOrigin='anonymous'
+          {...scriptAttributes}
+        />
+      </>
+    );
+  } else {
+    // For Pages Router, use Next.js Script components
+    return (
+      <>
+        {/* Blocking coordinator script - MUST run first and block */}
+        <NextScript
+          id='clerk-blocking-coordinator'
+          strategy='beforeInteractive'
+          dangerouslySetInnerHTML={{ __html: getBlockingCoordinatorScript() }}
+        />
+
+        {/* Actual ClerkJS script - managed by the coordinator */}
+        <NextScript
+          src={scriptUrl}
+          data-clerk-js-script
+          async
+          defer={false}
+          crossOrigin='anonymous'
+          strategy='beforeInteractive'
+          {...scriptAttributes}
+        />
+      </>
+    );
+  }
 }
 
-export { ClerkJSScript };
+export { ClerkJSScript, useClerkJSLoadingState };
+export type { ClerkJSScriptProps, LoadingState };
diff --git a/packages/shared/src/clerkJsBlockingCoordinator.ts b/packages/shared/src/clerkJsBlockingCoordinator.ts
new file mode 100644
index 00000000000..4d11d77f0eb
--- /dev/null
+++ b/packages/shared/src/clerkJsBlockingCoordinator.ts
@@ -0,0 +1,246 @@
+/**
+ * ClerkJS Blocking Coordinator
+ *
+ * This script MUST run synchronously before any ClerkJS script tags are processed.
+ * It sets up global coordination and can intercept script loading to prevent duplicates.
+ *
+ * This should be injected as an inline, render-blocking script tag.
+ */
+
+type LoadingState = 'idle' | 'loading' | 'loaded' | 'error';
+
+interface BlockingCoordinator {
+  state: LoadingState;
+  scriptUrl?: string;
+  scriptElement?: HTMLScriptElement;
+  error?: Error;
+  promise?: Promise<HTMLScriptElement>;
+  callbacks: Array<{
+    onLoad?: () => void;
+    onError?: (error: Error) => void;
+    onStateChange?: (state: LoadingState) => void;
+  }>;
+
+  shouldAllowScript(scriptElement: HTMLScriptElement): boolean;
+  registerCallback(callback: {
+    onLoad?: () => void;
+    onError?: (error: Error) => void;
+    onStateChange?: (state: LoadingState) => void;
+  }): void;
+  setState(newState: LoadingState, error?: Error): void;
+}
+
+/**
+ * Returns the inline script content that should be injected as a blocking script.
+ * This script sets up the global coordinator immediately.
+ */
+export function getBlockingCoordinatorScript(): string {
+  return `
+(function() {
+  'use strict';
+  
+  // Prevent multiple initialization
+  if (window.__clerkJSBlockingCoordinator) {
+    return;
+  }
+  
+  var coordinator = {
+    state: 'idle',
+    scriptUrl: null,
+    scriptElement: null,
+    error: null,
+    promise: null,
+    callbacks: [],
+    
+    shouldAllowScript: function(scriptElement) {
+      // Only manage ClerkJS scripts
+      if (!scriptElement.hasAttribute('data-clerk-js-script')) {
+        return true; // Allow non-ClerkJS scripts
+      }
+      
+      // If we already have a ClerkJS script, prevent duplicates
+      if (this.scriptElement && this.scriptElement.src === scriptElement.src) {
+        return false;
+      }
+      
+      // If ClerkJS is already loaded globally, prevent new scripts
+      if (window.Clerk) {
+        this.setState('loaded');
+        return false;
+      }
+      
+      // If we're currently loading, prevent new scripts
+      if (this.state === 'loading') {
+        return false;
+      }
+      
+      // This is the first ClerkJS script, adopt it
+      this.adoptScript(scriptElement);
+      return true;
+    },
+    
+    adoptScript: function(scriptElement) {
+      this.scriptElement = scriptElement;
+      this.scriptUrl = scriptElement.src;
+      this.setState('loading');
+      
+      var self = this;
+      
+      // Set up load monitoring
+      var originalOnLoad = scriptElement.onload;
+      var originalOnError = scriptElement.onerror;
+      
+      scriptElement.onload = function(event) {
+        scriptElement.setAttribute('data-clerk-loaded', 'true');
+        self.setState('loaded');
+        if (originalOnLoad) originalOnLoad.call(this, event);
+      };
+      
+      scriptElement.onerror = function(event) {
+        self.setState('error', new Error('ClerkJS failed to load'));
+        if (originalOnError) originalOnError.call(this, event);
+      };
+      
+      // Also use addEventListener for better compatibility
+      scriptElement.addEventListener('load', function() {
+        scriptElement.setAttribute('data-clerk-loaded', 'true');
+        self.setState('loaded');
+      });
+      
+      scriptElement.addEventListener('error', function() {
+        self.setState('error', new Error('ClerkJS failed to load'));
+      });
+    },
+    
+    registerCallback: function(callback) {
+      this.callbacks.push(callback);
+      
+      // Call immediately if we have a current state
+      if (callback.onStateChange) {
+        callback.onStateChange(this.state);
+      }
+      
+      if (this.state === 'loaded' && callback.onLoad) {
+        callback.onLoad();
+      } else if (this.state === 'error' && callback.onError && this.error) {
+        callback.onError(this.error);
+      }
+    },
+    
+    setState: function(newState, error) {
+      this.state = newState;
+      if (error) this.error = error;
+      
+      // Notify all callbacks
+      for (var i = 0; i < this.callbacks.length; i++) {
+        var callback = this.callbacks[i];
+        try {
+          if (callback.onStateChange) {
+            callback.onStateChange(newState);
+          }
+          
+          if (newState === 'loaded' && callback.onLoad) {
+            callback.onLoad();
+          } else if (newState === 'error' && callback.onError && error) {
+            callback.onError(error);
+          }
+        } catch (e) {
+          console.error('ClerkJS coordinator callback error:', e);
+        }
+      }
+    }
+  };
+  
+  // Intercept script creation to catch ClerkJS scripts before they load
+  var originalCreateElement = document.createElement;
+  document.createElement = function(tagName) {
+    var element = originalCreateElement.apply(this, arguments);
+    
+    if (tagName.toLowerCase() === 'script') {
+      // Set up a property setter to intercept src assignment
+      var originalSrc = element.src;
+      var srcSet = false;
+      
+      Object.defineProperty(element, 'src', {
+        get: function() {
+          return originalSrc;
+        },
+        set: function(value) {
+          originalSrc = value;
+          srcSet = true;
+          
+          // Check if this should be allowed after src is set
+          // (need to wait for src to be set to make decision)
+          setTimeout(function() {
+            if (!coordinator.shouldAllowScript(element)) {
+              // Prevent the script from loading by clearing its src
+              element.src = '';
+              element.remove();
+            }
+          }, 0);
+        },
+        configurable: true
+      });
+    }
+    
+    return element;
+  };
+  
+  // Also intercept appendChild to catch scripts added directly
+  var originalAppendChild = Node.prototype.appendChild;
+  Node.prototype.appendChild = function(child) {
+    if (child.tagName === 'SCRIPT' && child.hasAttribute('data-clerk-js-script')) {
+      if (!coordinator.shouldAllowScript(child)) {
+        // Return a dummy element to prevent errors
+        return child;
+      }
+    }
+    
+    return originalAppendChild.call(this, child);
+  };
+  
+  // Expose the coordinator globally
+  window.__clerkJSBlockingCoordinator = coordinator;
+})();
+`.trim();
+}
+
+/**
+ * Get the current state from the blocking coordinator.
+ */
+export function getBlockingCoordinatorState(): LoadingState {
+  if (typeof window === 'undefined') return 'idle';
+  const coordinator = (window as any).__clerkJSBlockingCoordinator;
+  return coordinator ? coordinator.state : 'idle';
+}
+
+/**
+ * Register callbacks with the blocking coordinator.
+ */
+export function registerWithBlockingCoordinator(callback: {
+  onLoad?: () => void;
+  onError?: (error: Error) => void;
+  onStateChange?: (state: LoadingState) => void;
+}): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  const coordinator = (window as any).__clerkJSBlockingCoordinator;
+  if (coordinator) {
+    coordinator.registerCallback(callback);
+  }
+
+  // Return a no-op unsubscribe function since the blocking coordinator
+  // doesn't need complex unsubscription
+  return () => {};
+}
+
+/**
+ * Check if ClerkJS is loaded according to the blocking coordinator.
+ */
+export function isClerkJSLoadedBlocking(): boolean {
+  if (typeof window === 'undefined') return false;
+  const coordinator = (window as any).__clerkJSBlockingCoordinator;
+  return coordinator ? coordinator.state === 'loaded' : false;
+}
+
+export type { LoadingState, BlockingCoordinator };
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 76bb1781289..d8e86b6ff1f 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -37,3 +37,4 @@ export { DEV_BROWSER_JWT_KEY, extractDevBrowserJWTFromURL, setDevBrowserJWTInURL
 export { getEnvVariable } from './getEnvVariable';
 export * from './pathMatcher';
 export * from './netlifyCacheHandler';
+export * from './clerkJsBlockingCoordinator';
diff --git a/packages/shared/src/loadClerkJsScript.ts b/packages/shared/src/loadClerkJsScript.ts
index ee3df44f089..9b34ef81032 100644
--- a/packages/shared/src/loadClerkJsScript.ts
+++ b/packages/shared/src/loadClerkJsScript.ts
@@ -1,7 +1,9 @@
 import type { ClerkOptions, SDKMetadata, Without } from '@clerk/types';
 
+import { isClerkJSLoadedBlocking, registerWithBlockingCoordinator } from './clerkJsBlockingCoordinator';
 import { buildErrorThrower } from './error';
 import { createDevOrStagingUrlCache, parsePublishableKey } from './keys';
+import { loadScript } from './loadScript';
 import { isValidProxyUrl, proxyUrlToAbsoluteURL } from './proxy';
 import { addClerkPrefix } from './url';
 import { versionSelector } from './versionSelector';
@@ -34,94 +36,71 @@ type LoadClerkJsScriptOptions = Without<ClerkOptions, 'isSatellite'> & {
 };
 
 /**
- * Hotloads the Clerk JS script.
+ * Hotloads the Clerk JS script using the blocking coordinator.
  *
- * Checks for an existing Clerk JS script and handles various loading states:
- * - If script already loaded successfully: resolves immediately
- * - If script is currently loading: waits for completion
- * - If script failed to load: attempts to load again
- * - If no script exists: loads the script.
+ * This function integrates with the render-blocking coordinator that must be
+ * set up before any ClerkJS scripts are rendered. The coordinator handles:
+ * - Script already loaded successfully: resolves immediately
+ * - Script is currently loading: waits for completion
+ * - Script failed to load: attempts to load again
+ * - No script exists: loads the script.
+ *
+ * The blocking coordinator ensures no duplicate network requests and proper
+ * state management at the browser DOM level, preventing race conditions.
  *
  * @param opts - The options used to build the Clerk JS script URL and load the script.
- *               Must include a `publishableKey` if no existing script is found.
+ *               Must include a `publishableKey`.
  *
  * @example
  * loadClerkJsScript({ publishableKey: 'pk_' });
  */
 const loadClerkJsScript = async (opts?: LoadClerkJsScriptOptions) => {
-  const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
-
-  if (existingScript) {
-    if (existingScript.getAttribute('data-clerk-loaded') === 'true') {
-      return Promise.resolve(existingScript);
-    }
-
-    return new Promise((resolve, reject) => {
-      const handleLoad = () => {
-        cleanup();
-        existingScript.setAttribute('data-clerk-loaded', 'true');
-        resolve(existingScript);
-      };
-
-      const handleError = () => {
-        cleanup();
-        existingScript.remove();
-        reject(new Error(FAILED_TO_LOAD_ERROR));
-      };
-
-      const cleanup = () => {
-        existingScript.removeEventListener('load', handleLoad);
-        existingScript.removeEventListener('error', handleError);
-      };
-
-      existingScript.addEventListener('load', handleLoad);
-      existingScript.addEventListener('error', handleError);
-
-      if (existingScript.getAttribute('data-clerk-loaded') === 'true') {
-        cleanup();
-        resolve(existingScript);
-      }
-    });
-  }
-
   if (!opts?.publishableKey) {
     errorThrower.throwMissingPublishableKeyError();
     return;
   }
 
-  return new Promise<HTMLScriptElement>((resolve, reject) => {
-    if (!document || !document.body) {
-      reject(new Error('loadClerkJsScript cannot be called when document does not exist'));
-      return;
-    }
+  try {
+    const scriptUrl = clerkJsScriptUrl(opts);
+    const attributes = buildClerkJsScriptAttributes(opts);
 
-    const script = document.createElement('script');
-    script.async = true;
-    script.setAttribute('crossorigin', 'anonymous');
-    if (opts.nonce) {
-      script.nonce = opts.nonce;
+    // Check if blocking coordinator has already handled this
+    if (isClerkJSLoadedBlocking()) {
+      // ClerkJS is already loaded, return existing script element
+      const existingScript = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+      if (existingScript) {
+        return existingScript;
+      }
     }
 
-    const handleLoad = () => {
-      script.setAttribute('data-clerk-loaded', 'true');
-      resolve(script);
-    };
-
-    const handleError = () => {
-      script.remove();
-      reject(new Error(FAILED_TO_LOAD_ERROR));
-    };
-
-    script.addEventListener('load', handleLoad);
-    script.addEventListener('error', handleError);
-
-    applyClerkJsScriptAttributes(opts)(script);
-
-    script.src = clerkJsScriptUrl(opts);
-    document.body.appendChild(script);
-  }).catch(() => {
+    // Use blocking coordinator if available, otherwise fall back to loadScript
+    if (typeof window !== 'undefined' && (window as any).__clerkJSBlockingCoordinator) {
+      return new Promise<HTMLScriptElement>((resolve, reject) => {
+        registerWithBlockingCoordinator({
+          onLoad: () => {
+            const script = document.querySelector<HTMLScriptElement>('script[data-clerk-js-script]');
+            if (script) {
+              resolve(script);
+            } else {
+              reject(new Error('ClerkJS loaded but script element not found'));
+            }
+          },
+          onError: error => {
+            reject(error);
+          },
+        });
+      });
+    } else {
+      // Fallback to traditional loading if blocking coordinator is not available
+      return await loadScript(scriptUrl, {
+        ...attributes,
+        async: true,
+        crossOrigin: 'anonymous',
+      });
+    }
+  } catch {
     throw new Error(FAILED_TO_LOAD_ERROR);
-  });
+  }
 };
 
 /**
@@ -179,12 +158,10 @@ const buildClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => {
   return obj;
 };
 
-const applyClerkJsScriptAttributes = (options: LoadClerkJsScriptOptions) => (script: HTMLScriptElement) => {
-  const attributes = buildClerkJsScriptAttributes(options);
-  for (const attribute in attributes) {
-    script.setAttribute(attribute, attributes[attribute]);
-  }
-};
-
 export { loadClerkJsScript, buildClerkJsScriptAttributes, clerkJsScriptUrl };
+export {
+  getBlockingCoordinatorState as getClerkJSState,
+  isClerkJSLoadedBlocking as isClerkJSLoaded,
+  registerWithBlockingCoordinator as onClerkJSStateChange,
+} from './clerkJsBlockingCoordinator';
 export type { LoadClerkJsScriptOptions };

From 6d06be869ef8f2fca1aee24bc4bd76514010649b Mon Sep 17 00:00:00 2001
From: Jacek <jacek@clerk.dev>
Date: Thu, 29 May 2025 12:21:43 -0500
Subject: [PATCH 3/4] wip

---
 packages/nextjs/src/utils/clerk-js-script.tsx |  13 +-
 .../shared/src/clerkJsBlockingCoordinator.ts  | 160 ++++++++++++------
 2 files changed, 112 insertions(+), 61 deletions(-)

diff --git a/packages/nextjs/src/utils/clerk-js-script.tsx b/packages/nextjs/src/utils/clerk-js-script.tsx
index 1d56724c416..80a742f10fd 100644
--- a/packages/nextjs/src/utils/clerk-js-script.tsx
+++ b/packages/nextjs/src/utils/clerk-js-script.tsx
@@ -150,10 +150,11 @@ function useClerkJSLoadingState() {
  * Enhanced ClerkJS Script component with bulletproof load detection.
  *
  * This component renders TWO script tags:
- * 1. A render-blocking inline script that sets up the coordinator BEFORE any ClerkJS scripts
+ * 1. A render-blocking inline script that sets up the coordinator globally
  * 2. The actual ClerkJS script tag (which the coordinator will manage)
  *
- * The blocking script intercepts script creation and prevents duplicates at the browser level.
+ * The coordinator uses comprehensive DOM interception to catch scripts regardless
+ * of where they're placed (head, body, or injected dynamically).
  */
 function ClerkJSScript(props: ClerkJSScriptProps) {
   const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant, nonce } = useClerkNextOptions();
@@ -210,6 +211,7 @@ function ClerkJSScript(props: ClerkJSScriptProps) {
 
   if (props.router === 'app') {
     // For App Router, use regular script tags
+    // The coordinator will catch these regardless of placement
     return (
       <>
         {/* Blocking coordinator script - MUST run first */}
@@ -222,7 +224,7 @@ function ClerkJSScript(props: ClerkJSScriptProps) {
         <script
           ref={scriptRef}
           src={scriptUrl}
-          data-clerk-js-script
+          data-clerk-js-script='true'
           async
           crossOrigin='anonymous'
           {...scriptAttributes}
@@ -230,7 +232,8 @@ function ClerkJSScript(props: ClerkJSScriptProps) {
       </>
     );
   } else {
-    // For Pages Router, use Next.js Script components
+    // For Pages Router, use Next.js Script components with beforeInteractive
+    // This ensures both scripts are placed in head and execute early
     return (
       <>
         {/* Blocking coordinator script - MUST run first and block */}
@@ -243,7 +246,7 @@ function ClerkJSScript(props: ClerkJSScriptProps) {
         {/* Actual ClerkJS script - managed by the coordinator */}
         <NextScript
           src={scriptUrl}
-          data-clerk-js-script
+          data-clerk-js-script='true'
           async
           defer={false}
           crossOrigin='anonymous'
diff --git a/packages/shared/src/clerkJsBlockingCoordinator.ts b/packages/shared/src/clerkJsBlockingCoordinator.ts
index 4d11d77f0eb..d64826d5cb3 100644
--- a/packages/shared/src/clerkJsBlockingCoordinator.ts
+++ b/packages/shared/src/clerkJsBlockingCoordinator.ts
@@ -32,7 +32,7 @@ interface BlockingCoordinator {
 
 /**
  * Returns the inline script content that should be injected as a blocking script.
- * This script sets up the global coordinator immediately.
+ * This script sets up the global coordinator immediately and intercepts all script loading.
  */
 export function getBlockingCoordinatorScript(): string {
   return `
@@ -86,30 +86,36 @@ export function getBlockingCoordinatorScript(): string {
       
       var self = this;
       
-      // Set up load monitoring
-      var originalOnLoad = scriptElement.onload;
-      var originalOnError = scriptElement.onerror;
-      
-      scriptElement.onload = function(event) {
+      // Set up load monitoring with multiple methods for better compatibility
+      var handleLoad = function() {
         scriptElement.setAttribute('data-clerk-loaded', 'true');
         self.setState('loaded');
-        if (originalOnLoad) originalOnLoad.call(this, event);
       };
       
-      scriptElement.onerror = function(event) {
+      var handleError = function() {
         self.setState('error', new Error('ClerkJS failed to load'));
-        if (originalOnError) originalOnError.call(this, event);
       };
       
-      // Also use addEventListener for better compatibility
-      scriptElement.addEventListener('load', function() {
-        scriptElement.setAttribute('data-clerk-loaded', 'true');
-        self.setState('loaded');
-      });
+      // Use multiple approaches to catch load events
+      if (scriptElement.onload !== undefined) {
+        var originalOnLoad = scriptElement.onload;
+        scriptElement.onload = function(event) {
+          handleLoad();
+          if (originalOnLoad) originalOnLoad.call(this, event);
+        };
+      }
       
-      scriptElement.addEventListener('error', function() {
-        self.setState('error', new Error('ClerkJS failed to load'));
-      });
+      if (scriptElement.onerror !== undefined) {
+        var originalOnError = scriptElement.onerror;
+        scriptElement.onerror = function(event) {
+          handleError();
+          if (originalOnError) originalOnError.call(this, event);
+        };
+      }
+      
+      // Also use addEventListener for better compatibility
+      scriptElement.addEventListener('load', handleLoad);
+      scriptElement.addEventListener('error', handleError);
     },
     
     registerCallback: function(callback) {
@@ -151,54 +157,96 @@ export function getBlockingCoordinatorScript(): string {
     }
   };
   
-  // Intercept script creation to catch ClerkJS scripts before they load
-  var originalCreateElement = document.createElement;
-  document.createElement = function(tagName) {
-    var element = originalCreateElement.apply(this, arguments);
-    
-    if (tagName.toLowerCase() === 'script') {
-      // Set up a property setter to intercept src assignment
-      var originalSrc = element.src;
-      var srcSet = false;
-      
-      Object.defineProperty(element, 'src', {
-        get: function() {
-          return originalSrc;
-        },
-        set: function(value) {
-          originalSrc = value;
-          srcSet = true;
-          
-          // Check if this should be allowed after src is set
-          // (need to wait for src to be set to make decision)
-          setTimeout(function() {
-            if (!coordinator.shouldAllowScript(element)) {
-              // Prevent the script from loading by clearing its src
-              element.src = '';
-              element.remove();
-            }
-          }, 0);
-        },
-        configurable: true
-      });
+  // Function to check and potentially intercept a script
+  function interceptScript(scriptElement) {
+    if (scriptElement && scriptElement.tagName === 'SCRIPT') {
+      if (scriptElement.hasAttribute('data-clerk-js-script')) {
+        return coordinator.shouldAllowScript(scriptElement);
+      }
     }
-    
-    return element;
-  };
+    return true;
+  }
   
-  // Also intercept appendChild to catch scripts added directly
+  // Intercept appendChild on all nodes
   var originalAppendChild = Node.prototype.appendChild;
   Node.prototype.appendChild = function(child) {
-    if (child.tagName === 'SCRIPT' && child.hasAttribute('data-clerk-js-script')) {
-      if (!coordinator.shouldAllowScript(child)) {
-        // Return a dummy element to prevent errors
-        return child;
-      }
+    if (!interceptScript(child)) {
+      // Create a dummy script element to return
+      var dummy = document.createElement('script');
+      dummy.src = child.src;
+      Object.keys(child.attributes || {}).forEach(function(key) {
+        var attr = child.attributes[key];
+        if (attr && attr.name && attr.value) {
+          dummy.setAttribute(attr.name, attr.value);
+        }
+      });
+      return dummy;
     }
     
     return originalAppendChild.call(this, child);
   };
   
+  // Intercept insertBefore
+  var originalInsertBefore = Node.prototype.insertBefore;
+  Node.prototype.insertBefore = function(newNode, referenceNode) {
+    if (!interceptScript(newNode)) {
+      var dummy = document.createElement('script');
+      dummy.src = newNode.src;
+      return dummy;
+    }
+    
+    return originalInsertBefore.call(this, newNode, referenceNode);
+  };
+  
+  // Also watch for scripts being set via innerHTML or similar
+  var observer = new MutationObserver(function(mutations) {
+    mutations.forEach(function(mutation) {
+      if (mutation.type === 'childList') {
+        Array.prototype.slice.call(mutation.addedNodes).forEach(function(node) {
+          if (node.nodeType === 1) { // Element node
+            if (node.tagName === 'SCRIPT' && node.hasAttribute('data-clerk-js-script')) {
+              if (!coordinator.shouldAllowScript(node)) {
+                node.remove();
+              }
+            }
+            
+            // Also check children in case scripts are added in bulk
+            var scripts = node.querySelectorAll ? node.querySelectorAll('script[data-clerk-js-script]') : [];
+            for (var i = 0; i < scripts.length; i++) {
+              if (!coordinator.shouldAllowScript(scripts[i])) {
+                scripts[i].remove();
+              }
+            }
+          }
+        });
+      }
+    });
+  });
+  
+  // Start observing
+  if (document.body) {
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+  } else {
+    // If body doesn't exist yet, wait for it
+    document.addEventListener('DOMContentLoaded', function() {
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true
+      });
+    });
+  }
+  
+  // Also observe head if it exists
+  if (document.head) {
+    observer.observe(document.head, {
+      childList: true,
+      subtree: true
+    });
+  }
+  
   // Expose the coordinator globally
   window.__clerkJSBlockingCoordinator = coordinator;
 })();

From b6431b1101036b32f196f39f3fd958f58535fd30 Mon Sep 17 00:00:00 2001
From: Jacek <jacek@clerk.dev>
Date: Thu, 29 May 2025 13:20:55 -0500
Subject: [PATCH 4/4] wip

---
 packages/nextjs/src/utils/clerk-js-script.tsx | 78 ++++++++++---------
 1 file changed, 41 insertions(+), 37 deletions(-)

diff --git a/packages/nextjs/src/utils/clerk-js-script.tsx b/packages/nextjs/src/utils/clerk-js-script.tsx
index 80a742f10fd..e27f86d026d 100644
--- a/packages/nextjs/src/utils/clerk-js-script.tsx
+++ b/packages/nextjs/src/utils/clerk-js-script.tsx
@@ -1,5 +1,6 @@
 import { useClerk } from '@clerk/clerk-react';
 import { buildClerkJsScriptAttributes, clerkJsScriptUrl } from '@clerk/clerk-react/internal';
+import Head from 'next/head';
 import NextScript from 'next/script';
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 
@@ -149,17 +150,14 @@ function useClerkJSLoadingState() {
 /**
  * Enhanced ClerkJS Script component with bulletproof load detection.
  *
- * This component renders TWO script tags:
- * 1. A render-blocking inline script that sets up the coordinator globally
- * 2. The actual ClerkJS script tag (which the coordinator will manage)
- *
- * The coordinator uses comprehensive DOM interception to catch scripts regardless
- * of where they're placed (head, body, or injected dynamically).
+ * This component ensures the blocking coordinator is loaded in the document head
+ * before any ClerkJS scripts, regardless of the router type.
  */
 function ClerkJSScript(props: ClerkJSScriptProps) {
   const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant, nonce } = useClerkNextOptions();
   const { domain, proxyUrl } = useClerk();
   const scriptRef = useRef<HTMLScriptElement>(null);
+  const coordinatorInjected = useRef(false);
 
   /**
    * If no publishable key, avoid appending invalid scripts in the DOM.
@@ -179,6 +177,31 @@ function ClerkJSScript(props: ClerkJSScriptProps) {
   };
   const scriptUrl = clerkJsScriptUrl(options);
 
+  // Inject coordinator script into head manually to ensure it's there first
+  useEffect(() => {
+    if (typeof window === 'undefined' || coordinatorInjected.current) return;
+
+    // Check if coordinator already exists
+    if ((window as any).__clerkJSBlockingCoordinator) {
+      coordinatorInjected.current = true;
+      return;
+    }
+
+    // Create and inject coordinator script into head
+    const coordinatorScript = document.createElement('script');
+    coordinatorScript.id = 'clerk-blocking-coordinator';
+    coordinatorScript.innerHTML = getBlockingCoordinatorScript();
+
+    // Insert at the beginning of head to ensure it runs first
+    if (document.head.firstChild) {
+      document.head.insertBefore(coordinatorScript, document.head.firstChild);
+    } else {
+      document.head.appendChild(coordinatorScript);
+    }
+
+    coordinatorInjected.current = true;
+  }, []);
+
   // Handle state changes from the blocking coordinator
   const handleLoad = useCallback(() => {
     props.onLoad?.();
@@ -210,17 +233,9 @@ function ClerkJSScript(props: ClerkJSScriptProps) {
   const scriptAttributes = buildClerkJsScriptAttributes(options);
 
   if (props.router === 'app') {
-    // For App Router, use regular script tags
-    // The coordinator will catch these regardless of placement
+    // For App Router, use Next.js Head component to ensure script goes to head
     return (
-      <>
-        {/* Blocking coordinator script - MUST run first */}
-        <script
-          dangerouslySetInnerHTML={{ __html: getBlockingCoordinatorScript() }}
-          // No async/defer - this must block to set up coordination
-        />
-
-        {/* Actual ClerkJS script - managed by the coordinator */}
+      <Head>
         <script
           ref={scriptRef}
           src={scriptUrl}
@@ -229,31 +244,20 @@ function ClerkJSScript(props: ClerkJSScriptProps) {
           crossOrigin='anonymous'
           {...scriptAttributes}
         />
-      </>
+      </Head>
     );
   } else {
     // For Pages Router, use Next.js Script components with beforeInteractive
-    // This ensures both scripts are placed in head and execute early
     return (
-      <>
-        {/* Blocking coordinator script - MUST run first and block */}
-        <NextScript
-          id='clerk-blocking-coordinator'
-          strategy='beforeInteractive'
-          dangerouslySetInnerHTML={{ __html: getBlockingCoordinatorScript() }}
-        />
-
-        {/* Actual ClerkJS script - managed by the coordinator */}
-        <NextScript
-          src={scriptUrl}
-          data-clerk-js-script='true'
-          async
-          defer={false}
-          crossOrigin='anonymous'
-          strategy='beforeInteractive'
-          {...scriptAttributes}
-        />
-      </>
+      <NextScript
+        src={scriptUrl}
+        data-clerk-js-script='true'
+        async
+        defer={false}
+        crossOrigin='anonymous'
+        strategy='beforeInteractive'
+        {...scriptAttributes}
+      />
     );
   }
 }