Skip to content

Conversation

@brkalow
Copy link
Member

@brkalow brkalow commented Jan 15, 2026

Summary

  • Introduces a new ui.shared.browser.js build variant that externalizes React dependencies, allowing the host application's React to be reused instead of bundling a separate copy
  • Adds @clerk/ui/register module to register React on globalThis.__clerkSharedModules for sharing with @clerk/ui
  • Adds clerkUiVariant option to explicitly control which variant to use
  • For @clerk/react users, the shared variant is automatically detected and enabled for compatible React versions
  • Extracts version checking logic into a testable utility with comprehensive unit tests
  • Adds development warnings for configuration fallbacks and React version mismatches

fixes USER-4440

Test plan

  • Unit tests added for version parsing and bounds checking (20 new tests)
  • All existing tests pass (328 total)
  • Build succeeds for @clerk/react package
  • Manual testing: verify bundle size reduction in a sample app using @clerk/react
  • Manual testing: verify fallback to non-shared variant when React version is incompatible

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Shared React variant for @clerk/ui to reduce bundle size by reusing the host app’s React.
    • New public "register" module to let host apps register their React before loading the UI bundle.
    • New configuration option clerkUiVariant ('shared') and automatic auto-selection when host React is compatible.
  • Tests

    • Added comprehensive version-compatibility tests for React detection and range parsing.

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

@changeset-bot
Copy link

changeset-bot bot commented Jan 15, 2026

🦋 Changeset detected

Latest commit: c84b0ef

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

This PR includes changesets to release 20 packages
Name Type
@clerk/ui Minor
@clerk/react Minor
@clerk/shared Patch
@clerk/astro Patch
@clerk/chrome-extension Patch
@clerk/vue Patch
@clerk/expo Patch
@clerk/nextjs Patch
@clerk/react-router Patch
@clerk/tanstack-react-start Patch
@clerk/agent-toolkit Patch
@clerk/backend Patch
@clerk/clerk-js Patch
@clerk/expo-passkeys Patch
@clerk/express Patch
@clerk/fastify Patch
@clerk/localizations Patch
@clerk/msw Patch
@clerk/nuxt Patch
@clerk/testing 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
Copy link

vercel bot commented Jan 15, 2026

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

Project Deployment Review Updated (UTC)
clerk-js-sandbox Ready Ready Preview, Comment Jan 21, 2026 5:01pm

Request Review

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jan 15, 2026

📝 Walkthrough

Walkthrough

Adds a shared React build variant for @clerk that externalizes React into a ui.shared.browser.js bundle and a register entrypoint (@clerk/ui/register) in ESM and CJS which writes host React modules to globalThis.__clerkSharedModules. Adds version utilities (parseVersion, checkVersionAgainstBounds, isVersionCompatible, IS_REACT_SHARED_VARIANT_COMPATIBLE) and build-time exposure of supported React bounds. @clerk/react now auto-selects the shared variant when compatible; IsomorphicClerkOptions and loadClerkJsScript gain clerkUiVariant?: 'shared' | ''. Build configs and package exports updated to produce and expose the shared variant and register module.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and specifically describes the main change: introducing a shared React variant for @clerk/ui and @clerk/react to reduce bundle size.
Linked Issues check ✅ Passed The PR fully implements USER-4440 requirements: detects compatible React versions, registers the host React via @clerk/ui/register for reuse, includes fallback logic for incompatible versions, and reduces bundle size through the shared variant approach.
Out of Scope Changes check ✅ Passed All changes directly support the shared React variant feature: version parsing utilities, registration modules, build configuration updates, and option handling are all in-scope for implementing the feature.
Docstring Coverage ✅ Passed Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.

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

@pkg-pr-new
Copy link

pkg-pr-new bot commented Jan 15, 2026

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: c84b0ef

brkalow and others added 11 commits January 15, 2026 22:54
Introduces a "shared" variant of @clerk/ui that externalizes React
dependencies, allowing the host application's React to be reused
instead of bundling a separate copy.

Changes:
- Add @clerk/ui/register module to register React on globalThis
- Add ui.shared.browser.js build variant with externalized React
- Add React version compatibility checking in @clerk/react
- Add clerkUiVariant option to load the appropriate variant
- Make dev server React externalization conditional via --env shared

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Extract version checking logic into testable utility (versionCheck.ts)
- Add comprehensive unit tests for version parsing and bounds checking
- Move version compatibility check to module level for better performance
- Add dev warning when pnpm-workspace.yaml fallback is used
- Add warning for React version mismatch in register modules
- Remove redundant clerkUiVariant assignment in isomorphicClerk.ts

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The new exports field in clerk-js/package.json blocked deep imports that
expo and chrome-extension packages depended on. This adds:
- ./internal/fapi export for FapiRequestInit/FapiResponse types (expo)
- ./no-rhc export for the no-RHC variant (chrome-extension)

