fix(react): Use globalThis instead of bare global in the browser Clerk loader

[jacekradko]

Fixes #8871. <ClerkProvider> crashed in production builds (TanStack Start, React Router) with ReferenceError: global is not defined. The loader read a bare global.Clerk that only resolved via the window.global polyfill on the package's main entry, but the provider comes in through @clerk/react/internal, which never imports that polyfill; since the tsdown migration (#8177) split the package into chunks, a production bundle can reach the loader with the polyfill absent. Using globalThis drops the dependency.

The bit worth scrutiny is the type change: declare const global only typed the global name, so globalThis.Clerk needs a declare global augmentation. It's intentionally not emitted into the public .d.ts, so consumers don't gain an ambient Clerk global. The window.global polyfill is kept for older clerk-js runtimes.

Summary by CodeRabbit

• Bug Fixes
  • Fixed a runtime initialization error that occurred in production environments during ClerkProvider startup, particularly in applications using TanStack Start and React Router. The fix improves compatibility across different bundler configurations and ensures reliable operation in all supported environments.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3ab67ad

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

This PR includes changesets to release 6 packages

Name	Type
@clerk/react	Patch
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/nextjs	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	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]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 18, 2026 1:08am
swingset	Ready	Preview, Comment	Jun 18, 2026 1:08am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: a83139a1-1b11-4fe8-9d36-de156602f4ce

📥 Commits

Reviewing files that changed from the base of the PR and between 27fc09a and 3ab67ad.

📒 Files selected for processing (2)

• .changeset/silly-pumas-cheer.md
• packages/react/src/isomorphicClerk.ts

✅ Files skipped from review due to trivial changes (1)

• .changeset/silly-pumas-cheer.md

---

📝 Walkthrough

Walkthrough

The PR fixes a production ReferenceError: global is not defined in ClerkProvider by replacing all global.* references in isomorphicClerk.ts with globalThis.*. The exported Global interface and declare const global typing are removed in favor of a declare global augmentation. A changeset entry documents the patch release.

Changes

globalThis migration fix

Layer / File(s)

Summary

Type declarations and runtime globalThis lookups packages/react/src/isomorphicClerk.ts, .changeset/silly-pumas-cheer.md

Removes the exported Global interface and declare const global: Global typing, replacing them with a declare global augmentation defining globalThis.Clerk and globalThis.__internal_ClerkUICtor. Updates getClerkJsEntryChunk to assign and read globalThis.Clerk with an explicit throw if undefined, and updates getClerkUIEntryChunk to read globalThis.__internal_ClerkUICtor with the same guard. Changeset documents the patch.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• TanStack Start ClerkProvider can fail when global shim is split into lazy chunk #8871: This PR directly resolves the reported ReferenceError: global is not defined by replacing global.Clerk with globalThis.Clerk in getClerkJsEntryChunk, eliminating the dependency on the unreliably-ordered window.global polyfill.

Possibly related PRs

• clerk/javascript#8773: Both PRs modify packages/react/src/isomorphicClerk.ts, specifically getClerkUIEntryChunk's loading and guard logic around __internal_ClerkUICtor.

Suggested reviewers

• tmilewski

Poem

🐇 A bunny once tripped on a global unknown,
The bundler had shuffled—its polyfill not shown.
"Use globalThis!" cried the rabbit with glee,
One universal object, as standard as can be.
No more ReferenceError to ruin the day! 🎉

🚥 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 accurately describes the main fix: replacing bare global with globalThis in the browser Clerk loader, which directly addresses the ReferenceError bug in production builds.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-18T01:09:41.055Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 3ab67ad.}

[wobsoriano]

Nice!