feat(js): expose loaded @clerk/ui version via Clerk.uiVersion (#8931)

Author: jacekradko

.changeset/clerk-ui-version.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/react': minor
+---
+
+Expose the loaded `@clerk/ui` version on the `Clerk` object via a new `uiVersion` property. It returns the version of the prebuilt UI bundle once it has loaded (for example `Clerk.uiVersion` in the browser console), or `undefined` if the UI has not been loaded yet. `@clerk/clerk-js` and `@clerk/ui` are versioned and loaded independently, so `uiVersion` can differ from `Clerk.version`.

.typedoc/__tests__/__snapshots__/clerk-properties.mdx

@@ -17,5 +17,6 @@
 | <a id="session"></a> `session`                     | <code>undefined \| null \| [SignedInSessionResource](/docs/reference/objects/session)</code>         | The currently active `Session`, which is guaranteed to be one of the sessions in `Client.sessions`. If there is no active session, this field will be `null`. If the session is loading, this field will be `undefined`.                                                                                                                 |
 | <a id="status"></a> `status`                       | <code>"error" \| "degraded" \| "loading" \| "ready"</code>                                           | The status of the `Clerk` instance. Possible values are: <ul> <li>`"error"`: Set when hotloading `clerk-js` or `Clerk.load()` failed.</li> <li>`"loading"`: Set during initialization.</li> <li>`"ready"`: Set when Clerk is fully operational.</li> <li>`"degraded"`: Set when Clerk is partially operational.</li> </ul>               |
 | <a id="telemetry"></a> `telemetry`                 | <code>undefined \| \{ isDebug: boolean; isEnabled: boolean; record: void; recordLog: void; \}</code> | [Telemetry](/docs/guides/how-clerk-works/security/clerk-telemetry) configuration.                                                                                                                                                                                                                                                        |
+| <a id="uiversion"></a> `uiVersion`                 | <code>undefined \| string</code>                                                                     | The version of `@clerk/ui` that is currently loaded, or `undefined` if the prebuilt UI has not been loaded yet.                                                                                                                                                                                                                          |
 | <a id="user"></a> `user`                           | <code>undefined \| null \| [UserResource](/docs/reference/objects/user)</code>                       | A shortcut to `Session.user` which holds the currently active `User` object. If the session is `null` or `undefined`, the user field will match.                                                                                                                                                                                         |
 | <a id="version"></a> `version`                     | <code>undefined \| string</code>                                                                     | The Clerk SDK version number.                                                                                                                                                                                                                                                                                                            |

packages/clerk-js/src/core/__tests__/clerk.ui-version.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { Clerk } from '../clerk';
+import { Client, Environment } from '../resources/internal';
+
+vi.mock('../resources/Client');
+vi.mock('../resources/Environment');
+
+vi.mock('../auth/devBrowser', () => ({
+  createDevBrowser: () => ({
+    clear: vi.fn(),
+    setup: vi.fn(),
+    getDevBrowser: vi.fn(() => 'deadbeef'),
+    setDevBrowser: vi.fn(),
+    removeDevBrowser: vi.fn(),
+    refreshCookies: vi.fn(),
+  }),
+}));
+
+Client.getOrCreateInstance = vi.fn().mockImplementation(() => ({ fetch: vi.fn() }));
+Environment.getInstance = vi.fn().mockImplementation(() => ({ fetch: vi.fn(() => Promise.resolve({})) }));
+
+const publishableKey = 'pk_test_Y2xlcmsuYWJjZWYuMTIzNDUuZGV2LmxjbGNsZXJrLmNvbSQ';
+
+describe('Clerk.uiVersion', () => {
+  let clerk: Clerk;
+
+  beforeEach(() => {
+    clerk = new Clerk(publishableKey);
+  });
+
+  afterEach(() => {
+    delete (window as any).__internal_ClerkUICtor;
+    vi.restoreAllMocks();
+  });
+
+  it('exposes the property on the instance', () => {
+    expect('uiVersion' in clerk).toBe(true);
+  });
+
+  it('returns undefined when the @clerk/ui bundle has not loaded', () => {
+    expect((window as any).__internal_ClerkUICtor).toBeUndefined();
+    expect(clerk.uiVersion).toBeUndefined();
+  });
+
+  it('returns the version published by the loaded @clerk/ui constructor', () => {
+    (window as any).__internal_ClerkUICtor = { version: '1.18.1' };
+    expect(clerk.uiVersion).toBe('1.18.1');
+  });
+
+  it('reports a UI version independent of the clerk-js version', () => {
+    (window as any).__internal_ClerkUICtor = { version: '1.18.1' };
+    expect(clerk.uiVersion).not.toBe(clerk.version);
+  });
+});

packages/clerk-js/src/core/clerk.ts

@@ -337,6 +337,14 @@ export class Clerk implements ClerkInterface {
     return Clerk.version;
   }
 
+  get uiVersion(): string | undefined {
+    // `@clerk/ui` publishes its constructor (which carries its package version) on this global when hot-loaded
+    // from the CDN; bundled (no-RHC) builds pass the constructor directly via `options.ui.ClerkUI` instead.
+    const globalCtor = typeof window !== 'undefined' ? window.__internal_ClerkUICtor : undefined;
+    const bundledCtor = this.#options.ui?.ClerkUI;
+    return globalCtor?.version ?? (bundledCtor instanceof Promise ? undefined : bundledCtor?.version);
+  }
+
   set sdkMetadata(metadata: SDKMetadata) {
     Clerk.sdkMetadata = metadata;
   }

packages/react/src/isomorphicClerk.ts

@@ -776,6 +776,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     return this.clerkjs?.version;
   }
 
+  get uiVersion(): string | undefined {
+    return this.clerkjs?.uiVersion;
+  }
+
   get client(): ClientResource | undefined {
     if (this.clerkjs) {
       return this.clerkjs.client;

packages/shared/src/types/clerk.ts

@@ -256,6 +256,11 @@ export interface Clerk {
    */
   version: string | undefined;
 
+  /**
+   * The version of `@clerk/ui` that is currently loaded, or `undefined` if the prebuilt UI has not been loaded yet.
+   */
+  uiVersion: string | undefined;
+
   /**
    * If present, contains information about the SDK that the host application is using.
    * For example, if Clerk is loaded through `@clerk/nextjs`, this would be `{ name: '@clerk/nextjs', version: '1.0.0' }`. You don't need to set this value yourself unless you're [developing an SDK](https://clerk.com/docs/guides/development/sdk-development/overview).