feat(ui,react): Add shared React variant to reduce bundle size

.changeset/shared-react-variant.md

@@ -0,0 +1,17 @@
+---
+"@clerk/ui": minor
+"@clerk/react": minor
+"@clerk/shared": patch
+---
+
+Add shared React variant to reduce bundle size when using `@clerk/react`.
+
+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. This can significantly reduce bundle size for applications using `@clerk/react`.
+
+**New features:**
+- `@clerk/ui/register` module: Import this to register React on `globalThis.__clerkSharedModules` for sharing with `@clerk/ui`
+- `clerkUiVariant` option: Set to `'shared'` to use the shared variant (automatically detected and enabled for compatible React versions in `@clerk/react`)
+
+**For `@clerk/react` users:** No action required. The shared variant is automatically used when your React version is compatible.
+
+**For custom integrations:** Import `@clerk/ui/register` before loading the UI bundle, then set `clerkUiVariant: 'shared'` in your configuration.

packages/nextjs/src/utils/clerk-script.tsx

@@ -4,12 +4,15 @@ import {
   buildClerkUiScriptAttributes,
   clerkJsScriptUrl,
   clerkUiScriptUrl,
+  IS_REACT_SHARED_VARIANT_COMPATIBLE,
 } from '@clerk/react/internal';
 import NextScript from 'next/script';
 import React from 'react';
 
 import { useClerkNextOptions } from '../client-boundary/NextOptionsContext';
 
