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

bratsos · 2026-01-23T19:40:29Z

Add runtime version check in ClerkUi constructor to detect incompatible @clerk/clerk-js versions. In development instances, logs a warning; in production, throws ClerkRuntimeError with actionable upgrade guidance.

Also moves shared version utilities to @clerk/shared/utils.

Description

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Added runtime version compatibility validation for Clerk.js during UI initialization; incompatible versions throw in development and warn in production.
- Added a convenience API to test if a version meets a minimum requirement.
- Introduced a new minimum-supported Clerk.js version constant.
Tests
- Added comprehensive tests for version checks and UI initialization behaviors (dev vs prod, pre-releases, and edge cases).

changeset-bot · 2026-01-23T19:40:34Z

🦋 Changeset detected

Latest commit: 38deb49

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@clerk/shared	Minor
@clerk/ui	Minor
@clerk/react	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-01-23T19:40:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 3, 2026 2:23pm

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

packages/ui/src/constants.ts

@@ -1,3 +1,5 @@
+export const MIN_CLERK_JS_VERSION = '5.112.0';


Is 5.112.0 the correct version here or should this be pinned to 6.0.0 since thats the major for core 3? The tests seem to use 6.0.0 as the expected minimum which made me wonder if this was intentional or if the constant just needs updating.

I think the version when we added ModuleManager/ClerkUi was 5.112.0 so in theory this could be the minimum clerk js version. But we can also arbitrarily set this to 6.0.0 to make it available only on Core3. WDYT?

I updated this to 6.0.0 73ebcb5

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

packages/ui/src/ClerkUi.ts

+        logger.warnOnce(incompatibilityMessage);
+      } else {
+        throw new ClerkRuntimeError(incompatibilityMessage, { code: 'clerk_ui_version_mismatch' });
+      }


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

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

packages/ui/src/ClerkUi.ts

+        `@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.`;
+    }


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:33Z

~~this PR adds a new feature to @clerk/ui and @clerk/shared but I dont see a changeset for it. Should we add one describing the new minimum version check behavior?~~

This is fine

coderabbitai · 2026-01-30T16:41:58Z

📝 Walkthrough

Walkthrough

This pull request adds runtime Clerk.js SDK version validation to ClerkUi: a new constant MIN_CLERK_JS_VERSION ('6.0.0') and an exported isVersionAtLeast function in versionCheck are introduced. ClerkUi's constructor now parses the detected @clerk/clerk-js version and either throws a ClerkRuntimeError in development or logs a warning in production when the version is incompatible or unparseable. Tests were added for the new checks and version comparisons. A minor import reordering was made in packages/react/build-utils/parseVersionRange.ts. A changeset documents package version bumps.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	The linked issue (USER-4102) title indicates the feature scope but lacks specific technical requirements to fully validate implementation completeness.	Review the linked issue details to confirm whether all specified coding requirements have been implemented in this changeset.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(ui): enforce minimum clerk-js version compatibility' clearly and concisely describes the main objective of adding version compatibility checks.
Out of Scope Changes check	✅ Passed	All changes align with the core objective: version checking utilities, isVersionAtLeast function, MIN_CLERK_JS_VERSION constant, runtime checks in ClerkUi, and comprehensive tests are all directly related to enforcing minimum clerk-js version compatibility.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

packages/ui/src/__tests__/ClerkUi.test.ts

Add runtime version check in ClerkUi constructor to detect incompatible @clerk/clerk-js versions. In development instances, logs a warning; in production, throws ClerkRuntimeError with actionable upgrade guidance.

pkg-pr-new · 2026-02-02T20:50:27Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7667

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7667

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7667

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7667

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7667

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7667

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7667

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7667

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7667

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7667

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7667

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7667

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7667

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7667

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7667

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7667

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7667

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7667

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7667

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7667

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7667

commit: 38deb49

…kjs-sdk-version-in-clerkui

github-actions bot added the react label Jan 23, 2026

bratsos force-pushed the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch from f6578d0 to 682ea78 Compare January 23, 2026 20:44

vercel bot deployed to Preview January 23, 2026 20:45 View deployment

Base automatically changed from brkalow/sacramento to main January 23, 2026 21:05

bratsos force-pushed the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch from 682ea78 to a033dda Compare January 26, 2026 17:07

github-actions bot added the core-3 label Jan 26, 2026

vercel bot deployed to Preview January 26, 2026 17:08 View deployment

bratsos force-pushed the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch from a033dda to d1d402b Compare January 26, 2026 17:25

vercel bot deployed to Preview January 26, 2026 17:26 View deployment

nikosdouvlis reviewed Jan 27, 2026

View reviewed changes

vercel bot deployed to Preview January 29, 2026 15:45 View deployment

bratsos marked this pull request as ready for review January 30, 2026 16:35

bratsos requested a review from nikosdouvlis January 30, 2026 17:15

jacekradko reviewed Jan 30, 2026

View reviewed changes

packages/ui/src/__tests__/ClerkUi.test.ts Outdated Show resolved Hide resolved

bratsos added 3 commits February 2, 2026 20:47

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

0569253

Add runtime version check in ClerkUi constructor to detect incompatible @clerk/clerk-js versions. In development instances, logs a warning; in production, throws ClerkRuntimeError with actionable upgrade guidance.

fixup! feat(ui): enforce minimum clerk-js version compatibility

878c600

fixup! feat(ui): enforce minimum clerk-js version compatibility

73ebcb5

bratsos force-pushed the alexbratsos/user-4102-implement-minimum-clerkjs-sdk-version-in-clerkui branch from 4e1751d to 73ebcb5 Compare February 2, 2026 20:47

vercel bot deployed to Preview February 2, 2026 20:47 View deployment

chore: add changeset

f36d483

vercel bot deployed to Preview February 2, 2026 21:34 View deployment

jacekradko approved these changes Feb 2, 2026

View reviewed changes

Merge branch 'main' into alexbratsos/user-4102-implement-minimum-cler…

1b0c42c

…kjs-sdk-version-in-clerkui

vercel bot deployed to Preview February 3, 2026 13:04 View deployment

Merge branch 'main' into alexbratsos/user-4102-implement-minimum-cler…

38deb49

…kjs-sdk-version-in-clerkui

vercel bot deployed to Preview February 3, 2026 14:23 View deployment

		@@ -1,3 +1,5 @@
		export const MIN_CLERK_JS_VERSION = '5.112.0';

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

Conversation

bratsos commented Jan 23, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

bratsos Feb 2, 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!

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 commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

Uh oh!

pkg-pr-new bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bratsos commented Jan 23, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 23, 2026 •

edited

Loading

vercel bot commented Jan 23, 2026 •

edited

Loading

nikosdouvlis commented Jan 27, 2026 •

edited

Loading

coderabbitai bot commented Jan 30, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 2, 2026 •

edited

Loading