Also updates expo to use the new clean import path.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rename register/index.js to register/index.cjs to fix module syntax
  mismatch (package uses "type": "module" but file was CommonJS)
- Add register/index.d.cts for CJS type declarations to fix
  "Masquerading as ESM" attw error
- Update exports to point to correct file extensions
- Run pnpm dedupe to clean up lockfile

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The new exports field introduces ESM entry points (.mjs) with CJS type
declarations (.d.ts), which triggers attw's "Masquerading as CJS" warning.
This is expected behavior for this package's build setup, so we ignore
the false-cjs rule.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add required curly braces after if conditions in versionCheck.ts and
fix import sorting in index.ts.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Copy link
Member

@bratsos bratsos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't run it locally yet, but I did a deep dive in the code and it looks good! That's a great optimization 🚀

I'll run it locally on Monday if it's not merged yet as a sanity check.

@jacekradko
Copy link
Member

Love it! Are we tracking the routing logic for this variant in the sdk-infra-workers repo?

@brkalow
Copy link
Member Author

brkalow commented Jan 16, 2026

@jacekradko nope, I'll take a look!

@brkalow
Copy link
Member Author

brkalow commented Jan 17, 2026

@jacekradko On second thought, I'm not sure we need additional logic in the proxy...we don't need/want the ability to pin specific domains to this variant necessarily, it's something that's internal to the SDK

@brkalow
Copy link
Member Author

brkalow commented Jan 17, 2026

!snapshot

@clerk-cookie
Copy link
Collaborator

Hey @brkalow - the snapshot version command generated the following package versions:

Package Version
@clerk/agent-toolkit 0.2.9-snapshot.v20260117034135
@clerk/astro 3.0.0-snapshot.v20260117034135
@clerk/backend 3.0.0-snapshot.v20260117034135
@clerk/chrome-extension 3.0.0-snapshot.v20260117034135
@clerk/clerk-js 6.0.0-snapshot.v20260117034135
@clerk/dev-cli 1.0.0-snapshot.v20260117034135
@clerk/expo 3.0.0-snapshot.v20260117034135
@clerk/expo-passkeys 1.0.0-snapshot.v20260117034135
@clerk/express 2.0.0-snapshot.v20260117034135
@clerk/fastify 2.6.9-snapshot.v20260117034135
@clerk/localizations 4.0.0-snapshot.v20260117034135
@clerk/msw 0.0.1-snapshot.v20260117034135
@clerk/nextjs 7.0.0-snapshot.v20260117034135
@clerk/nuxt 2.0.0-snapshot.v20260117034135
@clerk/react 6.0.0-snapshot.v20260117034135
@clerk/react-router 3.0.0-snapshot.v20260117034135
@clerk/shared 4.0.0-snapshot.v20260117034135
@clerk/tanstack-react-start 1.0.0-snapshot.v20260117034135
@clerk/testing 2.0.0-snapshot.v20260117034135
@clerk/ui 1.0.0-snapshot.v20260117034135
@clerk/upgrade 2.0.0-snapshot.v20260117034135
@clerk/vue 2.0.0-snapshot.v20260117034135

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260117034135 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.0-snapshot.v20260117034135 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.0-snapshot.v20260117034135 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.0-snapshot.v20260117034135 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.0-snapshot.v20260117034135 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@1.0.0-snapshot.v20260117034135 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.0-snapshot.v20260117034135 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260117034135 --save-exact

@clerk/express

npm i @clerk/express@2.0.0-snapshot.v20260117034135 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.6.9-snapshot.v20260117034135 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.0-snapshot.v20260117034135 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.1-snapshot.v20260117034135 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.0-snapshot.v20260117034135 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.0-snapshot.v20260117034135 --save-exact

@clerk/react

npm i @clerk/react@6.0.0-snapshot.v20260117034135 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.0-snapshot.v20260117034135 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.0-snapshot.v20260117034135 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260117034135 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.0-snapshot.v20260117034135 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.0-snapshot.v20260117034135 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.0-snapshot.v20260117034135 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.0-snapshot.v20260117034135 --save-exact

@jacekradko
Copy link
Member

@brkalow https://github.com/clerk/sdk-infra-workers/pull/323

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Fix all issues with AI agents
In `@packages/ui/rspack.config.js`:
- Around line 20-36: The externals handler sharedReactExternalsHandler currently
externalizes 'react' and 'react-dom' but misses subpaths like 'react-dom/client'
and 'react-dom/server', so update the function (the sharedReactExternalsHandler
that takes ({ request }, callback)) to also detect requests equal to
'react-dom/client' and 'react-dom/server' and call callback(null,
['__clerkSharedModules', 'react-dom/client'], 'root') and callback(null,
['__clerkSharedModules', 'react-dom/server'], 'root') respectively (keeping the
existing branches for 'react' and 'react-dom' and leaving callback() as the
default).

