feat(clerk-js): remove headless variant #7629

jacekradko · 2026-01-21T04:28:06Z

Summary

Fixes: USER-4231

This PR removes the clerkJSVariant: 'headless' option and replaces it with a new prefetchUI prop that controls whether the @clerk/ui script is prefetched.

Changes

Removed: clerkJSVariant: 'headless' option from all SDK packages
Added: prefetchUI prop (boolean | undefined) to control UI bundle prefetching
- prefetchUI={false} - Disable prefetching the UI bundle (UI will still load on-demand when needed)
- prefetchUI omitted or undefined - Prefetch UI normally (default behavior)
Added: shouldPrefetchClerkUI helper function
Added: Codemod to automatically migrate clerkJSVariant="headless" to prefetchUI={false}
Renamed: clerkUiCtor → clerkUICtor for casing consistency
Deprecated: ClerkJs casing in favor of ClerkJS for consistency
- loadClerkJsScript → loadClerkJSScript
- clerkJsScriptUrl → clerkJSScriptUrl
- buildClerkJsScriptAttributes → buildClerkJSScriptAttributes
- setClerkJsLoadingErrorPackageName → setClerkJSLoadingErrorPackageName
- LoadClerkJsScriptOptions → LoadClerkJSScriptOptions
- Old names are deprecated aliases that will be removed in a future major version

Environment Variables

You can disable UI prefetching via environment variable:

Next.js: NEXT_PUBLIC_CLERK_PREFETCH_UI=false
Astro: PUBLIC_CLERK_PREFETCH_UI=false
React Router / TanStack Start: CLERK_PREFETCH_UI=false

Usage

// Disable UI prefetching (e.g., when using Control Components for custom UI)
<ClerkProvider prefetchUI={false}>
  {children}
</ClerkProvider>

Packages Updated

@clerk/clerk-js (major)
@clerk/shared (major)
@clerk/react
@clerk/nextjs
@clerk/astro
@clerk/nuxt
@clerk/vue
@clerk/react-router
@clerk/tanstack-react-start
@clerk/expo
@clerk/chrome-extension
@clerk/express
@clerk/upgrade (codemod added)

Checklist

Summary by CodeRabbit

Breaking Changes
- Removed clerkJSVariant and the headless bundle; prop names changed (clerkUiUrl → clerkUIUrl, clerkUiCtor → clerkUICtor).
New Features
- Added prefetchUI prop to control UI prefetching (prefetchUI={false} disables).
- Added environment toggles to disable UI prefetching (PUBLIC_CLERK_PREFETCH_UI / CLERK_PREFETCH_UI_DISABLED).
Tests / Docs
- Updated tests, codemod, and upgrade docs to reflect the prop and env changes.

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

why: when using clerkJSVariant='headless', applications only need control components and don't require the full UI bundle. loading the unnecessary @clerk/ui script adds overhead without providing value. what changed: - clerk-script.tsx: conditionally render clerk-ui script tag only when clerkJSVariant !== 'headless' - integration template: read NEXT_PUBLIC_CLERK_JS_VARIANT env var and pass to ClerkProvider users can now set NEXT_PUBLIC_CLERK_JS_VARIANT='headless' to skip loading the ~100KB @clerk/ui bundle when using only control components.

why: when using clerkJSVariant='headless', applications only need control components and don't require the full UI bundle. loading the unnecessary @clerk/ui script adds overhead without providing value. what changed: - build-clerk-hotload-script: skip generating clerk-ui script tag when clerkJsVariant === 'headless' - create-clerk-instance: getClerkUiEntryChunk returns undefined for headless variant to skip client-side hot-loading users can now set clerkJSVariant='headless' to skip loading the ~100KB @clerk/ui bundle when using only control components.

why: when using clerkJSVariant='headless', applications only need control components and don't require the full UI bundle. loading the unnecessary @clerk/ui script adds overhead without providing value. what changed: isomorphicClerk's getClerkUiEntryChunk method now returns undefined when clerkJSVariant === 'headless', skipping the loadClerkUiScript call entirely. users can now set clerkJSVariant='headless' to skip loading the ~100KB @clerk/ui bundle when using only control components.

