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/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

@@ -11,6 +11,7 @@ import React from 'react';
 
 import { IsomorphicClerk } from '../isomorphicClerk';
 import type { IsomorphicClerkOptions } from '../types';
+import { IS_REACT_SHARED_VARIANT_COMPATIBLE } from '../utils/versionCheck';
 import { AuthContext } from './AuthContext';
 import { IsomorphicClerkContext } from './IsomorphicClerkContext';
 
@@ -111,8 +112,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 = (options: IsomorphicClerkOptions) => {
-  const isomorphicClerkRef = React.useRef(IsomorphicClerk.getOrCreateInstance(options));
+  // 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,
+      ...options,
+    }),
+    [options],
+  );
+  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/utils/__tests__/versionCheck.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from 'vitest';
+
+import { checkVersionAgainstBounds, isVersionCompatible, parseVersion, type VersionBounds } from '../versionCheck';
+
+describe('parseVersion', () => {
+  it('parses standard semver versions', () => {
+    expect(parseVersion('18.3.1')).toEqual({ major: 18, minor: 3, patch: 1 });
+    expect(parseVersion('19.0.0')).toEqual({ major: 19, minor: 0, patch: 0 });
+    expect(parseVersion('0.0.1')).toEqual({ major: 0, minor: 0, patch: 1 });
+  });
+
+  it('parses versions with pre-release suffixes', () => {
+    expect(parseVersion('19.0.0-rc.1')).toEqual({ major: 19, minor: 0, patch: 0 });
+    expect(parseVersion('18.3.0-alpha.1')).toEqual({ major: 18, minor: 3, patch: 0 });
+    expect(parseVersion('19.0.0-beta.2+build.123')).toEqual({ major: 19, minor: 0, patch: 0 });
+  });
+
+  it('returns null for invalid versions', () => {
+    expect(parseVersion('')).toBeNull();
+    expect(parseVersion('invalid')).toBeNull();
+    expect(parseVersion('18')).toBeNull();
+    expect(parseVersion('18.3')).toBeNull();
+    expect(parseVersion('v18.3.1')).toBeNull();
+    expect(parseVersion('18.3.x')).toBeNull();
+  });
+});
+
+describe('checkVersionAgainstBounds', () => {
+  describe('caret ranges (maxMinor === -1)', () => {
+    // ^18.0.0 means >= 18.0.0 and < 19.0.0
+    const caretBounds: VersionBounds[] = [[18, 0, -1, 0]];
+
+    it('matches versions at the minimum', () => {
+      expect(checkVersionAgainstBounds({ major: 18, minor: 0, patch: 0 }, caretBounds)).toBe(true);
+    });
+
+    it('matches versions with higher minor', () => {
+      expect(checkVersionAgainstBounds({ major: 18, minor: 1, patch: 0 }, caretBounds)).toBe(true);
+      expect(checkVersionAgainstBounds({ major: 18, minor: 99, patch: 99 }, caretBounds)).toBe(true);
+    });
+
+    it('matches versions with higher patch on same minor', () => {
+      expect(checkVersionAgainstBounds({ major: 18, minor: 0, patch: 1 }, caretBounds)).toBe(true);
+      expect(checkVersionAgainstBounds({ major: 18, minor: 0, patch: 99 }, caretBounds)).toBe(true);
+    });
+
+    it('does not match versions with lower major', () => {
+      expect(checkVersionAgainstBounds({ major: 17, minor: 99, patch: 99 }, caretBounds)).toBe(false);
+    });
+
+    it('does not match versions with higher major', () => {
+      expect(checkVersionAgainstBounds({ major: 19, minor: 0, patch: 0 }, caretBounds)).toBe(false);
+    });
+
+    it('does not match versions below the minimum patch', () => {
+      // ^18.2.5 means >= 18.2.5
+      const boundsWithPatch: VersionBounds[] = [[18, 2, -1, 5]];
+      expect(checkVersionAgainstBounds({ major: 18, minor: 2, patch: 4 }, boundsWithPatch)).toBe(false);
+      expect(checkVersionAgainstBounds({ major: 18, minor: 2, patch: 5 }, boundsWithPatch)).toBe(true);
+      expect(checkVersionAgainstBounds({ major: 18, minor: 2, patch: 6 }, boundsWithPatch)).toBe(true);
+      // Higher minor still works
+      expect(checkVersionAgainstBounds({ major: 18, minor: 3, patch: 0 }, boundsWithPatch)).toBe(true);
+    });
+  });
+
+  describe('tilde ranges (maxMinor === minMinor)', () => {
+    // ~19.0.0 means >= 19.0.0 and < 19.1.0
+    const tildeBounds: VersionBounds[] = [[19, 0, 0, 0]];
+
+    it('matches versions at the minimum', () => {
+      expect(checkVersionAgainstBounds({ major: 19, minor: 0, patch: 0 }, tildeBounds)).toBe(true);
+    });
+
+    it('matches versions with higher patch on same minor', () => {
+      expect(checkVersionAgainstBounds({ major: 19, minor: 0, patch: 1 }, tildeBounds)).toBe(true);
+      expect(checkVersionAgainstBounds({ major: 19, minor: 0, patch: 99 }, tildeBounds)).toBe(true);
+    });
+
+    it('does not match versions with different minor', () => {
+      expect(checkVersionAgainstBounds({ major: 19, minor: 1, patch: 0 }, tildeBounds)).toBe(false);
+      expect(checkVersionAgainstBounds({ major: 19, minor: 2, patch: 0 }, tildeBounds)).toBe(false);
+    });
+
+    it('does not match versions with different major', () => {
+      expect(checkVersionAgainstBounds({ major: 18, minor: 0, patch: 0 }, tildeBounds)).toBe(false);
+      expect(checkVersionAgainstBounds({ major: 20, minor: 0, patch: 0 }, tildeBounds)).toBe(false);
+    });
+
+    it('does not match versions below the minimum patch', () => {
+      // ~19.0.3 means >= 19.0.3 and < 19.1.0
+      const boundsWithPatch: VersionBounds[] = [[19, 0, 0, 3]];
+      expect(checkVersionAgainstBounds({ major: 19, minor: 0, patch: 2 }, boundsWithPatch)).toBe(false);
+      expect(checkVersionAgainstBounds({ major: 19, minor: 0, patch: 3 }, boundsWithPatch)).toBe(true);
+      expect(checkVersionAgainstBounds({ major: 19, minor: 0, patch: 4 }, boundsWithPatch)).toBe(true);
+    });
+  });
+
+  describe('multiple bounds', () => {
+    // ^18.0.0 || ^19.0.0
+    const multipleBounds: VersionBounds[] = [
+      [18, 0, -1, 0],
+      [19, 0, -1, 0],
+    ];
+
+    it('matches versions satisfying any bound', () => {
+      expect(checkVersionAgainstBounds({ major: 18, minor: 3, patch: 1 }, multipleBounds)).toBe(true);
+      expect(checkVersionAgainstBounds({ major: 19, minor: 0, patch: 0 }, multipleBounds)).toBe(true);
+    });
+
+    it('does not match versions outside all bounds', () => {
+      expect(checkVersionAgainstBounds({ major: 17, minor: 0, patch: 0 }, multipleBounds)).toBe(false);
+      expect(checkVersionAgainstBounds({ major: 20, minor: 0, patch: 0 }, multipleBounds)).toBe(false);
+    });
+  });
+
+  describe('empty bounds', () => {
+    it('returns false for empty bounds array', () => {
+      expect(checkVersionAgainstBounds({ major: 18, minor: 0, patch: 0 }, [])).toBe(false);
+    });
+  });
+});
+
+describe('isVersionCompatible', () => {
+  const bounds: VersionBounds[] = [
+    [18, 0, -1, 0], // ^18.0.0
+    [19, 0, -1, 0], // ^19.0.0
+  ];
+
+  it('returns true for compatible versions', () => {
+    expect(isVersionCompatible('18.3.1', bounds)).toBe(true);
+    expect(isVersionCompatible('19.0.0', bounds)).toBe(true);
+    expect(isVersionCompatible('19.0.0-rc.1', bounds)).toBe(true);
+  });
+
+  it('returns false for incompatible versions', () => {
+    expect(isVersionCompatible('17.0.0', bounds)).toBe(false);
+    expect(isVersionCompatible('20.0.0', bounds)).toBe(false);
+  });
+
+  it('returns false for invalid version strings', () => {
+    expect(isVersionCompatible('', bounds)).toBe(false);
+    expect(isVersionCompatible('invalid', bounds)).toBe(false);
+  });
+});