Externalize react-dom/client in the shared variant and register it
on globalThis.__clerkSharedModules so host apps can share it with
@clerk/ui.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Copy link
Member

@Ephem Ephem left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really nice work here! I tried the current (outdated) snapshot out with the dashboard a bit and it seems to work well.

ui.browser.js in the dash shrank from 36.1kb to 19.4kb which is a nice win. The rabbit might have a point about react-dom/client though, which might possibly move the needle a bit more?

Update: Oh, I had totally missed this was already addressed and Coderabbit just missed picking up on it. Will do a new snapshot and try it out.

@Ephem
Copy link
Member

Ephem commented Jan 21, 2026

!snapshot

@clerk-cookie
Copy link
Collaborator

Hey @Ephem - the snapshot version command generated the following package versions:

Package Version
@clerk/agent-toolkit 0.2.9-snapshot.v20260121133427
@clerk/astro 3.0.0-snapshot.v20260121133427
@clerk/backend 3.0.0-snapshot.v20260121133427
@clerk/chrome-extension 3.0.0-snapshot.v20260121133427
@clerk/clerk-js 6.0.0-snapshot.v20260121133427
@clerk/dev-cli 1.0.0-snapshot.v20260121133427
@clerk/expo 3.0.0-snapshot.v20260121133427
@clerk/expo-passkeys 1.0.0-snapshot.v20260121133427
@clerk/express 2.0.0-snapshot.v20260121133427
@clerk/fastify 2.6.9-snapshot.v20260121133427
@clerk/localizations 4.0.0-snapshot.v20260121133427
@clerk/msw 0.0.1-snapshot.v20260121133427
@clerk/nextjs 7.0.0-snapshot.v20260121133427
@clerk/nuxt 2.0.0-snapshot.v20260121133427
@clerk/react 6.0.0-snapshot.v20260121133427
@clerk/react-router 3.0.0-snapshot.v20260121133427
@clerk/shared 4.0.0-snapshot.v20260121133427
@clerk/tanstack-react-start 1.0.0-snapshot.v20260121133427
@clerk/testing 2.0.0-snapshot.v20260121133427
@clerk/ui 1.0.0-snapshot.v20260121133427
@clerk/upgrade 2.0.0-snapshot.v20260121133427
@clerk/vue 2.0.0-snapshot.v20260121133427

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/agent-toolkit

npm i @clerk/agent-toolkit@0.2.9-snapshot.v20260121133427 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.0-snapshot.v20260121133427 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.0-snapshot.v20260121133427 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.0-snapshot.v20260121133427 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.0-snapshot.v20260121133427 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@1.0.0-snapshot.v20260121133427 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.0-snapshot.v20260121133427 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260121133427 --save-exact

@clerk/express

npm i @clerk/express@2.0.0-snapshot.v20260121133427 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.6.9-snapshot.v20260121133427 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.0-snapshot.v20260121133427 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.1-snapshot.v20260121133427 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.0-snapshot.v20260121133427 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.0-snapshot.v20260121133427 --save-exact

@clerk/react

npm i @clerk/react@6.0.0-snapshot.v20260121133427 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.0-snapshot.v20260121133427 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.0-snapshot.v20260121133427 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260121133427 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.0-snapshot.v20260121133427 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.0-snapshot.v20260121133427 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.0-snapshot.v20260121133427 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.0-snapshot.v20260121133427 --save-exact

@Ephem
Copy link
Member

Ephem commented Jan 21, 2026

Hmm, trying out this very latest snapshot, I'm not seeing any bundle size gains in a local prod build of the dashboard.

Logging React.version gives 19.3.0-canary-f93b9fd4-20251217 which it seems like the checks should match, I tried doing this in a test to verify, and this does indeed pass:

  // This comes from logging it in the build:
  const bounds: VersionBounds[] = [
    [ 18, 0, -1, 0 ],
    [ 19, 0, 0, 3 ],
    [ 19, 1, 1, 4 ],
    [ 19, 2, 2, 3 ],
    [ 19, 3, 3, 0 ]
  ];

  it('returns true for compatible versions', () => {
    expect(isVersionCompatible('19.3.0-canary-f93b9fd4-20251217', bounds)).toBe(true);
  });

Not sure what's going on, I might very well be doing something wrong. 🤔

type VersionBounds = [major: number, minMinor: number, maxMinor: number, minPatch: number];

// Read supported React range from pnpm-workspace.yaml catalogs and parse into bounds
function getClerkUiSupportedReactBounds(): VersionBounds[] {
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't love the logic here, doing some iteration...

…pendencies

- Remove hardcoded fallback version range in tsup.config.ts
- Start from package.json peerDependencies.react to determine version range
- If it's a catalog reference (catalog:XXX), resolve it from pnpm-workspace.yaml
- If it's already a version range, parse it directly
- Extract parseRangeToBounds to build-utils/ for testability
- Add comprehensive tests for version range parsing

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants