feat(ui): enforce minimum clerk-js version compatibility #7667

nikosdouvlis · 2026-01-27T11:13:25Z

Looking at clerk-js, it always instantiates ClerkUi with new ModuleManager(), and clerkVersion comes from the Clerk instance which should always have its version set. Is there a scenario where ClerkUi would be instantiated without a moduleManager or without knowing the clerkVersion? If this is just defensive coding thats fine, but if theres an actual use case Im curious what it is :)

It's just defensive to future-proof us from a mistake. I thought about all different scenarios with pinned/hotloaded clerk-js and before/after we introduced moduleManager/ClerkUi and I don't think you land in this case right now, but you never know in the future.

nikosdouvlis · 2026-01-27T11:13:25Z

Should this be the other way around? Typically we want to fail fast in development (so devs catch issues early) but be more lenient in production (to avoid breaking user-facing apps). The current behavior warns in dev (easy to miss) but throws in prod (could cause outages).

Yeah that makes more sense. I went with "You don't want a mismatch on production" as you may end up with weird-looking UI, but I agree. 4e1751d

-Original file line number
+Diff line change
@@ -1,6 +1,5 @@
-    import { coerce } from 'semver';
     import type { VersionBounds } from '@clerk/shared/versionCheck';
+    import { coerce } from 'semver';
     export type { VersionBounds } from '@clerk/shared/versionCheck';
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -1,6 +1,12 @@
     import { describe, expect, it } from 'vitest';
