feat(clerk-js): remove headless variant #7629
Conversation
🦋 Changeset detectedLatest commit: 3fb75ce The changes in this PR will be included in the next version bump. This PR includes changesets to release 20 packages
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.
|
jacekradko
changed the title
📝 WalkthroughWalkthroughThis PR removes the headless bundle and its entry points/tests, replaces the 🚥 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://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
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.
@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
Reorder checks so explicit clerkUICtor is used even when prefetchUI is disabled. Previously, setting prefetchUI=false would ignore any custom UI constructor passed via clerkUICtor option.
|
!snapshot |
|
Hey @jacekradko - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260129153510 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/fastify@2.7.0-snapshot.v20260129153510 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260129153510 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260129153510 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260129153510 --save-exact |
| __internal_onAfterSetActive: () => Promise<void> | void; | ||
| // eslint-disable-next-line @typescript-eslint/consistent-type-imports | ||
| __internal_ClerkUiCtor?: import('@clerk/shared/types').ClerkUiConstructor; | ||
| __internal_ClerkUICtor?: import('@clerk/shared/types').ClerkUiConstructor; |
There was a problem hiding this comment.
We need to update the corresponding types
| avoiding race conditions with __clerkSharedModules registration | ||
| (which happens when React code runs @clerk/ui/register). | ||
| The actual execution happens via loadClerkUIScript() in isomorphicClerk. */} | ||
| {shouldPrefetchClerkUI(prefetchUI) && ( |
There was a problem hiding this comment.
I am thinking we should name this prop preloadUI to match the link semantics.. thoughts?
There was a problem hiding this comment.
Even though it currently works like that, I'm not sure if I like exposing this detail into the surface. But yeah, the terms preload and prefetch are loaded (pun intended) now that we use a link tag
bratsos
left a comment
bratsos
left a comment
There was a problem hiding this comment.
I don't really have any feedback, looks really solid! I added 2 minor comments as discussion points. LFG! 🚀
jacekradko
force-pushed
the
jrad/remove-headless-variant
branch
from
fa1f0bc to
3fb75ce
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/vue/src/plugin.ts (1)
81-102: OmitclerkUICtorfromloadOptionswhen it is not provided andprefetchUIis false.When
prefetchUI === falseand no explicit ctor is provided, passingPromise.resolve(undefined)asclerkUICtorcauses a runtime error. Although a Promise is truthy and passes theif (this.#options.clerkUICtor)check in Clerk.js, attempting to instantiateundefinedas a constructor fails. Additionally,Promise<undefined>violates theClerkOptions.clerkUICtortype (which expectsClerkUiConstructor | Promise<ClerkUiConstructor>), forcing an unsafe cast.Suggested fix
- const clerkUICtorPromise = pluginOptions.clerkUICtor - ? Promise.resolve(pluginOptions.clerkUICtor) - : pluginOptions.prefetchUI === false - ? Promise.resolve(undefined) - : (async () => { - await loadClerkUIScript(options); - if (!window.__internal_ClerkUICtor) { - throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.'); - } - return window.__internal_ClerkUICtor; - })(); + const clerkUICtorPromise = + pluginOptions.clerkUICtor + ? Promise.resolve(pluginOptions.clerkUICtor) + : pluginOptions.prefetchUI === false + ? undefined + : (async () => { + await loadClerkUIScript(options); + if (!window.__internal_ClerkUICtor) { + throw new Error('Failed to download latest Clerk UI. Contact support@clerk.com.'); + } + return window.__internal_ClerkUICtor; + })(); ... - const loadOptions = { ...options, clerkUICtor: clerkUICtorPromise } as unknown as ClerkOptions; + const loadOptions = { + ...options, + ...(clerkUICtorPromise ? { clerkUICtor: clerkUICtorPromise } : {}), + } as ClerkOptions;
|
!snapshot |
|
Hey @jacekradko - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260129212211 --save-exact
npm i @clerk/astro@3.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/backend@3.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/chrome-extension@3.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/clerk-js@6.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/dev-cli@1.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/expo@3.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/express@2.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/fastify@2.7.0-snapshot.v20260129212211 --save-exact
npm i @clerk/localizations@4.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/msw@0.0.1-snapshot.v20260129212211 --save-exact
npm i @clerk/nextjs@7.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/nuxt@2.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/react@6.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/react-router@3.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/shared@4.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/testing@2.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/ui@1.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/upgrade@2.0.0-snapshot.v20260129212211 --save-exact
npm i @clerk/vue@2.0.0-snapshot.v20260129212211 --save-exact |
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}- Disable prefetching the UI bundle (UI will still load on-demand when needed)prefetchUIomitted orundefined- Prefetch UI normally (default behavior)shouldPrefetchClerkUIhelper functionclerkJSVariant="headless"toprefetchUI={false}clerkUiCtor→clerkUICtorfor casing consistencyClerkJscasing in favor ofClerkJSfor consistencyloadClerkJsScript→loadClerkJSScriptclerkJsScriptUrl→clerkJSScriptUrlbuildClerkJsScriptAttributes→buildClerkJSScriptAttributessetClerkJsLoadingErrorPackageName→setClerkJSLoadingErrorPackageNameLoadClerkJsScriptOptions→LoadClerkJSScriptOptionsEnvironment Variables
You can disable UI prefetching via environment variable:
NEXT_PUBLIC_CLERK_PREFETCH_UI=falsePUBLIC_CLERK_PREFETCH_UI=falseCLERK_PREFETCH_UI=falseUsage
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
pnpm buildpassesSummary by CodeRabbit
Breaking Changes
New Features
Chores
✏️ Tip: You can customize this high-level summary in your review settings.