fix(clerk-js): Support both clerkUICtor and clerkUiCtor for backwards compatibility #7712

jacekradko · 2026-01-30T12:08:42Z

Summary

Adds backwards compatibility for the clerkUiCtor option (lowercase "i") in clerk-js
The correct property name is clerkUICtor (uppercase "UI"), but some SDKs may still be passing the lowercase version
The fix normalizes the option in #initOptions so both casing variants work

Test plan

Verify clerk-js works when SDK passes clerkUICtor
Verify clerk-js works when SDK passes clerkUiCtor

Summary by CodeRabbit

Bug Fixes
- Added backwards compatibility support for Clerk UI constructor configuration, enabling both legacy and current option naming conventions to work seamlessly without requiring configuration changes.

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

… compatibility

changeset-bot · 2026-01-30T12:08:46Z

🦋 Changeset detected

Latest commit: f4ea9e3

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

This PR includes changesets to release 3 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/chrome-extension	Patch
@clerk/expo	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-30T12:08:47Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 30, 2026 0:10am

coderabbitai · 2026-01-30T12:11:35Z

📝 Walkthrough

Walkthrough

This pull request adds backwards compatibility support to the @clerk/clerk-js package. It introduces handling for both clerkUICtor and clerkUiCtor option names during Clerk initialization. The change allows legacy configurations using clerkUiCtor to continue working while normalizing to the clerkUICtor naming convention. A changeset entry documents this update. The modification occurs in the initialization logic without affecting public method signatures or existing call sites.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and accurately summarizes the main change: adding backwards compatibility support for both clerkUICtor and clerkUiCtor option names in clerk-js, which matches the primary objective and changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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.}

pkg-pr-new · 2026-01-30T12:13:28Z

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: f4ea9e3

jacekradko · 2026-01-30T12:14:09Z

