clerk · jacekradko · Jan 23, 2026 · Jan 23, 2026 · Jan 23, 2026 · Jan 23, 2026
diff --git a/.changeset/shiny-owls-dance.md b/.changeset/shiny-owls-dance.md
@@ -0,0 +1,21 @@
+---
+'@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>
+```
+
+**Migration note**: If you were previously using the internal `clerkUiCtor` prop, migrate to the new `ui` prop by importing `ui` from `@clerk/ui`.
diff --git a/integration/templates/express-vite/src/client/main.ts b/integration/templates/express-vite/src/client/main.ts
@@ -1,13 +1,13 @@
 import { Clerk } from '@clerk/clerk-js';
-import { ClerkUi } from '@clerk/ui/entry';
+import { ClerkUI } from '@clerk/ui/entry';
 
 const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
 
 document.addEventListener('DOMContentLoaded', async function () {
   const clerk = new Clerk(publishableKey);
 
   await clerk.load({
-    clerkUICtor: ClerkUi,
+    ui: { ClerkUI },
   });
 
   if (clerk.isSignedIn) {

diff --git a/integration/tests/next-build.test.ts b/integration/tests/next-build.test.ts
@@ -2,6 +2,7 @@ import { expect, test } from '@playwright/test';
 
 import type { Application } from '../models/application';
 import { appConfigs } from '../presets';
+import { linkPackage } from '../presets/utils';
 
 type RenderingModeTestCase = {
   name: string;
@@ -23,6 +24,69 @@ function getIndicator(buildOutput: string, type: 'Static' | 'Dynamic') {
     .split(' ')[0];
 }
 
+test.describe('next build - bundled UI with react-server condition @nextjs', () => {
+  test.describe.configure({ mode: 'parallel' });
+  let app: Application;
+
+  test.beforeAll(async () => {
+    test.setTimeout(90_000); // Wait for app to be ready
+    app = await appConfigs.next.appRouter
+      .clone()
+      .addDependency('@clerk/ui', linkPackage('ui'))
+      .addFile(
+        'src/app/layout.tsx',
+        () => `import './globals.css';
+import { Inter } from 'next/font/google';
+import { ClerkProvider } from '@clerk/nextjs';
+import { ui } from '@clerk/ui';
+
+const inter = Inter({ subsets: ['latin'] });
+
+export const metadata = {
+  title: 'Create Next App',
+  description: 'Generated by create next app',
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <ClerkProvider ui={ui}>
+      <html lang='en'>
+        <body className={inter.className}>{children}</body>
+      </html>
+    </ClerkProvider>
+  );
+}
+    `,
+      )
+      .commit();
+    await app.setup();
+    await app.withEnv(appConfigs.envs.withEmailCodes);
+    await app.build();
+  });
+
+  test.afterAll(async () => {
+    await app.teardown();
+  });
+
+  test('When ui prop is used in server component layout, builds successfully', () => {
+    // The layout.tsx imports { ui } from "@clerk/ui" and passes ui={ui} to ClerkProvider
+    // This tests the react-server conditional export which provides a server-safe marker
+    // The build should succeed without errors about client-only modules in server components
+    expect(app.buildOutput).not.toMatch(/error/i);
+    expect(app.buildOutput).toContain('Generating static pages');
+  });
+
+  test('Static pages remain static with bundled UI', () => {
+    // Get the static indicator from the build output
+    const staticIndicator = getIndicator(app.buildOutput, 'Static');
+
+    // /_not-found should still be static even with bundled UI
+    const notFoundPageLine = app.buildOutput.split('\n').find(msg => msg.includes('/_not-found'));
+
+    expect(notFoundPageLine).toContain(staticIndicator);
+  });
+});
+
 test.describe('next build - provider as client component @nextjs', () => {
   test.describe.configure({ mode: 'parallel' });
   let app: Application;

diff --git a/packages/astro/package.json b/packages/astro/package.json
@@ -86,7 +86,8 @@
     "lint": "eslint src env.d.ts",
     "lint:attw": "attw --pack . --profile esm-only --ignore-rules internal-resolution-error",
     "lint:publint": "pnpm copy:components && publint",
-    "publish:local": "pnpm yalc push --replace --sig"
+    "publish:local": "pnpm yalc push --replace --sig",
+    "test": "vitest run"
   },
   "dependencies": {
     "@clerk/backend": "workspace:^",

diff --git a/packages/astro/src/env.d.ts b/packages/astro/src/env.d.ts
@@ -6,6 +6,7 @@ interface InternalEnv {
   readonly PUBLIC_CLERK_JS_URL?: string;
   readonly PUBLIC_CLERK_JS_VERSION?: string;
   readonly PUBLIC_CLERK_UI_URL?: string;
+  readonly PUBLIC_CLERK_UI_VERSION?: string;
   readonly PUBLIC_CLERK_PREFETCH_UI?: string;
   readonly CLERK_API_KEY?: string;
   readonly CLERK_API_URL?: string;

diff --git a/packages/astro/src/integration/create-integration.ts b/packages/astro/src/integration/create-integration.ts
@@ -21,6 +21,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
     // These are not provided when the "bundled" integration is used
     const clerkJSUrl = (params as any)?.clerkJSUrl as string | undefined;
     const clerkJSVersion = (params as any)?.clerkJSVersion as string | undefined;
+    const clerkUIVersion = (params as any)?.clerkUIVersion as string | undefined;
     const prefetchUI = (params as any)?.prefetchUI as boolean | undefined;
 
     return {
@@ -57,6 +58,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
                 ...buildEnvVarFromOption(domain, 'PUBLIC_CLERK_DOMAIN'),
                 ...buildEnvVarFromOption(clerkJSUrl, 'PUBLIC_CLERK_JS_URL'),
                 ...buildEnvVarFromOption(clerkJSVersion, 'PUBLIC_CLERK_JS_VERSION'),
+                ...buildEnvVarFromOption(clerkUIVersion, 'PUBLIC_CLERK_UI_VERSION'),
                 ...buildEnvVarFromOption(prefetchUI === false ? 'false' : undefined, 'PUBLIC_CLERK_PREFETCH_UI'),
               },
 
@@ -165,6 +167,7 @@ function createClerkEnvSchema() {
     PUBLIC_CLERK_DOMAIN: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
     PUBLIC_CLERK_JS_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
     PUBLIC_CLERK_JS_VERSION: envField.string({ context: 'client', access: 'public', optional: true }),
+    PUBLIC_CLERK_UI_VERSION: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_PREFETCH_UI: envField.string({ context: 'client', access: 'public', optional: true }),
     PUBLIC_CLERK_UI_URL: envField.string({ context: 'client', access: 'public', optional: true, url: true }),
     PUBLIC_CLERK_TELEMETRY_DISABLED: envField.boolean({ context: 'client', access: 'public', optional: true }),

diff --git a/packages/astro/src/internal/__tests__/create-clerk-instance.test.ts b/packages/astro/src/internal/__tests__/create-clerk-instance.test.ts
@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mockLoadClerkUIScript = vi.fn();
+const mockLoadClerkJSScript = vi.fn();
+
+vi.mock('@clerk/shared/loadClerkJsScript', () => ({
+  loadClerkJSScript: (...args: unknown[]) => mockLoadClerkJSScript(...args),
+  loadClerkUIScript: (...args: unknown[]) => mockLoadClerkUIScript(...args),
+  setClerkJSLoadingErrorPackageName: vi.fn(),
+}));
+
+// Mock nanostores
+vi.mock('../../stores/external', () => ({
+  $clerkStore: { notify: vi.fn() },
+}));
+
+vi.mock('../../stores/internal', () => ({
+  $clerk: { get: vi.fn(), set: vi.fn() },
+  $csrState: { setKey: vi.fn() },
+}));
+
+vi.mock('../invoke-clerk-astro-js-functions', () => ({
+  invokeClerkAstroJSFunctions: vi.fn(),
+}));
+
+vi.mock('../mount-clerk-astro-js-components', () => ({
+  mountAllClerkAstroJSComponents: vi.fn(),
+}));
+
+const mockClerkUICtor = vi.fn();
+
+describe('getClerkUIEntryChunk', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.resetModules();
+    (window as any).__internal_ClerkUICtor = undefined;
+    (window as any).Clerk = undefined;
+  });
+
+  afterEach(() => {
+    (window as any).__internal_ClerkUICtor = undefined;
+    (window as any).Clerk = undefined;
+  });
+
+  it('preserves clerkUIUrl from options', async () => {
+    mockLoadClerkUIScript.mockImplementation(async () => {
+      (window as any).__internal_ClerkUICtor = mockClerkUICtor;
+      return null;
+    });
+
+    mockLoadClerkJSScript.mockImplementation(async () => {
+      (window as any).Clerk = {
+        load: vi.fn().mockResolvedValue(undefined),
+        addListener: vi.fn(),
+      };
+      return null;
+    });
+
+    // Dynamically import to get fresh module with mocks
+    const { createClerkInstance } = await import('../create-clerk-instance');
+
+    // Call createClerkInstance with clerkUIUrl
+    await createClerkInstance({
+      publishableKey: 'pk_test_xxx',
+      clerkUIUrl: 'https://custom.selfhosted.example.com/ui.js',
+    });
+
+    expect(mockLoadClerkUIScript).toHaveBeenCalled();
+    const loadClerkUIScriptCall = mockLoadClerkUIScript.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(loadClerkUIScriptCall?.clerkUIUrl).toBe('https://custom.selfhosted.example.com/ui.js');
+  });
+
+  it('does not set clerkUIUrl when not provided', async () => {
+    mockLoadClerkUIScript.mockImplementation(async () => {
+      (window as any).__internal_ClerkUICtor = mockClerkUICtor;
+      return null;
+    });
+
+    mockLoadClerkJSScript.mockImplementation(async () => {
+      (window as any).Clerk = {
+        load: vi.fn().mockResolvedValue(undefined),
+        addListener: vi.fn(),
+      };
+      return null;
+    });
+
+    const { createClerkInstance } = await import('../create-clerk-instance');
+
+    await createClerkInstance({
+      publishableKey: 'pk_test_xxx',
+    });
+
+    expect(mockLoadClerkUIScript).toHaveBeenCalled();
+    const loadClerkUIScriptCall = mockLoadClerkUIScript.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(loadClerkUIScriptCall?.clerkUIUrl).toBeUndefined();
+  });
+});
diff --git a/packages/astro/src/internal/create-clerk-instance.ts b/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,
+    ui: { ...options?.ui, ClerkUI },
   } as unknown as ClerkOptions;
 
   initOptions = clerkOptions;
@@ -115,10 +115,10 @@ async function getClerkJsEntryChunk<TUi extends Ui = Ui>(options?: AstroClerkCre
  */
 async function getClerkUIEntryChunk<TUi extends Ui = Ui>(
   options?: AstroClerkCreateInstanceParams<TUi>,
-): Promise<ClerkUiConstructor | undefined> {
-  // Honor explicit clerkUICtor even when prefetchUI=false
-  if (options?.clerkUICtor) {
-    return options.clerkUICtor;
+): Promise<ClerkUIConstructor | undefined> {
+  // Support bundled UI via ui.ClerkUI prop
+  if (options?.ui?.ClerkUI) {
+    return options.ui.ClerkUI;
   }
 
   if (options?.prefetchUI === false) {

diff --git a/packages/astro/src/internal/create-injection-script-runner.ts b/packages/astro/src/internal/create-injection-script-runner.ts
@@ -22,7 +22,9 @@ function createInjectionScriptRunner(creator: CreateClerkInstanceInternalFn) {
       clientSafeVars = JSON.parse(clientSafeVarsContainer.textContent || '{}');
     }
 
-    await creator(mergeEnvVarsWithParams({ ...astroClerkOptions, ...clientSafeVars }));
+    await creator({
+      ...mergeEnvVarsWithParams({ ...astroClerkOptions, ...clientSafeVars }),
+    });
   }
 
   return runner;

diff --git a/packages/astro/src/internal/merge-env-vars-with-params.ts b/packages/astro/src/internal/merge-env-vars-with-params.ts
@@ -36,7 +36,8 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publish
     telemetry: paramTelemetry,
     clerkJSUrl: paramClerkJSUrl,
     clerkJSVersion: paramClerkJSVersion,
-    clerkUIUrl: paramClerkUiUrl,
+    clerkUIUrl: paramClerkUIUrl,
+    clerkUIVersion: paramClerkUIVersion,
     prefetchUI: paramPrefetchUI,
     ...rest
   } = params || {};
@@ -50,7 +51,8 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publish
     publishableKey: paramPublishableKey || import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY || '',
     clerkJSUrl: paramClerkJSUrl || import.meta.env.PUBLIC_CLERK_JS_URL,
     clerkJSVersion: paramClerkJSVersion || import.meta.env.PUBLIC_CLERK_JS_VERSION,
-    clerkUIUrl: paramClerkUiUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
+    clerkUIUrl: paramClerkUIUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
+    clerkUIVersion: paramClerkUIVersion || import.meta.env.PUBLIC_CLERK_UI_VERSION,
     prefetchUI: mergePrefetchUIConfig(paramPrefetchUI),
     telemetry: paramTelemetry || {
       disabled: isTruthy(import.meta.env.PUBLIC_CLERK_TELEMETRY_DISABLED),

diff --git a/packages/astro/src/server/build-clerk-hotload-script.ts b/packages/astro/src/server/build-clerk-hotload-script.ts
@@ -34,8 +34,9 @@ function buildClerkHotloadScript(locals: APIContext['locals']) {
     return clerkJsScript + '\n';
   }
 
-  const clerkUiScriptSrc = clerkUIScriptUrl({
+  const clerkUIScriptSrc = clerkUIScriptUrl({
     clerkUIUrl: env.clerkUIUrl,
+    clerkUIVersion: env.clerkUIVersion,
     domain,
     proxyUrl,
     publishableKey,
@@ -47,14 +48,14 @@ function buildClerkHotloadScript(locals: APIContext['locals']) {
   // registration (which happens when React code runs @clerk/ui/register).
   // When loadClerkUIScript() later adds a <script> tag, the browser uses the
   // cached resource and executes it without re-downloading.
-  const clerkUiPreload = `
+  const clerkUIPreload = `
   <link rel="preload"
-  href="${clerkUiScriptSrc}"
+  href="${clerkUIScriptSrc}"
   as="script"
   crossOrigin="anonymous"
   />`;
 
