feat(react,vue,astro): Replace clerkUiCtor prop with ui prop

Refactors the public API so users use `ui={ui}` instead of exposing
`clerkUiCtor` directly. The bundled UI can now be imported from
`@clerk/ui` and passed via the `ui` prop.

- Omit `clerkUiCtor` from public `ClerkProviderProps`
- Add `ctor` property to `Ui` type for bundled constructor
- Convert `ui.ctor` to `clerkUiCtor` internally in providers
- Update Chrome Extension, Vue, and Astro to use new pattern

Author: jacekradko

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

@@ -115,8 +115,10 @@ async function getClerkJsEntryChunk<TUi extends Ui = Ui>(options?: AstroClerkCre
 async function getClerkUiEntryChunk<TUi extends Ui = Ui>(
   options?: AstroClerkCreateInstanceParams<TUi>,
 ): Promise<ClerkUiConstructor> {
-  if (options?.clerkUiCtor) {
-    return options.clerkUiCtor;
+  // Check for ui.ctor first (new API), then fall back to clerkUiCtor (deprecated)
+  const ctorFromUi = options?.ui?.ctor;
+  if (ctorFromUi) {
+    return ctorFromUi;
   }
 
   await loadClerkUiScript(options);

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 as clerkUi } from '@clerk/ui';
 import React from 'react';
 
 import { createClerkClient } from '../internal/clerk';
@@ -36,7 +36,7 @@ export function ClerkProvider<TUi extends Ui = Ui>(props: ChromeExtensionClerkPr
     <ClerkReactProvider
       {...rest}
       Clerk={clerkInstance}
-      clerkUiCtor={ClerkUi}
+      ui={clerkUi as TUi}
       standardBrowser={!syncHost}
     >
       {children}

packages/react/src/contexts/ClerkProvider.tsx

@@ -8,8 +8,16 @@ import { withMaxAllowedInstancesGuard } from '../utils';
 import { ClerkContextProvider } from './ClerkContextProvider';
 
 function ClerkProviderBase<TUi extends Ui>(props: ClerkProviderProps<TUi>) {
-  const { initialState, children, ...restIsomorphicClerkOptions } = props;
-  const isomorphicClerkOptions = restIsomorphicClerkOptions as unknown as IsomorphicClerkOptions;
+  const { initialState, children, ui, ...restIsomorphicClerkOptions } = props;
+
+  // Convert ui prop to internal options
+  const isomorphicClerkOptions = {
+    ...restIsomorphicClerkOptions,
+    // Pass ui metadata for version/url handling
+    ui,
+    // Convert ui.ctor to clerkUiCtor if provided
+    ...(ui?.ctor && { clerkUiCtor: ui.ctor }),
+  } as unknown as IsomorphicClerkOptions;
 
   return (
     <ClerkContextProvider

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,26 @@
 import type { Ui } from './internal';
 import type { Appearance } from './internal/appearance';
 
+import { ClerkUi } from './ClerkUi';
+
 declare const PACKAGE_VERSION: string;
 
+export { ClerkUi };
+
 /**
- * Default ui object for Clerk UI components
- * Tagged with the internal Appearance type for type-safe appearance prop inference
+ * Bundled ui object that includes the Clerk UI constructor.
+ * Use this when you want to bundle the UI with your app instead of loading from CDN.
+ *
+ * @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,8 +78,10 @@ export const clerkPlugin: Plugin<[PluginOptions]> = {
       void (async () => {
         try {
           const clerkPromise = loadClerkJsScript(options);
-          const clerkUiCtorPromise = pluginOptions.clerkUiCtor
-            ? Promise.resolve(pluginOptions.clerkUiCtor)
+          // Check for ui.ctor first (new API), then fall back to clerkUiCtor (deprecated)
+          const ctorFromUi = pluginOptions.ui?.ctor;
+          const clerkUiCtorPromise = ctorFromUi
+            ? Promise.resolve(ctorFromUi)
             : (async () => {
                 await loadClerkUiScript(options);
                 if (!window.__internal_ClerkUiCtor) {