feat(clerk-js): remove headless variant #7629
Conversation
🦋 Changeset detectedLatest commit: 95281f7 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
📝 WalkthroughWalkthroughThe PR removes 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
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@integration/templates/next-app-router/src/app/layout.tsx`:
- Line 15: The prefetch toggle currently checks the wrong env var
(`NEXT_PUBLIC_CLERK_PREFETCH_UI_DISABLED`) so documented users won't disable
prefetching; update the prop check in app/layout.tsx for the prefetchUI prop to
read `process.env.NEXT_PUBLIC_CLERK_PREFETCH_UI === 'false' ? false : undefined`
(keeping undefined as the default), referencing the existing prefetchUI prop to
locate and replace the condition.
In `@packages/astro/src/server/build-clerk-hotload-script.ts`:
- Around line 37-42: The Astro hotload script builder is not passing the
extracted PUBLIC_CLERK_UI_VERSION through, so pinned UI versions are ignored;
update getSafeEnv to include clerkUIVersion in its returned object (extracting
PUBLIC_CLERK_UI_VERSION into clerkUIVersion) and then forward that value into
the clerkUIScriptUrl call (the clerkUiScriptSrc creation) by adding
clerkUIVersion to the argument list so clerkUIScriptUrl can select the correct
UI package version.
70808d1 to
66b6ddf
Compare
jacekradko
force-pushed
the
jrad/remove-headless-variant
branch
from
66b6ddf to
5cff9a0
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/clerk-js/rspack.config.js (1)
283-297: AddLimitChunkCountPluginto force the native build into a single chunk.Dynamic imports exist in production code (e.g.,
moduleManager.ts,clerk.ts) which would create separate chunks despitesplitChunks: false. React Native cannot load those additional chunks at runtime. Match the pattern used for other single-bundle variants:Proposed fix
{ output: { publicPath: '', }, + plugins: [ + new rspack.optimize.LimitChunkCountPlugin({ + maxChunks: 1, + }), + ], optimization: { splitChunks: false, }, },
🤖 Fix all issues with AI agents
In `@packages/astro/src/env.d.ts`:
- Around line 8-9: Add the missing PUBLIC_CLERK_UI_VERSION declaration to the
InternalEnv type: update the InternalEnv interface/type (where
PUBLIC_CLERK_UI_URL and PUBLIC_CLERK_PREFETCH_UI are declared) to include a
readonly PUBLIC_CLERK_UI_VERSION?: string; so TypeScript knows this env var
exists and the use in get-safe-env.ts compiles cleanly.
In `@packages/astro/src/server/get-safe-env.ts`:
- Around line 35-37: Add the missing PUBLIC_CLERK_UI_VERSION declaration to the
InternalEnv type in env.d.ts so the usage in get-safe-env.ts (specifically the
clerkUIVersion key and getContextEnvVar('PUBLIC_CLERK_UI_VERSION', context)) has
a matching type; update the InternalEnv interface/type to include
PUBLIC_CLERK_UI_VERSION with the appropriate string (or optional string) type to
resolve the TS2345 build error.
🧹 Nitpick comments (1)
packages/shared/src/loadClerkJsScript.ts (1)
277-280: TODO comment should be addressed.Line 278 contains a TODO comment questioning whether this delegation is needed. This should be resolved before merging or tracked in an issue.
Do you want me to open an issue to track this TODO, or should it be addressed in this PR?
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@packages/react/src/isomorphicClerk.ts`:
- Around line 511-518: The function getClerkUiEntryChunk currently returns
undefined early when shouldPrefetchClerkUI(this.options.prefetchUI) is false, so
any provided this.options.clerkUICtor is ignored; reorder the checks in
getClerkUiEntryChunk so you first return this.options.clerkUICtor if present,
and only consult shouldPrefetchClerkUI afterwards. Apply the same reorder in
create-clerk-instance (the equivalent initialization function there) so a
supplied clerkUICtor is honored even when prefetchUI is false.
♻️ Duplicate comments (2)
packages/astro/src/server/get-safe-env.ts (1)
35-37: EnsurePUBLIC_CLERK_UI_VERSIONis declared inInternalEnv.This concern was raised in a previous review. Line 36 references
'PUBLIC_CLERK_UI_VERSION'which must be added to theInternalEnvtype inpackages/astro/src/env.d.tsto avoid TypeScript errors (TS2345).packages/astro/src/server/build-clerk-hotload-script.ts (1)
37-43: Past review concern addressed.The
clerkUIVersionis now properly forwarded toclerkUIScriptUrlon line 39, resolving the previously flagged issue about pinned UI versions being ignored.
🧹 Nitpick comments (1)
packages/astro/src/server/build-clerk-hotload-script.ts (1)
9-13: Non-null assertions on potentially undefined values.The non-null assertions (
!) onenv.pk,env.proxyUrl, andenv.domaincould cause runtime issues if these environment variables are not configured. WhilepublishableKeyis typically required,proxyUrlanddomainare optional and commonly undefined.Consider removing the non-null assertions for optional values:
Suggested fix
- // eslint-disable-next-line `@typescript-eslint/no-non-null-assertion` - const publishableKey = env.pk!; - // eslint-disable-next-line `@typescript-eslint/no-non-null-assertion` - const proxyUrl = env.proxyUrl!; - // eslint-disable-next-line `@typescript-eslint/no-non-null-assertion` - const domain = env.domain!; + const publishableKey = env.pk ?? ''; + const proxyUrl = env.proxyUrl; + const domain = env.domain;
- Fix CLERK_PREFETCH_UI_DISABLED env var to use CLERK_PREFETCH_UI=false - Add clerkUIVersion to IsomorphicClerkOptions for UI version pinning - Rename __internal_ClerkUiCtor to __internal_ClerkUICtor for consistency
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)
83-107: prefetchUI=false currently ignores an explicitclerkUICtor(custom UI never loads).When
prefetchUIis false, the code forcesclerkUICtorPromiseto resolveundefinedeven ifpluginOptions.clerkUICtoris provided (Line 86-97). That drops a valid UI entrypoint and breaks custom UI setups. The same pattern appears inpackages/astro/src/internal/create-clerk-instance.ts(Line 120-126). Please prioritize the explicitclerkUICtorand only skip network prefetch when it’s absent.🔧 Minimal fix (Vue plugin)
- const clerkUICtorPromise = !shouldPrefetchClerkUI(pluginOptions.prefetchUI) - ? Promise.resolve(undefined) - : pluginOptions.clerkUICtor - ? Promise.resolve(pluginOptions.clerkUICtor) - : (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) + : !shouldPrefetchClerkUI(pluginOptions.prefetchUI) + ? 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; + })();
Fixes race condition where shared UI bundle executes before __clerkSharedModules is registered by @clerk/ui/register. Using <link rel='preload'> pre-fetches the bundle for performance but doesn't execute it immediately. The actual execution happens via loadClerkUIScript() after React code has run.
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 |
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
Tests / Docs
✏️ Tip: You can customize this high-level summary in your review settings.