fix(react): Respect ui prop when Clerk instance is passed to IsomorphicClerk by royanger · Pull Request #7997 · clerk/javascript

royanger · 2026-03-05T18:36:57Z

Description

The guard that causes the bug is:

const shouldLoadUi = !this.options.Clerk && this.options.standardBrowser !== false;

@clerk/react, @clerk/nextjs, etc.: this.options.Clerk is undefined → !this.options.Clerk is true → shouldLoadUi is true → getClerkUIEntryChunk() runs → finds uiProp.ClerkUI from the ui prop and returns it → ClerkUI is valid, no overwrite.

@clerk/chrome-extension: this.options.Clerk is a Clerk instance (truthy) → !this.options.Clerk is false → shouldLoadUi is false → ClerkUI = undefined → overwrites the valid ClerkUI from the ui prop.

The chrome-extension needs its own Clerk instance because it has to wire up extension-specific hooks (JWT handling, cookie syncing, storage cache, etc.) in createClerkClient before the instance is used.

Fix implemented in packages/react/src/isomorphicClerk.ts:

const shouldLoadUi = (this.options.standardBrowser !== false && !this.options.Clerk) || !!this.options.ui?.ClerkUI;

Logic: Load UI when either:

Standard browser mode without a pre-created Clerk instance (normal CDN path for react/nextjs/react-router/tanstack), OR
A bundled ClerkUI was provided via the ui prop (chrome-extension, even with standardBrowser: false)

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

Bug Fixes
- Fixed an issue where custom UI configurations were not respected when providing a pre-created Clerk instance to IsomorphicClerk, resolving Chrome Extension SDK errors.
Tests
- Added test coverage for Clerk instance configurations with custom UI settings across different environment conditions.

changeset-bot · 2026-03-05T18:37:02Z

🦋 Changeset detected

Latest commit: 1448607

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	Minor
@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 · 2026-03-05T18:37:02Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 9, 2026 8:06pm

royanger · 2026-03-05T18:59:39Z

!snapshot

royanger · 2026-03-05T19:09:46Z

!snapshot

tmilewski · 2026-03-05T19:18:48Z

!snapshot

royanger · 2026-03-05T19:33:45Z

!snapshot

brkalow · 2026-03-05T20:01:42Z

packages/react/src/isomorphicClerk.ts

@@ -474,7 +474,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
        this.beforeLoad(clerk);
        // Only load UI scripts in standard browser environments (not native/headless)
        const shouldLoadUi = !this.options.Clerk && this.options.standardBrowser !== false;


Do you think shouldLoadUi should be false if this.options.ui?.ClerkUI exists? or is that already handled elsewhere?

Nope. I was mostly starting with a draft PR so I could get snapshots, since this issue wasn't showing up in local testing. The updated change in 2dc46ff should be a better approach, but I still need to test it.

.changeset/tricky-apples-attend.md

royanger · 2026-03-06T20:39:25Z

!snapshot

royanger · 2026-03-06T20:57:13Z

!snapshot

…ome-extensions

royanger · 2026-03-06T22:42:17Z

!snapshot

…ome-extensions

royanger · 2026-03-09T19:29:19Z

!snapshot

clerk-cookie · 2026-03-09T19:31:57Z

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

Package	Version
@clerk/agent-toolkit	0.3.2-snapshot.v20260309193008
@clerk/astro	3.0.2-snapshot.v20260309193008
@clerk/backend	3.0.2-snapshot.v20260309193008
@clerk/chrome-extension	3.1.0-snapshot.v20260309193008
@clerk/clerk-js	6.1.0-snapshot.v20260309193008
@clerk/dev-cli	0.1.1-snapshot.v20260309193008
@clerk/expo	3.1.0-snapshot.v20260309193008
@clerk/expo-passkeys	1.0.2-snapshot.v20260309193008
@clerk/express	2.0.2-snapshot.v20260309193008
@clerk/fastify	3.1.0-snapshot.v20260309193008
@clerk/hono	0.1.0-snapshot.v20260309193008
@clerk/localizations	4.1.0-snapshot.v20260309193008
@clerk/msw	0.0.2-snapshot.v20260309193008
@clerk/nextjs	7.0.2-snapshot.v20260309193008
@clerk/nuxt	2.0.2-snapshot.v20260309193008
@clerk/react	6.1.0-snapshot.v20260309193008
@clerk/react-router	3.0.2-snapshot.v20260309193008
@clerk/shared	4.1.0-snapshot.v20260309193008
@clerk/tanstack-react-start	1.0.2-snapshot.v20260309193008
@clerk/testing	2.0.2-snapshot.v20260309193008
@clerk/ui	1.1.0-snapshot.v20260309193008
@clerk/upgrade	2.0.2-snapshot.v20260309193008
@clerk/vue	2.0.2-snapshot.v20260309193008

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

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/dev-cli

npm i @clerk/[email protected] --save-exact

