feat(ui): Add unified ui prop with RSC support via conditional exports

.changeset/shiny-owls-dance.md

@@ -0,0 +1,19 @@
+---
+'@clerk/ui': minor
+'@clerk/react': minor
+'@clerk/vue': minor
+'@clerk/astro': minor
+'@clerk/chrome-extension': minor
+'@clerk/shared': minor
+---
+
+Add `ui` prop to ClerkProvider for passing `@clerk/ui`
+
+Usage:
+```tsx
+import { ui } from '@clerk/ui';
+
+<ClerkProvider ui={ui}>
+  ...
+</ClerkProvider>
+```

integration/templates/express-vite/src/client/main.ts

@@ -1,13 +1,15 @@
 import { Clerk } from '@clerk/clerk-js';
-import { ClerkUi } from '@clerk/ui/entry';
+import { ui } from '@clerk/ui';
 
 const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
 
 document.addEventListener('DOMContentLoaded', async function () {
   const clerk = new Clerk(publishableKey);
 
+  // Use bundled UI via ui.ClerkUI
   await clerk.load({
-    clerkUiCtor: ClerkUi,
+    ui,
+    ClerkUI: ui.ClerkUI,
   });
 
   if (clerk.isSignedIn) {

packages/astro/src/internal/create-clerk-instance.ts

@@ -4,7 +4,7 @@ import {
   setClerkJsLoadingErrorPackageName,
 } from '@clerk/shared/loadClerkJsScript';
 import type { ClerkOptions } from '@clerk/shared/types';
-import type { ClerkUiConstructor } from '@clerk/shared/ui';
+import type { ClerkUIConstructor } from '@clerk/shared/ui';
 import type { Ui } from '@clerk/ui/internal';
 
 import { $clerkStore } from '../stores/external';
@@ -40,7 +40,7 @@ async function createClerkInstanceInternal<TUi extends Ui = Ui>(options?: AstroC
   // Both functions return early if the scripts are already loaded
   // (e.g., via middleware-injected script tags in the HTML head).
   const clerkJsChunk = getClerkJsEntryChunk(options);
-  const clerkUiCtor = getClerkUiEntryChunk(options);
+  const ClerkUI = getClerkUiEntryChunk(options);
 
   await clerkJsChunk;
 
@@ -59,7 +59,7 @@ async function createClerkInstanceInternal<TUi extends Ui = Ui>(options?: AstroC
     routerReplace: createNavigationHandler(window.history.replaceState.bind(window.history)),
     ...options,
     // Pass the clerk-ui constructor promise to clerk.load()
-    clerkUiCtor,
+    ClerkUI,
   } as unknown as ClerkOptions;
 
   initOptions = clerkOptions;
@@ -109,23 +109,27 @@ async function getClerkJsEntryChunk<TUi extends Ui = Ui>(options?: AstroClerkCre
 }
 
 /**
- * Gets the ClerkUI constructor, either from options or by loading the script.
- * Returns early if window.__internal_ClerkUiCtor already exists.
+ * Gets the ClerkUI constructor by loading from CDN with version pinning.
  */
 async function getClerkUiEntryChunk<TUi extends Ui = Ui>(
   options?: AstroClerkCreateInstanceParams<TUi>,
-): Promise<ClerkUiConstructor> {
-  if (options?.clerkUiCtor) {
-    return options.clerkUiCtor;
-  }
-
-  await loadClerkUiScript(options);
-
-  if (!window.__internal_ClerkUiCtor) {
+): Promise<ClerkUIConstructor> {
+  // Load UI from CDN with version pinning from ui.version
+  await loadClerkUiScript(
+    options
+      ? {
+          ...options,
+          clerkUiVersion: options.ui?.version,
+          clerkUiUrl: options.ui?.url,
+        }
+      : undefined,
+  );
+
+  if (!window.__internal_ClerkUICtor) {
     throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.');
   }
 
-  return window.__internal_ClerkUiCtor;
+  return window.__internal_ClerkUICtor;
 }
 
 export { createClerkInstance, updateClerkOptions };

packages/astro/src/types.ts

@@ -7,7 +7,7 @@ import type {
   ShowProps,
   Without,
 } from '@clerk/shared/types';
-import type { ClerkUiConstructor } from '@clerk/shared/ui';
+import type { ClerkUIConstructor } from '@clerk/shared/ui';
 import type { Appearance, Ui } from '@clerk/ui/internal';
 
 type AstroClerkUpdateOptions<TUi extends Ui = Ui> = Pick<ClerkOptions, 'localization'> & {
@@ -36,6 +36,11 @@ type AstroClerkIntegrationParams<TUi extends Ui = Ui> = Without<
      * The URL that `@clerk/ui` should be hot-loaded from.
      */
     clerkUiUrl?: string;
+    /**
+     * The Clerk UI bundle to use. When provided with a bundled UI via
+     * `ui.ClerkUI`, it will be used instead of loading from CDN.
+     */
+    ui?: TUi;
   };
 
 type AstroClerkCreateInstanceParams<TUi extends Ui = Ui> = AstroClerkIntegrationParams<TUi> & {
@@ -59,7 +64,7 @@ declare global {
     __astro_clerk_component_props: Map<string, Map<string, Record<string, unknown>>>;
     __astro_clerk_function_props: Map<string, Map<string, Record<string, unknown>>>;
     Clerk: BrowserClerk;
-    __internal_ClerkUiCtor?: ClerkUiConstructor;
+    __internal_ClerkUICtor?: ClerkUIConstructor;
   }
 }
 

packages/chrome-extension/src/react/ClerkProvider.tsx

@@ -2,7 +2,7 @@ import type { Clerk } from '@clerk/clerk-js/no-rhc';
 import type { ClerkProviderProps as ClerkReactProviderProps } from '@clerk/react';
 import { ClerkProvider as ClerkReactProvider } from '@clerk/react';
 import type { Ui } from '@clerk/react/internal';
-import { ClerkUi } from '@clerk/ui/entry';
+import { ui } from '@clerk/ui';
 import React from 'react';
 
 import { createClerkClient } from '../internal/clerk';
@@ -32,11 +32,14 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ChromeExtensionClerkPr
     return null;
   }
 
+  // Chrome extension must use bundled UI (no CDN access in extensions)
+  const bundledUi = { ...ui, __internal_forceBundledUI: true } as typeof ui;
+
   return (
     <ClerkReactProvider
-      {...rest}
+      {...(rest as any)}
       Clerk={clerkInstance}
-      clerkUiCtor={ClerkUi}
+      ui={bundledUi}
       standardBrowser={!syncHost}
     >
       {children}

packages/clerk-js/sandbox/app.ts

@@ -446,7 +446,7 @@ void (async () => {
       ...(componentControls.clerk.getProps() ?? {}),
       signInUrl: '/sign-in',
       signUpUrl: '/sign-up',
-      clerkUiCtor: window.__internal_ClerkUiCtor,
+      ClerkUI: window.__internal_ClerkUICtor,
     });
     renderCurrentRoute();
     updateVariables();

packages/clerk-js/sandbox/template.html

@@ -355,7 +355,7 @@
     </main>
 
     <!-- This app is in the Team SDK organization. -->
-    <!-- Load the UI bundle first, so window.__internal_ClerkUiCtor is available -->
+    <!-- Load the UI bundle first, so window.__internal_ClerkUICtor is available -->
     <script
       type="text/javascript"
       src="<%= uiScriptUrl %>"

packages/clerk-js/src/core/clerk.ts

@@ -485,8 +485,8 @@ export class Clerk implements ClerkInterface {
     this.#options = this.#initOptions(options);
 
     // Initialize ClerkUi if it was provided
-    if (this.#options.clerkUiCtor) {
-      this.#clerkUi = Promise.resolve(this.#options.clerkUiCtor).then(
+    if (this.#options.ClerkUI) {
+      this.#clerkUi = Promise.resolve(this.#options.ClerkUI).then(
         ClerkUI =>
           new ClerkUI(
             () => this,

packages/clerk-js/src/global.d.ts

@@ -18,7 +18,7 @@ interface Window {
   __internal_onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
   __internal_onAfterSetActive: () => Promise<void> | void;
   // eslint-disable-next-line @typescript-eslint/consistent-type-imports
-  __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor;
+  __internal_ClerkUICtor?: import('@clerk/shared/types').ClerkUIConstructor;
   /**
    * Promise used for coordination between standalone getToken() from @clerk/shared and clerk-js.
    * When getToken() is called before Clerk loads, it creates this promise with __resolve/__reject callbacks.

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

@@ -18,14 +18,14 @@ describe('isomorphicClerk', () => {
       load: vi.fn().mockResolvedValue(undefined),
       loaded: false,
     };
-    (global as any).__internal_ClerkUiCtor = vi.fn();
+    (global as any).__internal_ClerkUICtor = vi.fn();
   });
 
   afterAll(() => {
     vi.useRealTimers();
     // Clean up globals
     delete (global as any).Clerk;
-    delete (global as any).__internal_ClerkUiCtor;
+    delete (global as any).__internal_ClerkUICtor;
   });
 
   it('instantiates a IsomorphicClerk instance', () => {

packages/react/src/contexts/ClerkProvider.tsx

@@ -9,6 +9,7 @@ import { ClerkContextProvider } from './ClerkContextProvider';
 
 function ClerkProviderBase<TUi extends Ui>(props: ClerkProviderProps<TUi>) {
   const { initialState, children, ...restIsomorphicClerkOptions } = props;
+
   const isomorphicClerkOptions = restIsomorphicClerkOptions as unknown as IsomorphicClerkOptions;
 
   return (

packages/react/src/isomorphicClerk.ts

@@ -59,7 +59,7 @@ import type {
   WaitlistResource,
   Without,
 } from '@clerk/shared/types';
-import type { ClerkUiConstructor } from '@clerk/shared/ui';
+import type { ClerkUIConstructor } from '@clerk/shared/ui';
 import { handleValueOrFn } from '@clerk/shared/utils';
 
 import { errorThrower } from './errors/errorThrower';
@@ -87,7 +87,7 @@ const SDK_METADATA = {
 
 export interface Global {
   Clerk?: HeadlessBrowserClerk | BrowserClerk;
-  __internal_ClerkUiCtor?: ClerkUiConstructor;
+  __internal_ClerkUICtor?: ClerkUIConstructor;
 }
 
 declare const global: Global;
@@ -461,12 +461,12 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     }
 
     try {
-      const clerkUiCtor = this.getClerkUiEntryChunk();
+      const ClerkUI = this.getClerkUiEntryChunk();
       const clerk = await this.getClerkJsEntryChunk();
 
       if (!clerk.loaded) {
         this.beforeLoad(clerk);
-        await clerk.load({ ...this.options, clerkUiCtor });
+        await clerk.load({ ...this.options, ClerkUI });
       }
       if (clerk.loaded) {
         this.replayInterceptedInvocations(clerk);
@@ -508,11 +508,13 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     return global.Clerk;
   }
 
-  private async getClerkUiEntryChunk(): Promise<ClerkUiConstructor> {
-    if (this.options.clerkUiCtor) {
-      return this.options.clerkUiCtor;
+  private async getClerkUiEntryChunk(): Promise<ClerkUIConstructor> {
+    // Use bundled UI constructor if forced (e.g., Chrome Extension) and ui.ClerkUI is available
+    if (this.options.ui?.__internal_forceBundledUI && this.options.ui.ClerkUI) {
+      return this.options.ui.ClerkUI;
     }
 
+    // Default: load from CDN, using ui.version if available for version pinning
     await loadClerkUiScript({
       ...this.options,
       clerkUiVersion: this.options.ui?.version,
@@ -523,11 +525,11 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
       nonce: this.options.nonce,
     });
 
-    if (!global.__internal_ClerkUiCtor) {
+    if (!global.__internal_ClerkUICtor) {
       throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.');
     }
 
-    return global.__internal_ClerkUiCtor;
+    return global.__internal_ClerkUICtor;
   }
 
   public on: Clerk['on'] = (...args) => {

packages/react/src/types.ts

@@ -8,7 +8,7 @@ import type {
   SignUpRedirectOptions,
   TasksRedirectOptions,
 } from '@clerk/shared/types';
-import type { ClerkUiConstructor } from '@clerk/shared/ui';
+import type { ClerkUIConstructor } from '@clerk/shared/ui';
 import type { Appearance, ExtractAppearanceType, Ui } from '@clerk/ui/internal';
 import type React from 'react';
 
@@ -29,7 +29,7 @@ declare global {
     __clerk_publishable_key?: string;
     __clerk_proxy_url?: Clerk['proxyUrl'];
     __clerk_domain?: Clerk['domain'];
-    __internal_ClerkUiCtor?: ClerkUiConstructor;
+    __internal_ClerkUICtor?: ClerkUIConstructor;
   }
 }
 

packages/shared/src/__tests__/loadClerkJsScript.spec.ts

@@ -281,7 +281,7 @@ describe('loadClerkUiScript(options)', () => {
     (loadScript as Mock).mockResolvedValue(undefined);
     document.querySelector = vi.fn().mockReturnValue(null);
 
-    (window as any).__internal_ClerkUiCtor = undefined;
+    (window as any).__internal_ClerkUICtor = undefined;
 
     vi.useFakeTimers();
   });
@@ -297,7 +297,7 @@ describe('loadClerkUiScript(options)', () => {
   });
 
   test('returns null immediately when ClerkUI is already loaded', async () => {
-    (window as any).__internal_ClerkUiCtor = mockClerkUi;
+    (window as any).__internal_ClerkUICtor = mockClerkUi;
 
     const result = await loadClerkUiScript({ publishableKey: mockPublishableKey });
     expect(result).toBeNull();
@@ -309,7 +309,7 @@ describe('loadClerkUiScript(options)', () => {
 
     // Simulate ClerkUI becoming available after 250ms
     setTimeout(() => {
-      (window as any).__internal_ClerkUiCtor = mockClerkUi;
+      (window as any).__internal_ClerkUICtor = mockClerkUi;
     }, 250);
 
     // Advance timers to allow polling to detect ClerkUI
@@ -343,7 +343,7 @@ describe('loadClerkUiScript(options)', () => {
 
     expect(rejectedWith).toBeInstanceOf(ClerkRuntimeError);
     expect(rejectedWith.message).toContain('Failed to load Clerk UI');
-    expect((window as any).__internal_ClerkUiCtor).toBeUndefined();
+    expect((window as any).__internal_ClerkUICtor).toBeUndefined();
   });
 
   test('waits for existing script with timeout', async () => {
@@ -354,7 +354,7 @@ describe('loadClerkUiScript(options)', () => {
 
     // Simulate ClerkUI becoming available after 250ms
     setTimeout(() => {
-      (window as any).__internal_ClerkUiCtor = mockClerkUi;
+      (window as any).__internal_ClerkUICtor = mockClerkUi;
     }, 250);
 
     // Advance timers to allow polling to detect ClerkUI
@@ -369,23 +369,23 @@ describe('loadClerkUiScript(options)', () => {
     const loadPromise = loadClerkUiScript({ publishableKey: mockPublishableKey, scriptLoadTimeout: 1000 });
 
     setTimeout(() => {
-      (window as any).__internal_ClerkUiCtor = mockClerkUi;
+      (window as any).__internal_ClerkUICtor = mockClerkUi;
     }, 999);
 
     vi.advanceTimersByTime(1000);
 
     const result = await loadPromise;
     expect(result).toBeNull();
-    expect((window as any).__internal_ClerkUiCtor).toBe(mockClerkUi);
+    expect((window as any).__internal_ClerkUICtor).toBe(mockClerkUi);
   });
 
   test('validates ClerkUI is properly loaded', async () => {
-    (window as any).__internal_ClerkUiCtor = mockClerkUi;
+    (window as any).__internal_ClerkUICtor = mockClerkUi;
 
     const result = await loadClerkUiScript({ publishableKey: mockPublishableKey });
 
     expect(result).toBeNull();
-    expect((window as any).__internal_ClerkUiCtor).toBe(mockClerkUi);
+    expect((window as any).__internal_ClerkUICtor).toBe(mockClerkUi);
   });
 });
 

packages/shared/src/loadClerkJsScript.ts

@@ -43,7 +43,7 @@ export type LoadClerkUiScriptOptions = {
  *
  * @returns `true` if window.Clerk exists and has the expected structure with a load method.
  */
-function isClerkGlobalProperlyLoaded(prop: 'Clerk' | '__internal_ClerkUiCtor'): boolean {
+function isClerkGlobalProperlyLoaded(prop: 'Clerk' | '__internal_ClerkUICtor'): boolean {
   if (typeof window === 'undefined' || !(window as any)[prop]) {
     return false;
   }
@@ -53,7 +53,7 @@ function isClerkGlobalProperlyLoaded(prop: 'Clerk' | '__internal_ClerkUiCtor'):
   return !!val;
 }
 const isClerkProperlyLoaded = () => isClerkGlobalProperlyLoaded('Clerk');
-const isClerkUiProperlyLoaded = () => isClerkGlobalProperlyLoaded('__internal_ClerkUiCtor');
+const isClerkUiProperlyLoaded = () => isClerkGlobalProperlyLoaded('__internal_ClerkUICtor');
 
 /**
  * Checks if an existing script has a request error using Performance API.