fix(react): attach UI for preloaded Clerk instances

[jacekradko]

Fixes #8569.

When React's IsomorphicClerk reused an already-loaded global Clerk instance, it skipped the UI chunk load and immediately replayed premounted UI invocations, so sign-in/sign-up etc. never rendered. Now we load the UI chunk and call clerk.load again on the existing instance, which short-circuits the resource fetch but attaches ClerkUI via the new #initClerkUI path.

Includes regression tests for both packages and a patch changeset.

Before:

After:

[changeset-bot]

🦋 Changeset detected

Latest commit: 0fdc348

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

This PR includes changesets to release 7 packages

Name	Type
@clerk/clerk-js	Patch
@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	May 20, 2026 1:32am

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR fixes a bug where React applications that load Clerk outside the React provider (e.g., in client-side loaders) fail to mount UI components. The fix refactors Clerk.load() to support deferred UI initialization via a new #initClerkUI() method that can attach UI even when Clerk is already marked loaded. React's isomorphicClerk integration is enhanced to detect preloaded Clerk instances and conditionally load and attach bundled UI. Tests verify both the core mechanism and React integration work without unnecessary refetches.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(react): attach UI for preloaded Clerk instances' directly and specifically describes the main change: enabling UI attachment when React reuses an already-loaded Clerk instance.
Linked Issues check	✅ Passed	The PR fully addresses issue #8569 by ensuring UI components are loaded when React reuses a preloaded Clerk instance, fixing the 'Clerk was not loaded with Ui components' error through the new #initClerkUI path.
Out of Scope Changes check	✅ Passed	All changes are scoped to the linked issue: modifications to clerk.ts, isomorphicClerk.ts, and corresponding tests directly address the UI attachment bug when Clerk is preloaded.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The description is clearly related to the changeset, explaining the bug fix for preloaded Clerk instances and referencing the issue number, changes made, and test coverage added.

_{✏️ 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]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8594

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 0fdc348

[Ephem]

This part worries me a bit. After the initial load, the options have always been immutable before, now they can theoretically change, but they aren't reactive so if we've read them anywhere already, those values might now be stale (imagine clerk-js loads -> components in the host app rely on some options via the hooks -> ui loads with other options).

Supporting options updating for real with reactivity would be a huge pain for no real gain.

I think a clean alternative is to lift this to an __internal_attachUi(ui) function that's only callable after the initial load?

Internal only to avoid increasing the API surface needlessly for an advanced feature only we are likely to use, could make it public if there is demand.