feat(clerk-js): remove headless variant, add ui prop

[jacekradko]

Summary

⚠️ DO NOT MERGE - For review/discussion only

This PR removes the headless build variant from @clerk/clerk-js and introduces a new ui prop to control whether @clerk/ui is loaded.

Background

After the UI split to @clerk/ui, the browser builds are now identical in size:

• clerk.browser.js = 242K
• clerk.headless.browser.js = 242K

The headless build is redundant. A new ui prop provides cleaner control over UI loading.

New ui Prop API

The ui prop replaces clerkJSVariant: 'headless':

// Skip loading @clerk/ui entirely
<ClerkProvider ui={false} />

// Default behavior (load UI normally)
<ClerkProvider />

Changes

Build changes:

• Add react-native export condition in package.json for Expo/RN
• Rename clerkHeadless build → clerkNative (no chunk splitting for RN)
• Remove clerkHeadlessBrowser build (identical to regular browser)
• Update Expo to import from @clerk/clerk-js instead of /headless
• Delete headless source files and export directory

API changes:

• Remove clerkJSVariant prop (was only used for 'headless')
• Add new ui prop to skip loading @clerk/ui when set to false
• Add shouldLoadClerkUi() helper in shared package
• Update all SDK packages: Next.js, Astro, React, Vue, Nuxt, React Router, TanStack Start, Express

Breaking Changes

• @clerk/clerk-js/headless import path removed
• clerkJSVariant prop removed - use ui={false} instead
• Expo/React Native users should import from @clerk/clerk-js directly

Test plan

• Verify Expo builds correctly with the new import
• Verify clerk.native.js is built without chunk splitting
• Verify web apps work without the headless build variant
• Verify ui={false} skips loading clerk-ui

Summary by CodeRabbit

• New Features

  • Flexible ui option to enable/disable Clerk UI and specify UI URL/version
  • Environment variables to control UI behavior (disable, URL, version)
  • React Native "native" build variant

• Deprecations

  • Headless variant removed
  • clerkJSVariant replaced by ui across frameworks

• Tests

  • Added integration and unit tests validating UI-disabled and ui-config behaviors

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

[changeset-bot]

🦋 Changeset detected

Latest commit: b85a057

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

This PR includes changesets to release 0 packages

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

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	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 21, 2026 3:29pm

[coderabbitai]

📝 Walkthrough

Walkthrough

Replaces the clerkJSVariant option with a unified ui option (false | undefined | { url?: string; version?: string }) and introduces environment variables CLERK_UI_DISABLED, CLERK_UI_URL, and CLERK_UI_VERSION. Adds a shouldLoadClerkUi helper to gate UI loading. Removes headless build artifacts and adds a native (React Native) variant in clerk-js. Propagation and handling of the new UI config are updated across integrations (Astro, Next.js, Express, React, Vue, Nuxt, React Router, TanStack, Expo, Chrome extension, and related tooling).

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 38.89% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: removing the headless variant and introducing a ui prop. It is concise, specific, and accurately reflects the core refactoring objective.

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

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In @.changeset/light-eagles-stay.md:
- Around line 1-2: The changeset is empty and must document the breaking changes
introduced: explicitly list affected package names and semver bumps (use major
bumps for breaking changes), describe the removals of clerkJSVariant and the old
import path `@clerk/clerk-js/headless`, and note the new ui prop and its migration
steps; update the changeset body to include a short summary, per-package entries
(e.g., package-name: major), and a brief migration note explaining how to
replace/remove clerkJSVariant, how to update import paths to the new
entrypoints, and how to adopt the new ui prop so consumers can upgrade safely.

In `@packages/expo/src/provider/singleton/createClerkInstance.ts`:
- Around line 1-2: The import path for FapiRequestInit/FapiResponse is invalid;
instead derive request/response types from the public Clerk API: create a
Handler type from Parameters<Clerk["__internal_onBeforeRequest"]>[0], then
extract Req = Parameters<Handler>[0] and use Req as the type for the requestInit
parameter, and similarly extract the response type from
Clerk["__internal_onAfterResponse"] to replace FapiResponse usage; update
function signatures in createClerkInstance.ts to use these derived types
(referencing Clerk, __internal_onBeforeRequest, __internal_onAfterResponse,
Handler, and Req).

🧹 Nitpick comments (1)

packages/react-router/src/client/ReactRouterClerkProvider.tsx (1)

102-109: Type safety concern with as any casts.

The as any casts on lines 102 and 108 bypass TypeScript's type checking. While this may be a workaround for complex generic constraints with TUi, it could mask type mismatches at runtime.

Consider whether these casts can be replaced with more precise type assertions or if the underlying types can be aligned to avoid the need for any.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Empty changeset file - missing package entries and description.

This changeset is empty but the PR introduces breaking changes (removal of clerkJSVariant, @clerk/clerk-js/headless import path, new ui prop). The changeset should document affected packages and their semver bumps.

🤖 Prompt for AI Agents

In @.changeset/light-eagles-stay.md around lines 1 - 2, The changeset is empty
and must document the breaking changes introduced: explicitly list affected
package names and semver bumps (use major bumps for breaking changes), describe
the removals of clerkJSVariant and the old import path `@clerk/clerk-js/headless`,
and note the new ui prop and its migration steps; update the changeset body to
include a short summary, per-package entries (e.g., package-name: major), and a
brief migration note explaining how to replace/remove clerkJSVariant, how to
update import paths to the new entrypoints, and how to adopt the new ui prop so
consumers can upgrade safely.