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,19 @@
+---
+'@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>
+```
diff --git a/integration/templates/custom-flows-react-vite/src/main.tsx b/integration/templates/custom-flows-react-vite/src/main.tsx
@@ -15,7 +15,7 @@ createRoot(document.getElementById('root')!).render(
       <div className='flex w-full max-w-sm flex-col gap-6'>
         <ClerkProvider
           clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
-          clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL as string}
+          clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL as string}
           appearance={{
             options: {
               showOptionalFields: true,

diff --git a/integration/templates/expo-web/app/_layout.tsx b/integration/templates/expo-web/app/_layout.tsx
@@ -9,7 +9,7 @@ export default function RootLayout() {
       routerPush={(to: string) => router.push(to)}
       routerReplace={to => router.replace(to)}
       clerkJSUrl={process.env.EXPO_PUBLIC_CLERK_JS_URL}
-      clerkUiUrl={process.env.EXPO_PUBLIC_CLERK_UI_URL}
+      clerkUIUrl={process.env.EXPO_PUBLIC_CLERK_UI_URL}
       appearance={{
         options: {
           showOptionalFields: true,

diff --git a/integration/templates/express-vite/src/client/main.ts b/integration/templates/express-vite/src/client/main.ts
@@ -1,14 +1,12 @@
 import { Clerk } from '@clerk/clerk-js';
-import { ClerkUi } from '@clerk/ui/entry';
+import { ui } from '@clerk/ui';
 
 const publishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;
 
 document.addEventListener('DOMContentLoaded', async function () {
   const clerk = new Clerk(publishableKey);
 
-  await clerk.load({
-    clerkUiCtor: ClerkUi,
-  });
+  await clerk.load({ ui });
 
   if (clerk.isSignedIn) {
     document.getElementById('app')!.innerHTML = `

diff --git a/integration/templates/react-cra/src/index.tsx b/integration/templates/react-cra/src/index.tsx
@@ -10,7 +10,7 @@ root.render(
     <ClerkProvider
       publishableKey={process.env.REACT_APP_CLERK_PUBLISHABLE_KEY as string}
       clerkJSUrl={process.env.REACT_APP_CLERK_JS as string}
-      clerkUiUrl={process.env.REACT_APP_CLERK_UI as string}
+      clerkUIUrl={process.env.REACT_APP_CLERK_UI as string}
       appearance={{
         options: {
           showOptionalFields: true,

diff --git a/integration/templates/react-router-library/src/main.tsx b/integration/templates/react-router-library/src/main.tsx
@@ -15,7 +15,7 @@ createRoot(document.getElementById('root')!).render(
       <ClerkProvider
         publishableKey={PUBLISHABLE_KEY}
         clerkJSUrl={CLERK_JS_URL}
-        clerkUiUrl={CLERK_UI_URL}
+        clerkUIUrl={CLERK_UI_URL}
         appearance={{
           options: {
             showOptionalFields: true,

diff --git a/integration/templates/react-router-node/app/root.tsx b/integration/templates/react-router-node/app/root.tsx
@@ -33,7 +33,7 @@ export default function App({ loaderData }: Route.ComponentProps) {
     <ClerkProvider
       loaderData={loaderData}
       clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL}
-      clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL}
+      clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL}
       appearance={{
         options: {
           showOptionalFields: true,

diff --git a/integration/templates/react-vite/src/main.tsx b/integration/templates/react-vite/src/main.tsx
@@ -29,7 +29,7 @@ const Root = () => {
   return (
     <ClerkProvider
       clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL as string}
-      clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL as string}
+      clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL as string}
       routerPush={(to: string) => navigate(to)}
       routerReplace={(to: string) => navigate(to, { replace: true })}
       appearance={{

diff --git a/integration/templates/tanstack-react-start/src/routes/__root.tsx b/integration/templates/tanstack-react-start/src/routes/__root.tsx
@@ -29,7 +29,7 @@ function RootDocument({ children }: { children: React.ReactNode }) {
       <body>
         <ClerkProvider
           clerkJSUrl={import.meta.env.VITE_CLERK_JS_URL}
-          clerkUiUrl={import.meta.env.VITE_CLERK_UI_URL}
+          clerkUIUrl={import.meta.env.VITE_CLERK_UI_URL}
           appearance={{
             options: {
               showOptionalFields: true,

diff --git a/integration/templates/vue-vite/src/main.ts b/integration/templates/vue-vite/src/main.ts
@@ -8,7 +8,7 @@ const app = createApp(App);
 app.use(clerkPlugin, {
   publishableKey: import.meta.env.VITE_CLERK_PUBLISHABLE_KEY,
   clerkJSUrl: import.meta.env.VITE_CLERK_JS_URL,
-  clerkUiUrl: import.meta.env.VITE_CLERK_UI_URL,
+  clerkUIUrl: import.meta.env.VITE_CLERK_UI_URL,
   clerkJSVersion: import.meta.env.VITE_CLERK_JS_VERSION,
   appearance: {
     options: {

diff --git a/packages/astro/package.json b/packages/astro/package.json
@@ -85,7 +85,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/integration/create-integration.ts b/packages/astro/src/integration/create-integration.ts
@@ -20,7 +20,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 clerkUiUrl = (params as any)?.clerkUiUrl as string | undefined;
+    const clerkUIUrl = (params as any)?.clerkUIUrl as string | undefined;
     const clerkJSVariant = (params as any)?.clerkJSVariant as string | undefined;
     const clerkJSVersion = (params as any)?.clerkJSVersion as string | undefined;
 
@@ -61,7 +61,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
                 ...buildEnvVarFromOption(proxyUrl, 'PUBLIC_CLERK_PROXY_URL'),
                 ...buildEnvVarFromOption(domain, 'PUBLIC_CLERK_DOMAIN'),
                 ...buildEnvVarFromOption(clerkJSUrl, 'PUBLIC_CLERK_JS_URL'),
-                ...buildEnvVarFromOption(clerkUiUrl, 'PUBLIC_CLERK_UI_URL'),
+                ...buildEnvVarFromOption(clerkUIUrl, 'PUBLIC_CLERK_UI_URL'),
                 ...buildEnvVarFromOption(clerkJSVariant, 'PUBLIC_CLERK_JS_VARIANT'),
                 ...buildEnvVarFromOption(clerkJSVersion, 'PUBLIC_CLERK_JS_VERSION'),
               },

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,127 @@
+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 when options.ui.url is 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;
+    });
+
+    // Dynamically import to get fresh module with mocks
+    const { createClerkInstance } = await import('../create-clerk-instance');
+
+    // Call createClerkInstance with clerkUIUrl but without ui.url
+    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('prefers options.ui.url over options.clerkUIUrl when both are 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',
+      clerkUIUrl: 'https://fallback.example.com/ui.js',
+      ui: {
+        version: '1.0.0',
+        url: 'https://preferred.example.com/ui.js',
+      } as any,
+    });
+
+    expect(mockLoadClerkUiScript).toHaveBeenCalled();
+    const loadClerkUiScriptCall = mockLoadClerkUiScript.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(loadClerkUiScriptCall?.clerkUIUrl).toBe('https://preferred.example.com/ui.js');
+  });
+
+  it('does not set clerkUIUrl when neither options.ui.url nor options.clerkUIUrl is 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;
 
@@ -58,8 +58,12 @@ async function createClerkInstanceInternal<TUi extends Ui = Ui>(options?: AstroC
     routerPush: createNavigationHandler(window.history.pushState.bind(window.history)),
     routerReplace: createNavigationHandler(window.history.replaceState.bind(window.history)),
     ...options,
-    // Pass the clerk-ui constructor promise to clerk.load()
-    clerkUiCtor,
+    // Pass the clerk-ui constructor promise inside ui object
+    ui: {
+      version: options?.ui?.version,
+      url: options?.ui?.url,
+      ClerkUI,
+    },
   } as unknown as ClerkOptions;
 
   initOptions = clerkOptions;
@@ -109,23 +113,33 @@ 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, either from bundled UI or by loading from CDN.
  */
 async function getClerkUiEntryChunk<TUi extends Ui = Ui>(
   options?: AstroClerkCreateInstanceParams<TUi>,
-): Promise<ClerkUiConstructor> {
-  if (options?.clerkUiCtor) {
-    return options.clerkUiCtor;
+): Promise<ClerkUIConstructor> {
+  // Use bundled UI constructor if provided via options.ui.ClerkUI
+  const bundledClerkUI = (options?.ui as { ClerkUI?: ClerkUIConstructor })?.ClerkUI;
+  if (bundledClerkUI) {
+    return bundledClerkUI;
   }
 
-  await loadClerkUiScript(options);
-
-  if (!window.__internal_ClerkUiCtor) {
+  // Fall back to loading UI from CDN with version pinning from ui.version
+  await loadClerkUiScript(
+    options
+      ? {
+          ...options,
+          clerkUIVersion: options.ui?.version,
+          clerkUIUrl: options.ui?.url ?? options.clerkUIUrl,
+        }
+      : undefined,
+  );
+
+  if (!window.__internal_ClerkUICtor) {
     throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.');
   }
 
-  return window.__internal_ClerkUiCtor;
+  return window.__internal_ClerkUICtor;
 }
 
 export { createClerkInstance, updateClerkOptions };
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,12 @@ function createInjectionScriptRunner(creator: CreateClerkInstanceInternalFn) {
       clientSafeVars = JSON.parse(clientSafeVarsContainer.textContent || '{}');
     }
 
-    await creator(mergeEnvVarsWithParams({ ...astroClerkOptions, ...clientSafeVars }));
+    // Pass `ui` separately to avoid TypeScript declaration file issues with the
+    // branded Ui type that contains an unexported Tags symbol
+    await creator({
+      ...mergeEnvVarsWithParams({ ...astroClerkOptions, ...clientSafeVars }),
+      ui: astroClerkOptions?.ui,
+    });
   }
 
   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
@@ -15,9 +15,12 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publish
     publishableKey: paramPublishableKey,
     telemetry: paramTelemetry,
     clerkJSUrl: paramClerkJSUrl,
-    clerkUiUrl: paramClerkUiUrl,
+    clerkUIUrl: paramClerkUIUrl,
     clerkJSVariant: paramClerkJSVariant,
     clerkJSVersion: paramClerkJSVersion,
+    // Extract `ui` separately to avoid spreading the branded Ui type which contains
+    // an unexported Tags symbol that breaks TypeScript declaration file generation.
+    ui: _paramUi,
     ...rest
   } = params || {};
 
@@ -28,7 +31,7 @@ const mergeEnvVarsWithParams = (params?: AstroClerkIntegrationParams & { publish
     proxyUrl: paramProxy || import.meta.env.PUBLIC_CLERK_PROXY_URL,
     domain: paramDomain || import.meta.env.PUBLIC_CLERK_DOMAIN,
     publishableKey: paramPublishableKey || import.meta.env.PUBLIC_CLERK_PUBLISHABLE_KEY || '',
-    clerkUiUrl: paramClerkUiUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
+    clerkUIUrl: paramClerkUIUrl || import.meta.env.PUBLIC_CLERK_UI_URL,
     clerkJSUrl: paramClerkJSUrl || import.meta.env.PUBLIC_CLERK_JS_URL,
     clerkJSVariant: paramClerkJSVariant || import.meta.env.PUBLIC_CLERK_JS_VARIANT,
     clerkJSVersion: paramClerkJSVersion || import.meta.env.PUBLIC_CLERK_JS_VERSION,

diff --git a/packages/astro/src/server/build-clerk-hotload-script.ts b/packages/astro/src/server/build-clerk-hotload-script.ts
@@ -19,7 +19,7 @@ function buildClerkHotloadScript(locals: APIContext['locals']) {
     publishableKey,
   });
   const clerkUiScriptSrc = clerkUiScriptUrl({
-    clerkUiUrl: getSafeEnv(locals).clerkUiUrl,
+    clerkUIUrl: getSafeEnv(locals).clerkUIUrl,
     domain,
     proxyUrl,
     publishableKey,

diff --git a/packages/astro/src/server/get-safe-env.ts b/packages/astro/src/server/get-safe-env.ts
@@ -31,7 +31,7 @@ function getSafeEnv(context: ContextOrLocals) {
     signInUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_IN_URL', context),
     signUpUrl: getContextEnvVar('PUBLIC_CLERK_SIGN_UP_URL', context),
     clerkJsUrl: getContextEnvVar('PUBLIC_CLERK_JS_URL', context),
-    clerkUiUrl: getContextEnvVar('PUBLIC_CLERK_UI_URL', context),
+    clerkUIUrl: getContextEnvVar('PUBLIC_CLERK_UI_URL', context),
     clerkJsVariant: getContextEnvVar('PUBLIC_CLERK_JS_VARIANT', context) as 'headless' | '' | undefined,
     clerkJsVersion: getContextEnvVar('PUBLIC_CLERK_JS_VERSION', context),
     apiVersion: getContextEnvVar('CLERK_API_VERSION', context),