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

[bratsos]

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Added version compatibility validation for @clerk/clerk-js during initialization.
  • Incompatible versions now trigger errors in development mode and warnings in production.

• Tests

  • Added comprehensive test coverage for version compatibility checks.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4e1751d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[vercel]

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

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 29, 2026 3:45pm

[nikosdouvlis]

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.

[bratsos]

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?

[nikosdouvlis]

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).

[bratsos]

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]

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 :)

[bratsos]

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]

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]

📝 Walkthrough

Walkthrough

This pull request introduces minimum ClerkJS SDK version validation in the ClerkUI package. A new isVersionAtLeast function is added to the versionCheck module to compare semantic versions. The ClerkUi constructor now performs runtime version compatibility checks against a minimum required version (5.112.0) defined in constants. Version mismatches trigger a ClerkRuntimeError in development environments and log warnings in production. Supporting test suites validate version checking across various scenarios including pre-release handling, null/undefined inputs, and development vs. production behavior. A minor import reordering adjustment is applied to parseVersionRange.ts.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(ui): enforce minimum clerk-js version compatibility' clearly and concisely describes the main change: adding version compatibility enforcement for clerk-js in the UI package.
Linked Issues check	✅ Passed	The PR implements the minimum clerk-js SDK version check in ClerkUi as specified in USER-4102, with runtime validation in the constructor and environment-specific error/warning handling.
Out of Scope Changes check	✅ Passed	All changes align with the objective of implementing minimum clerk-js version checks: ClerkUi constructor enforcement, shared version utilities, constants, and comprehensive test coverage for the new functionality.
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.}

Tip

🧪 Unit Test Generation v2 is now available!

We have significantly improved our unit test generation capabilities.

To enable: Add this to your .coderabbit.yaml configuration:

reviews:
  finishing_touches:
    unit_tests:
      enabled: true

Try it out by using the @coderabbitai generate unit tests command on your code files or under ✨ Finishing Touches on the walkthrough!

Have feedback? Share your thoughts on our Discord thread!

---

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