+const DEFAULT_CLERK_UI_VARIANT = IS_REACT_SHARED_VARIANT_COMPATIBLE ? ('shared' as const) : ('' as const);
+
 type ClerkScriptProps = {
   scriptUrl: string;
   attributes: Record<string, string>;
@@ -43,7 +46,8 @@ function ClerkScript(props: ClerkScriptProps) {
 }
 
 export function ClerkScripts({ router }: { router: ClerkScriptProps['router'] }) {
-  const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant, nonce, clerkUiUrl, ui } = useClerkNextOptions();
+  const { publishableKey, clerkJSUrl, clerkJSVersion, clerkJSVariant, nonce, clerkUiUrl, clerkUiVariant, ui } =
+    useClerkNextOptions();
   const { domain, proxyUrl } = useClerk();
 
   if (!publishableKey) {
@@ -60,6 +64,7 @@ export function ClerkScripts({ router }: { router: ClerkScriptProps['router'] })
     proxyUrl,
     clerkUiVersion: ui?.version,
     clerkUiUrl: ui?.url || clerkUiUrl,
+    clerkUiVariant: clerkUiVariant ?? DEFAULT_CLERK_UI_VARIANT,
   };
 
   return (

packages/react/.gitignore

@@ -1,3 +1,4 @@
 /*/
 !/src/
 !/docs/
+!/build-utils/

packages/react/build-utils/__tests__/parseVersionRange.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseRangeToBounds, type VersionBounds } from '../parseVersionRange';
+
+describe('parseRangeToBounds', () => {
+  describe('caret ranges', () => {
+    it('parses simple caret range', () => {
+      expect(parseRangeToBounds('^18.0.0')).toEqual<VersionBounds[]>([[18, 0, -1, 0]]);
+    });
+
+    it('parses caret range with non-zero minor', () => {
+      expect(parseRangeToBounds('^18.2.0')).toEqual<VersionBounds[]>([[18, 2, -1, 0]]);
+    });
+
+    it('parses caret range with non-zero patch', () => {
+      expect(parseRangeToBounds('^18.2.5')).toEqual<VersionBounds[]>([[18, 2, -1, 5]]);
+    });
+  });
+
+  describe('tilde ranges', () => {
+    it('parses simple tilde range', () => {
+      expect(parseRangeToBounds('~19.0.0')).toEqual<VersionBounds[]>([[19, 0, 0, 0]]);
+    });
+
+    it('parses tilde range with non-zero minor', () => {
+      expect(parseRangeToBounds('~19.1.0')).toEqual<VersionBounds[]>([[19, 1, 1, 0]]);
+    });
+
+    it('parses tilde range with non-zero patch', () => {
+      expect(parseRangeToBounds('~19.0.3')).toEqual<VersionBounds[]>([[19, 0, 0, 3]]);
+    });
+  });
+
+  describe('exact versions', () => {
+    it('treats exact version as caret range', () => {
+      expect(parseRangeToBounds('18.3.1')).toEqual<VersionBounds[]>([[18, 3, -1, 1]]);
+    });
+  });
+
+  describe('OR combinations', () => {
+    it('parses two caret ranges', () => {
+      expect(parseRangeToBounds('^18.0.0 || ^19.0.0')).toEqual<VersionBounds[]>([
+        [18, 0, -1, 0],
+        [19, 0, -1, 0],
+      ]);
+    });
+
+    it('parses mixed caret and tilde ranges', () => {
+      expect(parseRangeToBounds('^18.0.0 || ~19.0.3')).toEqual<VersionBounds[]>([
+        [18, 0, -1, 0],
+        [19, 0, 0, 3],
+      ]);
+    });
+
+    it('parses multiple tilde ranges', () => {
+      expect(parseRangeToBounds('~19.0.3 || ~19.1.4 || ~19.2.3')).toEqual<VersionBounds[]>([
+        [19, 0, 0, 3],
+        [19, 1, 1, 4],
+        [19, 2, 2, 3],
+      ]);
+    });
+
+    it('parses complex real-world range', () => {
+      // This is the actual range from pnpm-workspace.yaml
+      expect(parseRangeToBounds('^18.0.0 || ~19.0.3 || ~19.1.4 || ~19.2.3 || ~19.3.0-0')).toEqual<VersionBounds[]>([
+        [18, 0, -1, 0],
+        [19, 0, 0, 3],
+        [19, 1, 1, 4],
+        [19, 2, 2, 3],
+        [19, 3, 3, 0],
+      ]);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles extra whitespace', () => {
+      expect(parseRangeToBounds('  ^18.0.0   ||   ^19.0.0  ')).toEqual<VersionBounds[]>([
+        [18, 0, -1, 0],
+        [19, 0, -1, 0],
+      ]);
+    });
+
+    it('returns empty array for invalid input', () => {
+      expect(parseRangeToBounds('invalid')).toEqual<VersionBounds[]>([]);
+      expect(parseRangeToBounds('')).toEqual<VersionBounds[]>([]);
+    });
+
+    it('skips invalid parts in OR combinations', () => {
+      expect(parseRangeToBounds('^18.0.0 || invalid || ^19.0.0')).toEqual<VersionBounds[]>([
+        [18, 0, -1, 0],
+        [19, 0, -1, 0],
+      ]);
+    });
+
+    it('handles prerelease versions', () => {
+      // semver.coerce strips prerelease info
+      expect(parseRangeToBounds('~19.3.0-0')).toEqual<VersionBounds[]>([[19, 3, 3, 0]]);
+      expect(parseRangeToBounds('^19.0.0-rc.1')).toEqual<VersionBounds[]>([[19, 0, -1, 0]]);
+    });
+  });
+});

packages/react/build-utils/parseVersionRange.ts

@@ -0,0 +1,47 @@
+import { coerce } from 'semver';
+
+// Version bounds format: [major, minMinor, maxMinor, minPatch]
+// - maxMinor === -1 means "any minor" (caret range, e.g., ^18.0.0)
+// - maxMinor === minMinor means "same minor only" (tilde range, e.g., ~19.0.3)
+export type VersionBounds = [major: number, minMinor: number, maxMinor: number, minPatch: number];
+
+/**
+ * Parses a semver range string (e.g., "^18.0.0 || ~19.0.3") into version bounds.
+ *
+ * Supported formats:
+ * - Caret ranges: ^X.Y.Z - allows any version >= X.Y.Z and < (X+1).0.0
+ * - Tilde ranges: ~X.Y.Z - allows any version >= X.Y.Z and < X.(Y+1).0
+ * - Exact versions: X.Y.Z - treated as caret range
+ * - OR combinations: "^18.0.0 || ~19.0.3" - multiple ranges separated by ||
+ *
+ * @param rangeStr - The semver range string to parse
+ * @returns Array of version bounds, one per range component
+ */
+export function parseRangeToBounds(rangeStr: string): VersionBounds[] {
+  const bounds: VersionBounds[] = [];
+  const parts = rangeStr.split('||').map(s => s.trim());
+
+  for (const part of parts) {
+    if (part.startsWith('^')) {
+      // Caret range: ^X.Y.Z means >= X.Y.Z and < (X+1).0.0
+      const ver = coerce(part.slice(1));
+      if (ver) {
+        bounds.push([ver.major, ver.minor, -1, ver.patch]);
+      }
+    } else if (part.startsWith('~')) {
+      // Tilde range: ~X.Y.Z means >= X.Y.Z and < X.(Y+1).0
+      const ver = coerce(part.slice(1));
+      if (ver) {
+        bounds.push([ver.major, ver.minor, ver.minor, ver.patch]);
+      }
+    } else {
+      // Exact version or other format - try to parse as caret
+      const ver = coerce(part);
+      if (ver) {
+        bounds.push([ver.major, ver.minor, -1, ver.patch]);
+      }
+    }
+  }
+
+  return bounds;
+}

packages/react/package.json

@@ -101,7 +101,9 @@
   "devDependencies": {
     "@clerk/localizations": "workspace:*",
     "@clerk/ui": "workspace:*",
-    "@types/semver": "^7.7.1"
+    "@types/semver": "^7.7.1",
+    "semver": "^7.7.1",
+    "yaml": "^2.8.0"
   },
   "peerDependencies": {
     "react": "catalog:peer-react",

packages/react/src/contexts/ClerkContextProvider.tsx

@@ -12,6 +12,7 @@ import React from 'react';
 import { IsomorphicClerk } from '../isomorphicClerk';
 import type { IsomorphicClerkOptions } from '../types';
 import { mergeWithEnv } from '../utils';
+import { IS_REACT_SHARED_VARIANT_COMPATIBLE } from '../utils/versionCheck';
 import { AuthContext } from './AuthContext';
 import { IsomorphicClerkContext } from './IsomorphicClerkContext';
 
@@ -114,8 +115,23 @@ export function ClerkContextProvider(props: ClerkContextProvider) {
   );
 }
 
+// Default clerkUiVariant based on React version compatibility.
+// Computed once at module level for optimal performance.
+const DEFAULT_CLERK_UI_VARIANT = IS_REACT_SHARED_VARIANT_COMPATIBLE ? ('shared' as const) : ('' as const);
+
 const useLoadedIsomorphicClerk = (mergedOptions: IsomorphicClerkOptions) => {
-  const isomorphicClerkRef = React.useRef(IsomorphicClerk.getOrCreateInstance(mergedOptions));
+  // Merge default clerkUiVariant with user options.
+  // User-provided options spread last to allow explicit overrides.
+  // The shared variant expects React to be provided via globalThis.__clerkSharedModules
+  // (set up by @clerk/ui/register import), which reduces bundle size.
+  const optionsWithDefaults = React.useMemo(
+    () => ({
+      clerkUiVariant: DEFAULT_CLERK_UI_VARIANT,
+      ...mergedOptions,
+    }),
+    [mergedOptions],
+  );
+  const isomorphicClerkRef = React.useRef(IsomorphicClerk.getOrCreateInstance(optionsWithDefaults));
   const [clerkStatus, setClerkStatus] = React.useState(isomorphicClerkRef.current.status);
 
   React.useEffect(() => {

packages/react/src/index.ts

@@ -1,5 +1,9 @@
 import './polyfills';
 import './types/appearance';
+// Register React on the global shared modules registry.
+// This enables @clerk/ui's shared variant to use the host app's React
+// instead of bundling its own copy, reducing overall bundle size.
+import '@clerk/ui/register';
 
 import { setClerkJsLoadingErrorPackageName } from '@clerk/shared/loadClerkJsScript';
 

packages/react/src/internal.ts

@@ -2,6 +2,7 @@ export { setErrorThrowerOptions } from './errors/errorThrower';
 export { MultisessionAppSupport } from './components/controlComponents';
 export { useRoutingProps } from './hooks/useRoutingProps';
 export { useDerivedAuth } from './hooks/useAuth';
+export { IS_REACT_SHARED_VARIANT_COMPATIBLE } from './utils/versionCheck';
 
 export {
   clerkJsScriptUrl,