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

.changeset/shiny-owls-dance.md

@@ -0,0 +1,23 @@
+---
+'@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 UI version metadata
+
+The `ui` object from `@clerk/ui` contains version info and the bundled constructor. Each SDK decides whether to use `ui.ctor` based on its support level:
+- Chrome Extension: Uses bundled UI via `ui.ctor`
+- React/Next.js, Vue, Astro: Uses CDN loading
+
+Usage:
+```tsx
+import { ui } from '@clerk/ui';
+
+<ClerkProvider ui={ui}>
+  ...
+</ClerkProvider>
+```

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

@@ -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,12 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ChromeExtensionClerkPr
     return null;
   }
 
+  // Chrome extension uses bundled UI via ui.ctor
   return (
     <ClerkReactProvider
-      {...rest}
+      {...(rest as any)}
       Clerk={clerkInstance}
-      clerkUiCtor={ClerkUi}
+      clerkUiCtor={ui.ctor}
       standardBrowser={!syncHost}
     >
       {children}

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

@@ -1,12 +1,24 @@
 import type { Ui } from './internal';
 import type { Appearance } from './internal/appearance';
 
+import { ClerkUi } from './ClerkUi';
+
 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 object for Clerk UI components.
+ * Pass this to ClerkProvider to use the bundled UI.
+ *
+ * @example
+ * ```tsx
+ * import { ui } from '@clerk/ui';
+ *
+ * <ClerkProvider ui={ui}>
+ *   ...
+ * </ClerkProvider>
+ * ```
  */
 export const ui = {
   version: PACKAGE_VERSION,
+  ctor: ClerkUi,
 } as Ui<Appearance>;

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;