@clerk/expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/hono

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/msw

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/ui

npm i @clerk/[email protected] --save-exact

@clerk/upgrade

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact

coderabbitai · 2026-03-09T19:40:57Z

📝 Walkthrough

Walkthrough

Updates change IsomorphicClerk UI-loading logic: ClerkUI is now loaded when either (a) standardBrowser is not false and no Clerk instance is provided, or (b) a ui.ClerkUI is explicitly supplied. The clerk.load call is updated to include ui.ClerkUI when present. A changeset bumps @clerk/react with a minor version. Comprehensive tests were added to validate UI loading across CDN, bundled, Expo, and Chrome Extension scenarios and to ensure ui.ClerkUI is preserved when a Clerk instance is passed.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and specifically describes the main fix: respecting the ui prop when a Clerk instance is passed to IsomorphicClerk, which matches the core change in the isomorphicClerk.ts logic.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

…n't load

tmilewski · 2026-03-09T20:38:18Z

Throwing this in here for posterity:

The deep research and comprehensive testing across all SDK packages has been completed. Here's a summary of where things stand:

  Fix implemented in packages/react/src/isomorphicClerk.ts:                                                                                                                
  const shouldLoadUi =
    (this.options.standardBrowser !== false && !this.options.Clerk) || !!this.options.ui?.ClerkUI;                                                                         

  Logic: Load UI when either:                                                                                                                                              
  - Standard browser mode without a pre-created Clerk instance (normal CDN path for react/nextjs/react-router/tanstack), OR
  - A bundled ClerkUI was provided via the ui prop (chrome-extension, even with standardBrowser: false)

  8 scenario tests added in packages/react/src/__tests__/isomorphicClerk.test.ts covering every SDK combination:
  - @clerk/react, @clerk/nextjs, @clerk/react-router, @clerk/tanstack-react-start → CDN
  - @clerk/react with bundled ui prop → bundled ClerkUI
  - @clerk/expo native → no UI
  - @clerk/expo web → CDN
  - @clerk/chrome-extension without syncHost → bundled ClerkUI
  - @clerk/chrome-extension with syncHost → bundled ClerkUI (the bug case)
  - Clerk instance without ui prop → no UI
  - Server marker ui without ClerkUI → no CDN

fix: Respect ui prop when Clerk instance is passed to ClerkProvider

a2d370f

github-actions bot added the react label Mar 5, 2026

chore: Add changeset

42cc094

royanger changed the title ~~fix: Respect ui prop when Clerk instance is passed to ClerkProvider~~ fix(react): Respect ui prop when Clerk instance is passed to IsomorphicClerk Mar 5, 2026

vercel bot deployed to Preview March 5, 2026 18:58 View deployment

brkalow reviewed Mar 5, 2026

View reviewed changes

.changeset/tricky-apples-attend.md Outdated Show resolved Hide resolved

fix: Fixed changeset formatting

3f4e299

vercel bot deployed to Preview March 6, 2026 20:56 View deployment

This comment has been minimized.

Sign in to view

fix: Updated fix

2dc46ff

vercel bot deployed to Preview March 6, 2026 22:36 View deployment

Merge branch 'main' into roy/fix-clerk-loaded-without-ui-error-in-chr…

55641a5

…ome-extensions

vercel bot deployed to Preview March 6, 2026 22:41 View deployment

This comment has been minimized.

Sign in to view

royanger added 2 commits March 9, 2026 15:14

fix: Refined fix

6d1abce

Merge branch 'main' into roy/fix-clerk-loaded-without-ui-error-in-chr…

8477178

…ome-extensions

vercel bot deployed to Preview March 9, 2026 19:16 View deployment

royanger marked this pull request as ready for review March 9, 2026 19:37

test: Added more tests for various scenarios were ui should or should…

1448607

…n't load

vercel bot deployed to Preview March 9, 2026 20:06 View deployment

royanger requested a review from brkalow March 9, 2026 20:38

tmilewski approved these changes Mar 9, 2026

View reviewed changes

Conversation

royanger commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

royanger commented Mar 5, 2026

Uh oh!

royanger commented Mar 5, 2026

Uh oh!

tmilewski commented Mar 5, 2026

Uh oh!

royanger commented Mar 5, 2026

Uh oh!

brkalow Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

royanger Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

royanger commented Mar 6, 2026

Uh oh!

royanger commented Mar 6, 2026

Uh oh!

This comment has been minimized.

royanger commented Mar 6, 2026

Uh oh!

This comment has been minimized.

royanger commented Mar 9, 2026

Uh oh!

clerk-cookie commented Mar 9, 2026

Uh oh!

coderabbitai bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

tmilewski commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

royanger commented Mar 5, 2026 •

edited

Loading

changeset-bot bot commented Mar 5, 2026 •

edited

Loading

vercel bot commented Mar 5, 2026 •

edited

Loading

coderabbitai bot commented Mar 9, 2026 •

edited

Loading