!snapshot

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/clerk-js/src/core/clerk.ts`:
- Around line 3250-3259: Add unit tests to cover the backward-compatible alias
behavior introduced in the `#initOptions` function: write tests that instantiate
Clerk (or call Clerk.prototype.#initOptions via a public initialization helper)
passing options with clerkUICtor and separately with the legacy clerkUiCtor and
assert that the resulting configuration uses the same constructor value in
clerkUICtor; include tests for both merging with defaultOptions and for when
only the legacy key is provided to ensure createAllowedRedirectOrigins and other
returned properties are preserved. Ensure tests reference the public
initialization path that exercises `#initOptions` (e.g., new Clerk(...) or init
method) and assert equality of the effective clerkUICtor and other merged
fields.

coderabbitai · 2026-01-30T12:15:40Z

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

  #initOptions = (options?: ClerkOptions): ClerkOptions => {
+    // Support both clerkUICtor (correct) and clerkUiCtor (legacy) for backwards compatibility
+    const clerkUICtor =
+      options?.clerkUICtor ?? (options as Record<string, unknown> | undefined)?.clerkUiCtor ?? undefined;
+
    return {
      ...defaultOptions,
      ...options,
+      clerkUICtor: clerkUICtor as ClerkOptions['clerkUICtor'],
      allowedRedirectOrigins: createAllowedRedirectOrigins(


⚠️ Potential issue | 🟠 Major

Add tests for the legacy alias behavior before merge.

This PR changes initialization to accept both clerkUICtor and clerkUiCtor, but no tests were added to lock in that behavior. Please add coverage for both option names.
As per coding guidelines, “If there are no tests added or modified as part of the PR, please suggest that tests be added to cover the changes.”

🤖 Prompt for AI Agents

In `@packages/clerk-js/src/core/clerk.ts` around lines 3250 - 3259, Add unit tests to cover the backward-compatible alias behavior introduced in the `#initOptions` function: write tests that instantiate Clerk (or call Clerk.prototype.#initOptions via a public initialization helper) passing options with clerkUICtor and separately with the legacy clerkUiCtor and assert that the resulting configuration uses the same constructor value in clerkUICtor; include tests for both merging with defaultOptions and for when only the legacy key is provided to ensure createAllowedRedirectOrigins and other returned properties are preserved. Ensure tests reference the public initialization path that exercises `#initOptions` (e.g., new Clerk(...) or init method) and assert equality of the effective clerkUICtor and other merged fields.

clerk-cookie · 2026-01-30T12:16:35Z

Hey @jacekradko - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.9-snapshot.v20260130121458
@clerk/astro	3.0.0-snapshot.v20260130121458
@clerk/backend	3.0.0-snapshot.v20260130121458
@clerk/chrome-extension	3.0.0-snapshot.v20260130121458
@clerk/clerk-js	6.0.0-snapshot.v20260130121458
@clerk/dev-cli	1.0.0-snapshot.v20260130121458
@clerk/expo	3.0.0-snapshot.v20260130121458
@clerk/expo-passkeys	1.0.0-snapshot.v20260130121458
@clerk/express	2.0.0-snapshot.v20260130121458
@clerk/fastify	2.7.0-snapshot.v20260130121458
@clerk/localizations	4.0.0-snapshot.v20260130121458
@clerk/msw	0.0.1-snapshot.v20260130121458
@clerk/nextjs	7.0.0-snapshot.v20260130121458
@clerk/nuxt	2.0.0-snapshot.v20260130121458
@clerk/react	6.0.0-snapshot.v20260130121458
@clerk/react-router	3.0.0-snapshot.v20260130121458
@clerk/shared	4.0.0-snapshot.v20260130121458
@clerk/tanstack-react-start	1.0.0-snapshot.v20260130121458
@clerk/testing	2.0.0-snapshot.v20260130121458
@clerk/ui	1.0.0-snapshot.v20260130121458
@clerk/upgrade	2.0.0-snapshot.v20260130121458
@clerk/vue	2.0.0-snapshot.v20260130121458

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260130121458 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.0-snapshot.v20260130121458 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.0-snapshot.v20260130121458 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.0-snapshot.v20260130121458 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.0-snapshot.v20260130121458 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@1.0.0-snapshot.v20260130121458 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.0-snapshot.v20260130121458 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260130121458 --save-exact

@clerk/express

npm i @clerk/express@2.0.0-snapshot.v20260130121458 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.7.0-snapshot.v20260130121458 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.0-snapshot.v20260130121458 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.1-snapshot.v20260130121458 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.0-snapshot.v20260130121458 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.0-snapshot.v20260130121458 --save-exact

@clerk/react

npm i @clerk/react@6.0.0-snapshot.v20260130121458 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.0-snapshot.v20260130121458 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.0-snapshot.v20260130121458 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260130121458 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.0-snapshot.v20260130121458 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.0-snapshot.v20260130121458 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.0-snapshot.v20260130121458 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.0-snapshot.v20260130121458 --save-exact

fix(clerk-js): Support both clerkUICtor and clerkUiCtor for backwards…

d0ad49b

… compatibility

github-actions bot added clerk-js core-3 labels Jan 30, 2026

jacekradko requested a review from nikosdouvlis January 30, 2026 12:09

vercel bot deployed to Preview January 30, 2026 12:09 View deployment

chore: add changeset

f4ea9e3

vercel bot deployed to Preview January 30, 2026 12:10 View deployment

coderabbitai bot reviewed Jan 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(clerk-js): Support both clerkUICtor and clerkUiCtor for backwards compatibility #7712

fix(clerk-js): Support both clerkUICtor and clerkUiCtor for backwards compatibility #7712

Uh oh!

jacekradko commented Jan 30, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 30, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 30, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 30, 2026 •

edited

Loading

Walkthrough

Uh oh!

pkg-pr-new bot commented Jan 30, 2026

Uh oh!

jacekradko commented Jan 30, 2026

Uh oh!

coderabbitai bot left a comment

Uh oh!

coderabbitai bot Jan 30, 2026

Uh oh!

clerk-cookie commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fix(clerk-js): Support both clerkUICtor and clerkUiCtor for backwards compatibility #7712

Are you sure you want to change the base?

fix(clerk-js): Support both clerkUICtor and clerkUiCtor for backwards compatibility #7712

Uh oh!

Conversation

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

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 30, 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 30, 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!

pkg-pr-new bot commented Jan 30, 2026

Uh oh!

jacekradko commented Jan 30, 2026

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

clerk-cookie commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jacekradko commented Jan 30, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 30, 2026 •

edited

Loading

vercel bot commented Jan 30, 2026 •

edited

Loading

coderabbitai bot commented Jan 30, 2026 •

edited

Loading