feat(react,vue,astro): Add ui prop for version metadata

Adds `ui` prop to ClerkProvider for specifying UI version metadata.
The bundled UI constructor is not used yet (CDN loading continues).

- Add `ui` prop to ClerkProviderProps (version metadata only)
- Keep `ctor` in Ui type for future bundling support
- Chrome extension continues using internal `clerkUiCtor` prop
- Omit `clerkUiCtor` from public ClerkProviderProps type

Author: jacekradko

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

@@ -109,16 +109,11 @@ 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.
  */
 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) {

packages/astro/src/types.ts

@@ -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.ctor`, it will be used instead of loading from CDN.
+     */
+    ui?: TUi;
   };
 
 type AstroClerkCreateInstanceParams<TUi extends Ui = Ui> = AstroClerkIntegrationParams<TUi> & {

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

@@ -34,7 +34,7 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ChromeExtensionClerkPr
 
   return (
     <ClerkReactProvider
-      {...rest}
+      {...(rest as any)}
       Clerk={clerkInstance}
       clerkUiCtor={ClerkUi}
       standardBrowser={!syncHost}

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/types.ts

@@ -36,7 +36,7 @@ declare global {
 /**
  * @interface
  */
-export type ClerkProviderProps<TUi extends Ui = Ui> = Omit<IsomorphicClerkOptions, 'appearance'> & {
+export type ClerkProviderProps<TUi extends Ui = Ui> = Omit<IsomorphicClerkOptions, 'appearance' | 'clerkUiCtor'> & {
   children: React.ReactNode;
   /**
    * Provide an initial state of the Clerk client during server-side rendering. You don't need to set this value yourself unless you're [developing an SDK](https://clerk.com/docs/guides/development/sdk-development/overview).

packages/shared/src/types/clerk.ts

@@ -2436,7 +2436,15 @@ export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
    * This is a structural-only type for the `ui` object that can be passed
    * to Clerk.load() and ClerkProvider
    */
-  ui?: { version: string; url?: string };
+  ui?: {
+    version: string;
+    url?: string;
+    /**
+     * The Clerk UI constructor. When provided, this will be used instead of
+     * loading the UI from CDN. This is useful for bundling the UI with your app.
+     */
+    ctor?: ClerkUiConstructor | Promise<ClerkUiConstructor>;
+  };
 } & MultiDomainAndOrProxy;
 
 export interface LoadedClerk extends Clerk {

packages/ui/src/index.ts

@@ -4,8 +4,17 @@ import type { Appearance } from './internal/appearance';
 declare const PACKAGE_VERSION: string;
 
 /**
- * Default ui object for Clerk UI components
- * Tagged with the internal Appearance type for type-safe appearance prop inference
+ * UI metadata object for Clerk UI components.
+ * Pass this to ClerkProvider to specify which UI version to load.
+ *
+ * @example
+ * ```tsx
+ * import { ui } from '@clerk/ui';
+ *
+ * <ClerkProvider ui={ui}>
+ *   ...
+ * </ClerkProvider>
+ * ```
  */
 export const ui = {
   version: PACKAGE_VERSION,

packages/ui/src/internal/index.ts

@@ -1,3 +1,5 @@
+import type { ClerkUiConstructor } from '@clerk/shared/ui';
+
 import type { Appearance } from './appearance';
 
 export type { ComponentControls, MountComponentRenderer } from '../Components';
@@ -26,6 +28,11 @@ export type Ui<A = any> = Tagged<
   {
     version: string;
     url?: string;
+    /**
+     * The Clerk UI constructor. When provided, this will be used instead of
+     * loading the UI from CDN. This is useful for bundling the UI with your app.
+     */
+    ctor?: ClerkUiConstructor | Promise<ClerkUiConstructor>;
     /**
      * Phantom property for type-level appearance inference
      * This property never exists at runtime

packages/vue/src/plugin.ts

@@ -78,15 +78,13 @@ export const clerkPlugin: Plugin<[PluginOptions]> = {
       void (async () => {
         try {
           const clerkPromise = loadClerkJsScript(options);
-          const clerkUiCtorPromise = pluginOptions.clerkUiCtor
-            ? Promise.resolve(pluginOptions.clerkUiCtor)
-            : (async () => {
-                await loadClerkUiScript(options);
-                if (!window.__internal_ClerkUiCtor) {
-                  throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.');
-                }
-                return window.__internal_ClerkUiCtor;
-              })();
+          const clerkUiCtorPromise = (async () => {
+            await loadClerkUiScript(options);
+            if (!window.__internal_ClerkUiCtor) {
+              throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.');
+            }
+            return window.__internal_ClerkUiCtor;
+          })();
 
           await clerkPromise;