feat(*): Skip loading clerk-ui when headless variants are used #7570

nikosdouvlis · 2026-01-09T11:34:16Z

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

Summary by CodeRabbit

New Features
- Adds a configurable "headless" mode so only the core Clerk script is loaded and the UI script is omitted when enabled across Next.js, Astro, React, and Vue.
Tests
- Added an integration test verifying headless behavior: core Clerk script injected, UI script skipped.
Chores
- Added a small changeset placeholder for the release.

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

changeset-bot · 2026-01-09T11:34:21Z

🦋 Changeset detected

Latest commit: c6a734e

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 · 2026-01-09T11:34:21Z

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

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 29, 2026 2:48pm

pkg-pr-new · 2026-01-09T11:37:25Z

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: c6a734e

coderabbitai · 2026-01-09T11:37:31Z

📝 Walkthrough

Walkthrough

Adds support for a clerkJSVariant value of "headless" across Next.js, Astro, React, and Vue integrations. When clerkJSVariant === 'headless', the Clerk UI constructor is not loaded or returned and the Clerk UI script is omitted, while the core Clerk JS script continues to be produced. Several internal functions and signatures were adjusted to allow undefined when the UI is skipped. An integration test was added to confirm the Clerk JS script is injected and the Clerk UI script is not present in headless mode.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% 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 and concisely summarizes the main change: preventing clerk-ui loading when headless variants are used, which is the primary objective across all modified files.

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

jacekradko

…-ui-if-headless-is-used # Conflicts: # packages/nextjs/src/utils/clerk-script.tsx

nikosdouvlis added 5 commits January 9, 2026 13:15

github-actions bot added nextjs react integration astro vue core-3 labels Jan 9, 2026

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

9d3bbe6

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

dedupe

f643280

nikosdouvlis force-pushed the nikos/dont-load-clerk-ui-if-headless-is-used branch from 294bc54 to f643280 Compare January 12, 2026 13:00

vercel bot deployed to Preview January 12, 2026 13:01 View deployment

octoper approved these changes Jan 13, 2026

View reviewed changes

jacekradko approved these changes Jan 13, 2026

View reviewed changes

jacekradko mentioned this pull request Jan 21, 2026

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

Open

5 tasks

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

cf3cdd2

vercel bot deployed to Preview January 26, 2026 16:12 View deployment

Merge remote-tracking branch 'origin/main' into nikos/dont-load-clerk…

c6a734e

…-ui-if-headless-is-used # Conflicts: # packages/nextjs/src/utils/clerk-script.tsx

vercel bot deployed to Preview January 29, 2026 14:48 View deployment

nikosdouvlis changed the title ~~Skip loading clerk-ui when headless variants are used~~ feat(*): Skip loading clerk-ui when headless variants are used Jan 29, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(*): Skip loading clerk-ui when headless variants are used #7570

feat(*): Skip loading clerk-ui when headless variants are used #7570

nikosdouvlis commented Jan 9, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 9, 2026 •

edited

Loading

Walkthrough

Uh oh!

jacekradko left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat(*): Skip loading clerk-ui when headless variants are used #7570

Are you sure you want to change the base?

feat(*): Skip loading clerk-ui when headless variants are used #7570

Conversation

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

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

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

Uh oh!

Uh oh!

pkg-pr-new bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Walkthrough

Uh oh!

jacekradko left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nikosdouvlis commented Jan 9, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 9, 2026 •

edited

Loading

vercel bot commented Jan 9, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 9, 2026 •

edited

Loading

coderabbitai bot commented Jan 9, 2026 •

edited

Loading