why: when using clerkJSVariant='headless', applications only need control components and don't require the full UI bundle. loading the unnecessary @clerk/ui script adds overhead without providing value. what changed: clerkPlugin now checks if clerkJSVariant === 'headless' and skips the loadClerkUiScript call, resolving the clerkUiCtorPromise to undefined instead. users can now set clerkJSVariant='headless' to skip loading the ~100KB @clerk/ui bundle when using only control components.

why: verify that the headless variant correctly skips clerk-ui script injection across the full integration stack (env var → prop → script rendering). what changed: created headless-variant.test.ts that sets CLERK_JS_VARIANT='headless' and asserts clerk-ui script is absent while clerk-js script is present.

…ition The headless variant is no longer needed now that UI components have been moved to @clerk/ui. The browser builds are now identical in size. Changes: - Add `react-native` export condition in package.json for Expo/RN - Rename `clerkHeadless` build to `clerkNative` (no chunk splitting) - Remove `clerkHeadlessBrowser` build (identical to regular browser) - Update Expo to import from `@clerk/clerk-js` instead of `/headless` - Deprecate `clerkJSVariant` option (now ignored) - Delete headless source files and export directory BREAKING CHANGE: `@clerk/clerk-js/headless` import path removed. Expo/React Native users should import from `@clerk/clerk-js` directly.

changeset-bot · 2026-01-21T04:28:11Z

🦋 Changeset detected

Latest commit: c2824b6

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

This PR includes changesets to release 20 packages

Name	Type
@clerk/clerk-js	Major
@clerk/shared	Major
@clerk/react	Minor
@clerk/nextjs	Minor
@clerk/astro	Minor
@clerk/nuxt	Minor
@clerk/vue	Minor
@clerk/react-router	Minor
@clerk/tanstack-react-start	Minor
@clerk/expo	Minor
@clerk/chrome-extension	Minor
@clerk/agent-toolkit	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/testing	Patch
@clerk/ui	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-21T04:28:12Z

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

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 23, 2026 4:02pm

….com:clerk/javascript into jrad/remove-headless-variant

clerkJSVariant is still used to control whether @clerk/ui loads. The option just no longer affects the clerk-js URL since the separate headless build has been removed.

Replace the clerkJSVariant: 'headless' pattern with a cleaner ui prop API: - ui: false - Skip loading @clerk/ui (for custom UIs) - ui: { version?, url? } - Load UI with specific version/URL - ui: undefined (default) - Load UI normally Also adds shouldLoadClerkUi() helper function to shared package. Breaking change: clerkJSVariant is removed in favor of ui prop.

…tency

…tions

packages/upgrade/src/versions/core-3/changes/clerk-ui-url-renamed.md

nikosdouvlis

Looking good! Few minor things:

clerkUIVersion in isomorphicClerk.ts

The old code pulled this.options.ui?.version into clerkUiVersion when calling loadClerkUiScript. Now it just spreads this.options, but there's no clerkUIVersion on IsomorphicClerkOptions, so the version never actually makes it to the script URL builder. Was this dead code before, or do we need to add the field?

clerkUiCtor casing

We renamed clerkUiUrl → clerkUIUrl to match clerkJSUrl, but clerkUiCtor still has the old casing. Should probably be clerkUICtor while we're at it

Env var naming

CLERK_PREFETCH_UI_DISABLED=true mapping to prefetchUI: false is a double negation. Can we just use CLERK_PREFETCH_UI=false instead? Same for the framework-prefixed variants (NEXT_PUBLIC_CLERK_PREFETCH_UI, PUBLIC_CLERK_PREFETCH_UI, etc.)

Rename internal functions to use consistent ClerkJS casing: - loadClerkJSScript (deprecated: loadClerkJsScript) - clerkJSScriptUrl (deprecated: clerkJsScriptUrl) - buildClerkJSScriptAttributes (deprecated: buildClerkJsScriptAttributes) - setClerkJSLoadingErrorPackageName (deprecated: setClerkJsLoadingErrorPackageName) - LoadClerkJSScriptOptions (deprecated: LoadClerkJsScriptOptions) Deprecated aliases will be removed in a future major version.

- Fix clerkUIVersion: pass ui.version and ui.url to loadClerkUIScript - Rename clerkUiCtor to clerkUICtor for casing consistency - Change env var from PREFETCH_UI_DISABLED=true to PREFETCH_UI=false (removes double negation for clearer semantics)

jacekradko · 2026-01-23T15:46:37Z

@nikosdouvlis Addressed your feedback. Thanks for going through it!

