refactor clerk/ui, clerk/js and clerk/react to use the shared ClerkUi interface

nikosdouvlis · nikosdouvlis · commit d7841c495947 · 2025-11-07T07:56:11.000+02:00
- also updated Components so that new versions of clerk and environment propagate automatically
diff --git a/packages/clerk-js/src/core/clerk.ts b/packages/clerk-js/src/core/clerk.ts
diff --git a/packages/clerk-js/src/global.d.ts b/packages/clerk-js/src/global.d.ts
@@ -3,28 +3,20 @@ declare module '*.svg' {
   export default value;
 }
 
-declare const __PKG_NAME__: string;
-declare const __PKG_VERSION__: string;
-declare const __DEV__: boolean;
-
-/**
- * Build time feature flags.
- */
-declare const __BUILD_DISABLE_RHC__: string;
-declare const __BUILD_VARIANT_CHANNEL__: boolean;
-declare const __BUILD_VARIANT_CHIPS__: boolean;
-
-interface Window {
-  __unstable__onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
-  __unstable__onAfterSetActive: () => Promise<void> | void;
+declare global {
+  const __PKG_NAME__: string;
+  const __PKG_VERSION__: string;
+  const __DEV__: boolean;
 
   /**
-   * TODO @nikos: implment type
-   * UI components loaded from @clerk/ui browser bundle.
-   * This is injected by the @clerk/ui package and consumed by clerk-js.
+   * Build time feature flags.
    */
-  __unstable_ClerkUi?: {
-    mountComponentRenderer: any;
-    version: string;
-  };
+  const __BUILD_DISABLE_RHC__: string;
+  const __BUILD_VARIANT_CHANNEL__: boolean;
+  const __BUILD_VARIANT_CHIPS__: boolean;
+
+  interface Window {
+    __unstable__onBeforeSetActive: (intent?: 'sign-out') => Promise<void> | void;
+    __unstable__onAfterSetActive: () => Promise<void> | void;
+  }
 }
diff --git a/packages/clerk-js/src/index.browser.ts b/packages/clerk-js/src/index.browser.ts
@@ -5,11 +5,6 @@ import './utils/setWebpackChunkPublicPath';
 
 import { Clerk } from './core/clerk';
 
-// Load UI components from window (injected by @clerk/ui browser bundle)
-if (window.__unstable_ClerkUi) {
-  Clerk.mountComponentRenderer = window.__unstable_ClerkUi.mountComponentRenderer;
-}
-
 const publishableKey =
   document.querySelector('script[data-clerk-publishable-key]')?.getAttribute('data-clerk-publishable-key') ||
   window.__clerk_publishable_key ||
@@ -27,7 +22,6 @@ const domain =
 if (!window.Clerk) {
   window.Clerk = new Clerk(publishableKey, {
     proxyUrl,
-    // @ts-expect-error - domain is not typed
     domain,
   });
 }
diff --git a/packages/clerk-js/src/index.legacy.browser.ts b/packages/clerk-js/src/index.legacy.browser.ts
@@ -7,11 +7,6 @@ import 'regenerator-runtime/runtime';
 
 import { Clerk } from './core/clerk';
 
-// Load UI components from window (injected by @clerk/ui browser bundle)
-if (window.__unstable_ClerkUi) {
-  Clerk.mountComponentRenderer = window.__unstable_ClerkUi.mountComponentRenderer;
-}
-
 const publishableKey =
   document.querySelector('script[data-clerk-publishable-key]')?.getAttribute('data-clerk-publishable-key') ||
   window.__clerk_publishable_key ||
@@ -29,7 +24,6 @@ const domain =
 if (!window.Clerk) {
   window.Clerk = new Clerk(publishableKey, {
     proxyUrl,
-    // @ts-expect-error
     domain,
   });
 }
diff --git a/packages/react/src/isomorphicClerk.ts b/packages/react/src/isomorphicClerk.ts
@@ -54,7 +54,7 @@ import type {
   WaitlistResource,
   Without,
 } from '@clerk/shared/types';
-import type { MountComponentRenderer } from '@clerk/shared/ui';
+import type { ClerkUiConstructor } from '@clerk/shared/ui';
 import { handleValueOrFn } from '@clerk/shared/utils';
 
 import { errorThrower } from './errors/errorThrower';
@@ -82,10 +82,7 @@ const SDK_METADATA = {
 
 export interface Global {
   Clerk?: HeadlessBrowserClerk | BrowserClerk;
-  __unstable_ClerkUi?: {
-    mountComponentRenderer: MountComponentRenderer;
-    version: string;
-  };
+  __unstable_ClerkUiCtor?: ClerkUiConstructor;
 }
 
 declare const global: Global;
@@ -453,19 +450,18 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     }
 
     try {
-      console.log('yo');
-
       const clerkPromise = this.loadClerkJsEntryChunk();
-      const clerkUiEntry = { resolve: () => this.loadClerkUiEntryChunk().then(a => a.mountComponentRenderer) };
+      const clerkUiCtor = this.loadClerkUiEntryChunk();
       await clerkPromise;
 
       if (!global.Clerk) {
         // TODO @nikos: somehow throw if clerk ui failed to load but it was not headless
         throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
       }
+
       if (!global.Clerk.loaded) {
         this.beforeLoad(global.Clerk);
-        await global.Clerk.load({ ...this.options, clerkUiEntry });
+        await global.Clerk.load({ ...this.options, clerkUiCtor });
       }
       if (global.Clerk.loaded) {
         this.replayInterceptedInvocations(global.Clerk);
@@ -508,10 +504,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
       domain: this.domain,
       nonce: this.options.nonce,
     });
-    if (!global.__unstable_ClerkUi) {
+    if (!global.__unstable_ClerkUiCtor) {
       throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.');
     }
-    return global.__unstable_ClerkUi;
+    return global.__unstable_ClerkUiCtor;
   }
 
   public on: Clerk['on'] = (...args) => {
diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts
@@ -12,13 +12,15 @@ import type {
   TasksRedirectOptions,
   Without,
 } from '@clerk/shared/types';
+import type { ClerkUiConstructor } from '@clerk/shared/ui';
 import type React from 'react';
 
 declare global {
   interface Window {
     __clerk_publishable_key?: string;
     __clerk_proxy_url?: Clerk['proxyUrl'];
     __clerk_domain?: Clerk['domain'];
+    __unstable_ClerkUiCtor?: ClerkUiConstructor;
   }
 }
 
diff --git a/packages/shared/src/loadClerkJsScript.ts b/packages/shared/src/loadClerkJsScript.ts
@@ -42,17 +42,17 @@ export type LoadClerkUiScriptOptions = {
  *
  * @returns `true` if window.Clerk exists and has the expected structure with a load method.
  */
-function isClerkGlobalProperlyLoaded(prop: 'Clerk' | '__unstable_ClerkUi'): boolean {
+function isClerkGlobalProperlyLoaded(prop: 'Clerk' | '__unstable_ClerkUiCtor'): boolean {
   if (typeof window === 'undefined' || !(window as any)[prop]) {
     return false;
   }
 
   // Basic validation that window.Clerk has the expected structure
   const val = (window as any)[prop];
-  return typeof val === 'object' && (val.load ? typeof val.load === 'function' : true);
+  return !!val;
 }
 const isClerkProperlyLoaded = () => isClerkGlobalProperlyLoaded('Clerk');
-const isClerkUiProperlyLoaded = () => isClerkGlobalProperlyLoaded('__unstable_ClerkUi');
+const isClerkUiProperlyLoaded = () => isClerkGlobalProperlyLoaded('__unstable_ClerkUiCtor');
 
 /**
  * Hotloads the Clerk JS script with robust failure detection.
diff --git a/packages/shared/src/types/clerk.ts b/packages/shared/src/types/clerk.ts
@@ -1,4 +1,4 @@
-import type { ClerkUiEntry } from '../ui/types';
+import type { ClerkUiConstructor } from '../ui/types';
 import type { APIKeysNamespace } from './apiKeys';
 import type {
   APIKeysTheme,
@@ -1037,7 +1037,7 @@ export type ClerkOptions = ClerkOptionsNavigation &
     /**
      * Clerk UI entrypoint.
      */
-    clerkUiEntry?: ClerkUiEntry;
+    clerkUiCtor?: Promise<ClerkUiConstructor>;
     /**
      * Optional object to style your components. Will only affect [Clerk Components](https://clerk.com/docs/reference/components/overview) and not [Account Portal](https://clerk.com/docs/guides/customizing-clerk/account-portal) pages.
      */
diff --git a/packages/shared/src/ui/types.ts b/packages/shared/src/ui/types.ts
@@ -1,29 +1,39 @@
-/**
- * UI-related types and utilities
- */
+import type { Appearance, Clerk, ClerkOptions, EnvironmentResource } from '../types';
 
-// Placeholder - Add UI-specific types and utilities here
 export type UIVersion = string;
 
-// TODO: replace with a proper interface
-export type MountComponentRenderer = (
-  clerk: any,
-  environment: any,
-  options: any,
-) => {
-  ensureMounted: (options?: { preloadHint?: string }) => Promise<{
-    mountImpersonationFab: () => void;
-    updateProps: (props: any) => void;
-    openModal: (name: string, props: any) => void;
-    closeModal: (name: string) => void;
-    openDrawer: (name: string, props: any) => void;
-    closeDrawer: (name: string) => void;
-    mountComponent: (config: any) => void;
-    unmountComponent: (config: any) => void;
-    prefetch: (name: string) => void;
-  }>;
+export type ComponentControls = {
+  mountComponent: (params: { appearanceKey: string; name: string; node: HTMLDivElement; props?: any }) => void;
+  unmountComponent: (params: { node: HTMLDivElement }) => void;
+  updateProps: (params: {
+    appearance?: Appearance | undefined;
+    options?: ClerkOptions | undefined;
+    node?: HTMLDivElement;
+    props?: unknown;
+  }) => void;
+  openModal: (modal: string, props?: any) => void;
+  closeModal: (modal: string, options?: { notify?: boolean }) => void;
+  openDrawer: (drawer: string, props?: any) => void;
+  closeDrawer: (drawer: string, options?: { notify?: boolean }) => void;
+  prefetch: (component: 'organizationSwitcher') => void;
+  mountImpersonationFab: () => void;
 };
 
-export interface ClerkUiEntry {
-  resolve: () => Promise<MountComponentRenderer>;
+// Instance shape that the class will implement
+export interface ClerkUiInstance {
+  version: string;
+  ensureMounted: (opts?: { preloadHint?: string }) => Promise<ComponentControls>;
 }
+
+// Constructor type
+export interface ClerkUiConstructor {
+  new (
+    getClerk: () => Clerk,
+    getEnvironment: () => EnvironmentResource | null | undefined,
+    options: ClerkOptions,
+    importModule: (module: string) => Promise<any>,
+  ): ClerkUiInstance;
+  version: string;
+}
+
+export type ClerkUi = ClerkUiInstance;
diff --git a/packages/ui/src/ClerkUi.ts b/packages/ui/src/ClerkUi.ts
@@ -0,0 +1,24 @@
+import type { Clerk, ClerkOptions, EnvironmentResource } from '@clerk/shared/types';
+import type { ClerkUiInstance, ComponentControls as SharedComponentControls } from '@clerk/shared/ui';
+
+import { type MountComponentRenderer, mountComponentRenderer } from './Components';
+
+export class ClerkUi implements ClerkUiInstance {
+  static version = __PKG_VERSION__;
+  version = __PKG_VERSION__;
+
+  #componentRenderer: ReturnType<MountComponentRenderer>;
+
+  constructor(
+    getClerk: () => Clerk,
+    getEnvironment: () => EnvironmentResource | null | undefined,
+    options: ClerkOptions,
+    _importModule: (module: string) => Promise<any>,
+  ) {
+    this.#componentRenderer = mountComponentRenderer(getClerk, getEnvironment, options);
+  }
+
+  ensureMounted(opts?: { preloadHint?: string }): Promise<SharedComponentControls> {
+    return this.#componentRenderer.ensureMounted(opts as unknown as any) as Promise<SharedComponentControls>;
+  }
+}
diff --git a/packages/ui/src/Components.tsx b/packages/ui/src/Components.tsx
@@ -50,12 +50,15 @@ import { buildVirtualRouterUrl } from './utils/buildVirtualRouterUrl';
 import { disambiguateRedirectOptions } from './utils/disambiguateRedirectOptions';
 import { extractCssLayerNameFromAppearance } from './utils/extractCssLayerNameFromAppearance';
 
+// Re-export for ClerkUi
+export { extractCssLayerNameFromAppearance };
+
 /**
  * Avoid importing from `@clerk/shared/react` to prevent extra dependencies being added to the bundle.
  */
 const useSafeLayoutEffect = typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
 
-const ROOT_ELEMENT_ID = 'clerk-components';
+export const ROOT_ELEMENT_ID = 'clerk-components';
 
 export type ComponentControls = {
   mountComponent: (params: {
@@ -138,8 +141,8 @@ interface HtmlNodeOptions {
 }
 
 interface ComponentsProps {
-  clerk: Clerk;
-  environment: EnvironmentResource;
+  getClerk: () => Clerk;
+  getEnvironment: () => EnvironmentResource | null | undefined;
   options: ClerkOptions;
   onComponentsMounted: () => void;
 }
@@ -181,7 +184,11 @@ function assertDOMElement(element: HTMLElement): asserts element {
   }
 }
 
-export const mountComponentRenderer = (clerk: Clerk, environment: EnvironmentResource, _options: ClerkOptions) => {
+export const mountComponentRenderer = (
+  getClerk: () => Clerk,
+  getEnvironment: () => EnvironmentResource | null | undefined,
+  _options: ClerkOptions,
+) => {
   const options = { ..._options };
   // Extract cssLayerName from baseTheme if present and move it to appearance level
   if (options.appearance) {
@@ -215,8 +222,8 @@ export const mountComponentRenderer = (clerk: Clerk, environment: EnvironmentRes
         componentsControlsResolver = import('./lazyModules/common').then(({ createRoot }) => {
           createRoot(clerkRoot).render(
             <Components
-              clerk={clerk}
-              environment={environment}
+              getClerk={getClerk}
+              getEnvironment={getEnvironment}
               options={options}
               onComponentsMounted={deferredPromise.resolve}
             />,
@@ -568,8 +575,8 @@ const Components = (props: ComponentsProps) => {
   return (
     <Suspense fallback={''}>
       <LazyProviders
-        clerk={props.clerk}
-        environment={props.environment}
+        clerk={props.getClerk()}
+        environment={props.getEnvironment()}
         options={state.options}
       >
         {[...nodes].map(([node, component]) => {
diff --git a/packages/ui/src/Components1.tsx b/packages/ui/src/Components1.tsx
diff --git a/packages/ui/src/global.d.ts b/packages/ui/src/global.d.ts
diff --git a/packages/ui/src/index.browser.ts b/packages/ui/src/index.browser.ts

Original file line number	Diff line number	Diff line change
`@@ -12,13 +12,15 @@ import type {`
`12`	`12`	`TasksRedirectOptions,`
`13`	`13`	`Without,`
`14`	`14`	`} from '@clerk/shared/types';`
	`15`	`+import type { ClerkUiConstructor } from '@clerk/shared/ui';`
`15`	`16`	`import type React from 'react';`
`16`	`17`
`17`	`18`	`declare global {`
`18`	`19`	`interface Window {`
`19`	`20`	`__clerk_publishable_key?: string;`
`20`	`21`	`__clerk_proxy_url?: Clerk['proxyUrl'];`
`21`	`22`	`__clerk_domain?: Clerk['domain'];`
	`23`	`+ __unstable_ClerkUiCtor?: ClerkUiConstructor;`
`22`	`24`	`}`
`23`	`25`	`}`
`24`	`26`
Original file line number	Diff line number	Diff line change
`@@ -42,17 +42,17 @@ export type LoadClerkUiScriptOptions = {`
`42`	`42`	`*`
`43`	`43`	* @returns `true` if window.Clerk exists and has the expected structure with a load method.
`44`	`44`	`*/`
`45`		`-function isClerkGlobalProperlyLoaded(prop: 'Clerk' \| '__unstable_ClerkUi'): boolean {`
	`45`	`+function isClerkGlobalProperlyLoaded(prop: 'Clerk' \| '__unstable_ClerkUiCtor'): boolean {`
`46`	`46`	`if (typeof window === 'undefined' \|\| !(window as any)[prop]) {`
`47`	`47`	`return false;`
`48`	`48`	`}`
`49`	`49`
`50`	`50`	`// Basic validation that window.Clerk has the expected structure`
`51`	`51`	`const val = (window as any)[prop];`
`52`		`- return typeof val === 'object' && (val.load ? typeof val.load === 'function' : true);`
	`52`	`+ return !!val;`
`53`	`53`	`}`
`54`	`54`	`const isClerkProperlyLoaded = () => isClerkGlobalProperlyLoaded('Clerk');`
`55`		`-const isClerkUiProperlyLoaded = () => isClerkGlobalProperlyLoaded('__unstable_ClerkUi');`
	`55`	`+const isClerkUiProperlyLoaded = () => isClerkGlobalProperlyLoaded('__unstable_ClerkUiCtor');`
`56`	`56`
`57`	`57`	`/**`
`58`	`58`	`* Hotloads the Clerk JS script with robust failure detection.`