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

.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>
+```

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:^",

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();
+  });
+});

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;

packages/astro/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./vitest.setup.ts'],
+  },
+});

packages/astro/vitest.setup.ts

@@ -0,0 +1,6 @@
+import { vi } from 'vitest';
+
+import packageJson from './package.json';
+
+vi.stubGlobal('PACKAGE_NAME', packageJson.name);
+vi.stubGlobal('PACKAGE_VERSION', packageJson.version);

packages/react-router/src/client/__tests__/ClerkProvider.test.tsx

@@ -0,0 +1,92 @@
+import { render } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mockClerkProvider = vi.fn(({ children }: { children: React.ReactNode }) => <div>{children}</div>);
+
+vi.mock('@clerk/react', () => ({
+  ClerkProvider: (props: any) => mockClerkProvider(props),
+}));
+
+vi.mock('react-router', () => ({
+  useNavigate: () => vi.fn(),
+  useLocation: () => ({ pathname: '/' }),
+  UNSAFE_DataRouterContext: React.createContext(null),
+}));
+
+vi.mock('../../utils/assert', () => ({
+  assertPublishableKeyInSpaMode: vi.fn(),
+  assertValidClerkState: vi.fn(),
+  isSpaMode: () => true,
+  warnForSsr: vi.fn(),
+}));
+
+describe('ClerkProvider clerkUIUrl prop', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('passes clerkUIUrl prop to the underlying ClerkProvider', async () => {
+    const { ClerkProvider } = await import('../ReactRouterClerkProvider');
+
+    render(
+      <ClerkProvider
+        publishableKey='pk_test_xxx'
+        clerkUIUrl='https://custom.clerk.ui/ui.js'
+      >
+        <div>Test</div>
+      </ClerkProvider>,
+    );
+
+    expect(mockClerkProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        clerkUIUrl: 'https://custom.clerk.ui/ui.js',
+      }),
+    );
+  });
+
+  it('passes clerkUIUrl as undefined when not provided', async () => {
+    const { ClerkProvider } = await import('../ReactRouterClerkProvider');
+
+    render(
+      <ClerkProvider publishableKey='pk_test_xxx'>
+        <div>Test</div>
+      </ClerkProvider>,
+    );
+
+    expect(mockClerkProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        clerkUIUrl: undefined,
+      }),
+    );
+  });
+
+  it('passes clerkUIUrl alongside other props', async () => {
+    const { ClerkProvider } = await import('../ReactRouterClerkProvider');
+
+    render(
+      <ClerkProvider
+        publishableKey='pk_test_xxx'
+        clerkUIUrl='https://custom.clerk.ui/ui.js'
+        clerkJSUrl='https://custom.clerk.js/clerk.js'
+        signInUrl='/sign-in'
+        signUpUrl='/sign-up'
+      >
+        <div>Test</div>
+      </ClerkProvider>,
+    );
+
+    expect(mockClerkProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        clerkUIUrl: 'https://custom.clerk.ui/ui.js',
+        clerkJSUrl: 'https://custom.clerk.js/clerk.js',
+        signInUrl: '/sign-in',
+        signUpUrl: '/sign-up',
+      }),
+    );
+  });
+});

packages/shared/src/ui/types.ts

@@ -30,7 +30,7 @@ export interface ClerkUiInstance {
 }
 
 // Constructor type
-export interface ClerkUiConstructor {
+export interface ClerkUIConstructor {
   new (
     getClerk: () => Clerk,
     getEnvironment: () => EnvironmentResource | null | undefined,
@@ -41,3 +41,6 @@ export interface ClerkUiConstructor {
 }
 
 export type ClerkUi = ClerkUiInstance;
+
+// Alias for compatibility with main branch naming convention
+export type ClerkUiConstructor = ClerkUIConstructor;

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,
+  ClerkUI: ClerkUi,
 } as Ui<Appearance>;