-    import { checkVersionAgainstBounds, isVersionCompatible, parseVersion, type VersionBounds } from '../versionCheck';
+    import {
+      checkVersionAgainstBounds,
+      isVersionAtLeast,
+      isVersionCompatible,
+      parseVersion,
+      type VersionBounds,
+    } from '../versionCheck';
     describe('parseVersion', () => {
       it('parses standard semver versions', () => {
@@ Expand Down Expand Up / @@ -142,3 +148,70 @@ describe('isVersionCompatible', () => { @@
         expect(isVersionCompatible('invalid', bounds)).toBe(false);
       });
     });
+    describe('isVersionAtLeast', () => {
+      describe('returns true when version meets or exceeds minimum', () => {
+        it('exact match', () => {
+          expect(isVersionAtLeast('5.100.0', '5.100.0')).toBe(true);
+        });
+        it('higher patch', () => {
+          expect(isVersionAtLeast('5.100.1', '5.100.0')).toBe(true);
+        });
+        it('higher minor', () => {
+          expect(isVersionAtLeast('5.101.0', '5.100.0')).toBe(true);
+          expect(isVersionAtLeast('5.114.0', '5.100.0')).toBe(true);
+        });
+        it('higher major', () => {
+          expect(isVersionAtLeast('6.0.0', '5.100.0')).toBe(true);
+        });
+      });
+      describe('returns false when version is below minimum', () => {
+        it('lower patch', () => {
+          expect(isVersionAtLeast('5.100.0', '5.100.1')).toBe(false);
+        });
+        it('lower minor', () => {
+          expect(isVersionAtLeast('5.99.0', '5.100.0')).toBe(false);
+          expect(isVersionAtLeast('5.99.999', '5.100.0')).toBe(false);
+        });
+        it('lower major', () => {
+          expect(isVersionAtLeast('4.999.999', '5.100.0')).toBe(false);
+        });
+      });
+      describe('handles pre-release versions', () => {
+        it('treats pre-release as base version', () => {
+          expect(isVersionAtLeast('5.100.0-canary.123', '5.100.0')).toBe(true);
+          expect(isVersionAtLeast('5.114.0-snapshot.456', '5.100.0')).toBe(true);
+        });
+        it('compares base versions ignoring pre-release suffix', () => {
+          expect(isVersionAtLeast('5.99.0-canary.999', '5.100.0')).toBe(false);
+        });
+      });
+      describe('handles edge cases', () => {
+        it('returns false for null/undefined version', () => {
+          expect(isVersionAtLeast(null, '5.100.0')).toBe(false);
+          expect(isVersionAtLeast(undefined, '5.100.0')).toBe(false);
+        });
+        it('returns false for empty string', () => {
+          expect(isVersionAtLeast('', '5.100.0')).toBe(false);
+        });
+        it('returns false for invalid version string', () => {
+          expect(isVersionAtLeast('invalid', '5.100.0')).toBe(false);
+          expect(isVersionAtLeast('5.100', '5.100.0')).toBe(false);
+        });
+        it('returns false if minVersion cannot be parsed', () => {
+          expect(isVersionAtLeast('5.100.0', 'invalid')).toBe(false);
+        });
+      });
+    });

-Original file line number
+Diff line change
@@ Expand Up @@
      * Checks if a parsed version satisfies the given version bounds.
      *
      * @param version - The parsed version to check
+     * @param version.major
      * @param bounds - Array of version bounds to check against
+     * @param version.minor
+     * @param version.patch
      * @returns true if the version satisfies any of the bounds
      */
     export function checkVersionAgainstBounds(
@@ Expand Down Expand Up @@
       }
       return checkVersionAgainstBounds(parsed, bounds);
     }
+    /**
+     * Returns true if the given version is at least the minimum version.
+     * Both versions are compared by their major.minor.patch components only.
+     * Pre-release suffixes are ignored (e.g., "5.114.0-canary.123" is treated as "5.114.0").
+     *
+     * @param version - The version string to check (e.g., "5.114.0")
+     * @param minVersion - The minimum required version (e.g., "5.100.0")
+     * @returns true if version >= minVersion, false otherwise (including if either cannot be parsed)
+     *
+     * @example
+     * isVersionAtLeast("5.114.0", "5.100.0") // true
+     * isVersionAtLeast("5.99.0", "5.100.0") // false
+     * isVersionAtLeast("5.100.0-canary.123", "5.100.0") // true
+     */
+    export function isVersionAtLeast(version: string | undefined | null, minVersion: string): boolean {
+      if (!version) {
+        return false;
+      }
+      const parsed = parseVersion(version);
+      const minParsed = parseVersion(minVersion);
+      if (!parsed || !minParsed) {
+        return false;
+      }
+      if (parsed.major !== minParsed.major) {
+        return parsed.major > minParsed.major;
+      }
+      if (parsed.minor !== minParsed.minor) {
+        return parsed.minor > minParsed.minor;
+      }
+      return parsed.patch >= minParsed.patch;
+    }

-Original file line number
+Diff line change
@@ -1,8 +1,12 @@
+    import { ClerkRuntimeError } from '@clerk/shared/error';
+    import { logger } from '@clerk/shared/logger';
     import type { ModuleManager } from '@clerk/shared/moduleManager';
     import type { Clerk, ClerkOptions, EnvironmentResource } from '@clerk/shared/types';
     import type { ClerkUiInstance, ComponentControls as SharedComponentControls } from '@clerk/shared/ui';
+    import { isVersionAtLeast, parseVersion } from '@clerk/shared/versionCheck';
     import { type MountComponentRenderer, mountComponentRenderer } from './Components';
+    import { MIN_CLERK_JS_VERSION } from './constants';
     export class ClerkUi implements ClerkUiInstance {
       static version = __PKG_VERSION__;
@@ Expand All / @@ -16,6 +20,33 @@ export class ClerkUi implements ClerkUiInstance { @@
         options: ClerkOptions,
         moduleManager: ModuleManager,
       ) {
+        const clerk = getClerk();
+        const clerkVersion = clerk?.version;
+        const isDevelopmentInstance = clerk?.instanceType === 'development';
+        const parsedVersion = parseVersion(clerkVersion ?? '');
+        let incompatibilityMessage: string | null = null;
+        if (parsedVersion && !isVersionAtLeast(clerkVersion, MIN_CLERK_JS_VERSION)) {
+          incompatibilityMessage =
+            `@clerk/ui@${ClerkUi.version} requires @clerk/clerk-js@>=${MIN_CLERK_JS_VERSION}, ` +
+            `but found @clerk/clerk-js@${clerkVersion}. ` +
+            `Please upgrade @clerk/clerk-js (or your framework SDK) to a compatible version.`;
+        } else if (!parsedVersion && !moduleManager) {
+          incompatibilityMessage =
+            `@clerk/ui@${ClerkUi.version} requires @clerk/clerk-js@>=${MIN_CLERK_JS_VERSION}, ` +
+            `but found an incompatible version${clerkVersion ? ` (${clerkVersion})` : ''}. ` +
+            `Please upgrade @clerk/clerk-js (or your framework SDK) to a compatible version.`;
+        }
+        if (incompatibilityMessage) {
+          if (isDevelopmentInstance) {
+            throw new ClerkRuntimeError(incompatibilityMessage, { code: 'clerk_ui_version_mismatch' });
+          } else {
+            logger.warnOnce(incompatibilityMessage);
+          }
+        }
         this.#componentRenderer = mountComponentRenderer(getClerk, getEnvironment, options, moduleManager);
       }
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(ui): enforce minimum clerk-js version compatibility #7667

Diff view

Diff view

There are no files selected for viewing

nikosdouvlis Jan 27, 2026

Uh oh!

bratsos Jan 29, 2026

Uh oh!

nikosdouvlis Jan 27, 2026

Uh oh!

bratsos Jan 29, 2026

Uh oh!

Uh oh!

feat(ui): enforce minimum clerk-js version compatibility #7667

Are you sure you want to change the base?

feat(ui): enforce minimum clerk-js version compatibility #7667

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

nikosdouvlis Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

bratsos Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

bratsos Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!