fix(clerk-js): Restore backwards compat for legacy clerkUICtor option

[jacekradko]

Summary

• Restores backwards compatibility for the legacy clerkUICtor / clerkUiCtor options that were removed in feat(ui): Add unified ui prop with RSC support via conditional exports #7664
• The #initOptions method now detects legacy option names and converts them to the new ui.ClerkUI format
• Adds test coverage for both legacy option names

Context

The ui prop PR (#7664) changed the clerk-js options API from clerkUICtor (top-level) to ui: { ClerkUI } (nested) and removed the backwards compat shim. Consumers still on older SDK versions (e.g. the dashboard) pass clerkUICtor, which the new clerk-js ignores — causing assertComponentsReady to throw "Clerk was not loaded with Ui components" when mounting any component.

Failing dashboard smoke tests: https://github.com/clerk/dashboard/actions/runs/21809499309

Test plan

• Existing ui.ClerkUI test still passes
• New test: legacy clerkUICtor option initializes ClerkUI
• New test: legacy clerkUiCtor option initializes ClerkUI
• pnpm build --filter @clerk/clerk-js passes
• All 97 clerk.test.ts tests pass

Summary by CodeRabbit

• Bug Fixes

  • Restored backwards compatibility for legacy Clerk UI constructor options so older option names continue to work with the updated UI initialization.

• Tests

  • Added tests verifying legacy UI constructor options invoke the expected initialization path.

• Documentation

  • Added a changeset entry documenting the patch-level compatibility fix.

• Chores

  • Small build size threshold adjustment.

[changeset-bot]

🦋 Changeset detected

Latest commit: 77d6eba

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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 9, 2026 11:43am

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds backwards-compatibility handling for legacy Clerk UI constructor options by mapping clerkUICtor and clerkUiCtor into the new ui.ClerkUI configuration during initialization. Propagates the normalized ui value through returned Clerk options. Adds tests verifying both legacy option variants invoke the provided constructor during load. Also extends allowedRedirectOrigins creation to accept an instanceType parameter.

Possibly related PRs

• PR 7712 (clerk/javascript): Implements the same normalization and support for legacy clerkUICtor/clerkUiCtor variants within the Clerk initialization flow, including corresponding tests.

🚥 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 title accurately summarizes the main change: restoring backwards compatibility for a legacy clerkUICtor option, which aligns with the changeset's primary objective.
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.}

---

No actionable comments were generated in the recent review. 🎉

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 77d6eba