fix(react): make __internal_* URL props take precedence over bundled constructors (#7919)

Author: jacekradko

.changeset/internal-url-precedence.md

@@ -0,0 +1,5 @@
+---
+'@clerk/react': patch
+---
+
+Fix `__internal_clerkJSUrl` and `__internal_clerkUIUrl` being silently ignored when bundled `Clerk` or `ui.ClerkUI` constructors are provided. Internal URL overrides now take precedence.

packages/react/src/__tests__/isomorphicClerk.test.ts

@@ -1,5 +1,6 @@
+import { loadClerkJSScript, loadClerkUIScript } from '@clerk/shared/loadClerkJsScript';
 import type { Resources, UnsubscribeCallback } from '@clerk/shared/types';
-import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { IsomorphicClerk } from '../isomorphicClerk';
 
@@ -12,7 +13,9 @@ vi.mock('@clerk/shared/loadClerkJsScript', () => ({
 describe('isomorphicClerk', () => {
   beforeAll(() => {
     vi.useFakeTimers();
+  });
 
+  beforeEach(() => {
     // Set up minimal global Clerk objects to prevent errors during initialization
     (global as any).Clerk = {
       load: vi.fn().mockResolvedValue(undefined),
@@ -21,13 +24,18 @@ describe('isomorphicClerk', () => {
     (global as any).__internal_ClerkUICtor = vi.fn();
   });
 
-  afterAll(() => {
-    vi.useRealTimers();
+  afterEach(() => {
+    vi.mocked(loadClerkJSScript).mockClear();
+    vi.mocked(loadClerkUIScript).mockClear();
     // Clean up globals
     delete (global as any).Clerk;
     delete (global as any).__internal_ClerkUICtor;
   });
 
+  afterAll(() => {
+    vi.useRealTimers();
+  });
+
   it('instantiates a IsomorphicClerk instance', () => {
     expect(() => {
       new IsomorphicClerk({ publishableKey: 'pk_test_XXX' });
@@ -117,4 +125,79 @@ describe('isomorphicClerk', () => {
     expect(listenerCallHistory).toEqual([]);
     expect(listenerCallHistory.length).toBe(0);
   });
+
+  describe('__internal_* URL precedence', () => {
+    it('__internal_clerkJSUrl causes script loading even when Clerk prop is provided', async () => {
+      const mockClerkCtor = vi.fn().mockImplementation(() => ({
+        load: vi.fn().mockResolvedValue(undefined),
+        loaded: false,
+      }));
+      // Make the mock pass the isConstructor check
+      mockClerkCtor.prototype = {};
+
+      const clerk = new IsomorphicClerk({
+        publishableKey: 'pk_test_XXX',
+        Clerk: mockClerkCtor as any,
+        __internal_clerkJSUrl: 'https://staging.clerk.com/clerk.js',
+      });
+
+      // Trigger loading by accessing the private method
+      await (clerk as any).getClerkJsEntryChunk();
+
+      // Should load from URL, not use the bundled constructor
+      expect(loadClerkJSScript).toHaveBeenCalled();
+      expect(mockClerkCtor).not.toHaveBeenCalled();
+    });
+
+    it('__internal_clerkUIUrl causes script loading even when ui.ClerkUI prop is provided', async () => {
+      const mockClerkUI = vi.fn();
+
+      const clerk = new IsomorphicClerk({
+        publishableKey: 'pk_test_XXX',
+        ui: { ClerkUI: mockClerkUI } as any,
+        __internal_clerkUIUrl: 'https://staging.clerk.com/clerk-ui.js',
+      });
+
+      const result = await (clerk as any).getClerkUIEntryChunk();
+
+      // Should load from URL, not return the bundled ClerkUI
+      expect(loadClerkUIScript).toHaveBeenCalled();
+      expect(result).not.toBe(mockClerkUI);
+    });
+
+    it('Clerk prop is used when no __internal_clerkJSUrl is set', async () => {
+      const mockInstance = {
+        load: vi.fn().mockResolvedValue(undefined),
+        loaded: false,
+      };
+      const mockClerkCtor = vi.fn().mockImplementation(() => mockInstance);
+      mockClerkCtor.prototype = {};
+
+      const clerk = new IsomorphicClerk({
+        publishableKey: 'pk_test_XXX',
+        Clerk: mockClerkCtor as any,
+      });
+
+      await (clerk as any).getClerkJsEntryChunk();
+
+      // Should use the bundled constructor, not load from URL
+      expect(loadClerkJSScript).not.toHaveBeenCalled();
+      expect(mockClerkCtor).toHaveBeenCalled();
+    });
+
+    it('ui.ClerkUI is used when no __internal_clerkUIUrl is set', async () => {
+      const mockClerkUI = vi.fn();
+
+      const clerk = new IsomorphicClerk({
+        publishableKey: 'pk_test_XXX',
+        ui: { ClerkUI: mockClerkUI } as any,
+      });
+
+      const result = await (clerk as any).getClerkUIEntryChunk();
+
+      // Should return the bundled ClerkUI, not load from URL
+      expect(loadClerkUIScript).not.toHaveBeenCalled();
+      expect(result).toBe(mockClerkUI);
+    });
+  });
 });

packages/react/src/isomorphicClerk.ts

@@ -488,7 +488,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
 
   private async getClerkJsEntryChunk(): Promise<HeadlessBrowserClerk | BrowserClerk> {
     // Hotload bundle
-    if (!this.options.Clerk && !__BUILD_DISABLE_RHC__) {
+    if ((!this.options.Clerk || this.options.__internal_clerkJSUrl) && !__BUILD_DISABLE_RHC__) {
       // the UMD script sets the global.Clerk instance
       // we do not want to await here as we
       await loadClerkJSScript({
@@ -501,7 +501,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     }
 
     // Otherwise, set global.Clerk to the bundled ctor or instance
-    if (this.options.Clerk) {
+    if (this.options.Clerk && !this.options.__internal_clerkJSUrl) {
       global.Clerk = isConstructor<BrowserClerkConstructor | HeadlessBrowserClerkConstructor>(this.options.Clerk)
         ? new this.options.Clerk(this.#publishableKey, { proxyUrl: this.proxyUrl, domain: this.domain })
         : this.options.Clerk;
@@ -518,12 +518,13 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
   private async getClerkUIEntryChunk(): Promise<ClerkUIConstructor | undefined> {
     // Support bundled UI via ui.ClerkUI prop
     const uiProp = (this.options as { ui?: { __brand?: string; ClerkUI?: ClerkUIConstructor } }).ui;
-    if (uiProp?.ClerkUI) {
+    const hasInternalUrl = !!this.options.__internal_clerkUIUrl;
+    if (uiProp?.ClerkUI && !hasInternalUrl) {
       return uiProp.ClerkUI;
     }
 
     // Skip CDN prefetch when ui prop is passed (bundled UI) or prefetchUI is false
-    if (uiProp || this.options.prefetchUI === false) {
+    if ((uiProp || this.options.prefetchUI === false) && !hasInternalUrl) {
       return undefined;
     }