feat(clerk-js): remove headless variant #7629
Open
+332
−270
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 detectedLatest commit: e67dfa5 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen 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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
….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.
jacekradko
changed the title
Contributor
📝 WalkthroughWalkthroughReplaces previous UI variant and per-UI URL configuration with a boolean prefetchUI flag and a new shouldPrefetchClerkUi helper. Removes headless bundle exports and entry points and introduces a clerk.native variant. Adds PUBLIC_CLERK_PREFETCH_UI_DISABLED / CLERK_PREFETCH_UI_DISABLED env flags and gates Clerk UI script prefetching and hotload emission on prefetchUI across integrations and SDKs (Astro, Next.js, Nuxt, React, Vue, Express, React Router, TanStack, Expo, Chrome extension). Updates types/env shapes and tests, including a new Playwright integration test. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://d.iamgay.cn/https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
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 withas anycasts.The
as anycasts on lines 102 and 108 bypass TypeScript's type checking. While this may be a workaround for complex generic constraints withTUi, 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.
Comment on lines
+1
to
+2
| --- | ||
| --- |
Contributor
There was a problem hiding this comment.
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.
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
jacekradko
changed the title
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@packages/astro/src/integration/create-integration.ts`:
- Line 61: The environment variable name used in create-integration (the
buildEnvVarFromOption call passing 'PUBLIC_CLERK_PREFETCH_UI_DISABLED') doesn't
match the schema's name ('PUBLIC_CLERK_UI_DISABLED'); update the code so names
are consistent—either rename the buildEnvVarFromOption argument to
'PUBLIC_CLERK_UI_DISABLED' where used (e.g., the prefetchUI handling in
create-integration) or add 'PUBLIC_CLERK_PREFETCH_UI_DISABLED' to the env schema
(the object that defines import.meta.env entries around the env schema block
referenced near lines 169-171) so the variable has proper typing and Astro env
validation passes. Ensure the same change is applied consistently wherever
PUBLIC_CLERK_UI_DISABLED/PREFETCH_UI_DISABLED appears.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Fixes: USER-4231
This PR removes the
clerkJSVariant: 'headless'option and replaces it with a newprefetchUIprop that controls whether the@clerk/uiscript is prefetched.Changes
clerkJSVariant: 'headless'option from all SDK packagesprefetchUIprop (boolean | undefined) to control UI bundle prefetchingprefetchUI={false}- Skip prefetching the UI bundle (for custom UIs using Control Components)prefetchUIomitted orundefined- Prefetch UI normally (default behavior)shouldLoadClerkUi→shouldPrefetchClerkUihelper functionCLERK_UI_DISABLEDtoCLERK_PREFETCH_UI_DISABLEDUsage
Packages Updated
@clerk/shared@clerk/react@clerk/nextjs@clerk/vue@clerk/astro@clerk/react-router@clerk/tanstack-react-start@clerk/expressChecklist
pnpm buildpassesSummary by CodeRabbit
New Features
Chores
Tests
✏️ Tip: You can customize this high-level summary in your review settings.