Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
bratsos wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

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

bratsos wants to merge 1 commit into from

Conversation

@bratsos
Copy link
Member

@bratsos bratsos commented Jan 23, 2026 •
edited
Loading

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:

@changeset-bot
Copy link

changeset-bot bot commented Jan 23, 2026 •
edited
Loading

⚠️ No Changeset found

Latest commit: d1d402b

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
Copy link

vercel bot commented Jan 23, 2026 •
edited
Loading

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

Project Deployment Review Updated (UTC)
clerk-js-sandbox Ready Ready Preview, Comment Jan 26, 2026 5:26pm

Request Review

@github-actions github-actions bot added the react label Jan 23, 2026
@bratsos 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
Base automatically changed from brkalow/sacramento to main January 23, 2026 21:05
@bratsos 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
@bratsos
feat(ui): enforce minimum clerk-js version compatibility
d1d402b 
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.
@bratsos 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
nikosdouvlis
nikosdouvlis reviewed Jan 27, 2026
View reviewed changes
packages/ui/src/constants.ts
@@ -1,3 +1,5 @@
export const MIN_CLERK_JS_VERSION = '5.112.0';
Copy link
Member

@nikosdouvlis nikosdouvlis Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

packages/ui/src/ClerkUi.ts
logger.warnOnce(incompatibilityMessage);
} else {
throw new ClerkRuntimeError(incompatibilityMessage, { code: 'clerk_ui_version_mismatch' });
}
Copy link
Member

@nikosdouvlis nikosdouvlis Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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.`;
}
Copy link
Member

@nikosdouvlis nikosdouvlis Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@nikosdouvlis
Copy link
Member

nikosdouvlis commented Jan 27, 2026 •
edited
Loading

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@nikosdouvlis nikosdouvlis nikosdouvlis left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

core-3 react

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@bratsos @nikosdouvlis