nikosdouvlis and others added 8 commits January 9, 2026 13:15

Merge branch 'main' into nikos/dont-load-clerk-ui-if-headless-is-used

9d3bbe6

dedupe

f643280

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

vercel bot deployed to Preview January 21, 2026 04:28 View deployment

jacekradko added 2 commits January 21, 2026 06:56

Merge branch 'nikos/dont-load-clerk-ui-if-headless-is-used' of github…

92fe11c

….com:clerk/javascript into jrad/remove-headless-variant

fix: un-deprecate clerkJSVariant, update docs

bb62787

clerkJSVariant is still used to control whether @clerk/ui loads. The option just no longer affects the clerk-js URL since the separate headless build has been removed.

github-actions bot added nextjs react integration astro vue labels Jan 21, 2026

vercel bot deployed to Preview January 21, 2026 12:58 View deployment

github-actions bot added express tanstack react-router nuxt labels Jan 21, 2026

vercel bot deployed to Preview January 21, 2026 13:47 View deployment

jacekradko changed the title ~~[DO NOT MERGE] feat(clerk-js): remove headless variant~~ feat(clerk-js): remove headless variant, add ui prop Jan 21, 2026

Merge branch 'main' into jrad/remove-headless-variant

84c2552

fix: restore clerkUIUrl in express loadClientEnv

a708fb2

vercel bot temporarily deployed to Preview January 23, 2026 13:56 Inactive

fix: rename shouldPrefetchClerkUi to shouldPrefetchClerkUI for consis…

c962cca

…tency

vercel bot deployed to Preview January 23, 2026 13:58 View deployment

jacekradko added 3 commits January 23, 2026 07:58

fix: remove unnecessary 'as any' casts in ReactRouterClerkProvider

9452d48

fix: use inline expression for prefetchUI in react-router env.ts

10f6b15

fix: rename ClerkUi to ClerkUI for consistency in script loading func…

be5c39c

…tions

vercel bot deployed to Preview January 23, 2026 14:01 View deployment

jacekradko commented Jan 23, 2026

View reviewed changes

packages/upgrade/src/versions/core-3/changes/clerk-ui-url-renamed.md Outdated Show resolved Hide resolved

chore: remove unnecessary clerk-ui-url-renamed upgrade doc

3c5f8db

vercel bot temporarily deployed to Preview January 23, 2026 14:06 Inactive

docs: add codemod note to clerkJSVariant removal upgrade doc

4857764

vercel bot temporarily deployed to Preview January 23, 2026 14:12 Inactive

docs: simplify codemod note in upgrade doc

3d619df

vercel bot temporarily deployed to Preview January 23, 2026 14:13 Inactive

fix: remove clerkUiUrl codemod since prop was never released

b295696

vercel bot temporarily deployed to Preview January 23, 2026 14:14 Inactive

nikosdouvlis reviewed Jan 23, 2026

View reviewed changes

chore: remove clerkUiUrl rename from changeset

4bb635b

vercel bot deployed to Preview January 23, 2026 14:46 View deployment

vercel bot deployed to Preview January 23, 2026 15:00 View deployment

docs: clarify prefetchUI behavior in upgrade doc

3dbc51e

vercel bot temporarily deployed to Preview January 23, 2026 15:36 Inactive

vercel bot deployed to Preview January 23, 2026 15:45 View deployment

fix: type errors in isomorphicClerk.ts

c2824b6

vercel bot deployed to Preview January 23, 2026 16:02 View deployment

jacekradko mentioned this pull request Jan 23, 2026

feat(ui,react): Add shared React variant to reduce bundle size #7601

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(clerk-js): remove headless variant #7629

feat(clerk-js): remove headless variant #7629

jacekradko commented Jan 21, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 21, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 21, 2026 •

edited

Loading

Uh oh!

Uh oh!

nikosdouvlis left a comment •

edited

Loading

Uh oh!

jacekradko commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(clerk-js): remove headless variant #7629

Are you sure you want to change the base?

feat(clerk-js): remove headless variant #7629

Conversation

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

Uh oh!

Summary

Changes

Environment Variables

Usage

Packages Updated

Checklist

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 21, 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 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

nikosdouvlis left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacekradko commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jacekradko commented Jan 21, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 21, 2026 •

edited

Loading

vercel bot commented Jan 21, 2026 •

edited

Loading

nikosdouvlis left a comment •

edited

Loading