-  return clerkJsScript + clerkUiPreload + '\n';
+  return clerkJsScript + clerkUIPreload + '\n';
 }
 
 export { buildClerkHotloadScript };
diff --git a/packages/astro/src/server/get-safe-env.ts b/packages/astro/src/server/get-safe-env.ts
@@ -33,6 +33,7 @@ function getSafeEnv(context: ContextOrLocals) {
     clerkJsUrl: getContextEnvVar('PUBLIC_CLERK_JS_URL', context),
     clerkJsVersion: getContextEnvVar('PUBLIC_CLERK_JS_VERSION', context),
     clerkUIUrl: getContextEnvVar('PUBLIC_CLERK_UI_URL', context),
+    clerkUIVersion: getContextEnvVar('PUBLIC_CLERK_UI_VERSION', context),
     prefetchUI: getContextEnvVar('PUBLIC_CLERK_PREFETCH_UI', context) === 'false' ? false : undefined,
     apiVersion: getContextEnvVar('CLERK_API_VERSION', context),
     apiUrl: getContextEnvVar('CLERK_API_URL', context),

diff --git a/packages/astro/src/types.ts b/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'> & {
@@ -35,6 +35,10 @@ type AstroClerkIntegrationParams<TUi extends Ui = Ui> = Without<
      * The URL that `@clerk/ui` should be hot-loaded from.
      */
     clerkUIUrl?: string;
+    /**
+     * The npm version for `@clerk/ui`.
+     */
+    clerkUIVersion?: string;
     /**
      * Controls prefetching of the `@clerk/ui` script.
      * - `false` - Skip prefetching the UI (for custom UIs using Control Components)
@@ -64,7 +68,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;
   }
 }