fix(ui,nextjs): use rsc client reference for clerk-ui instead of dynamic import #7809

jacekradko · 2026-02-10T03:30:18Z

Summary

Remove broken webpackIgnore/turbopackIgnore dynamic import of @clerk/ui/entry from Next.js ClerkProvider
Add 'use client' directive to @clerk/ui's ClerkUI.ts and entry.ts so RSC serializes ClerkUI as a client reference
Include ClerkUI in @clerk/ui's server export (server.ts) — the RSC bundler creates a client module reference instead of bundling the actual code on the server

Problem

The import(/* webpackIgnore: true */ /* turbopackIgnore: true */ '@clerk/ui/entry') approach had two failure modes:

With pragmas: Both bundlers skip resolution, leaving the bare specifier @clerk/ui/entry in the browser bundle. Browsers cannot resolve bare module specifiers → TypeError: Failed to resolve module specifier '@clerk/ui/entry'
Without pragmas: The bundler tries to resolve @clerk/ui/entry at build time. Since @clerk/ui is an optional dependency, apps without it installed get a build failure

Solution

Use RSC's built-in client reference mechanism:

ClerkUI.ts is marked with 'use client' — this is semantically correct since it's client-only UI code
server.ts (used via the react-server package.json condition) now includes ClerkUI imported from ./entry
When the RSC bundler processes server.ts, it sees the 'use client' boundary on ClerkUI.js and creates a client module reference instead of including the actual code
This reference is serializable — it flows through RSC props from server to client components
On the client, React Flight resolves the reference to the actual ClerkUI class from the client bundle

No dynamic import needed. No bundler-specific workarounds. Works with both webpack and Turbopack.

Test plan

pnpm build passes for @clerk/ui and @clerk/nextjs
pnpm test passes for @clerk/ui (1548 tests) and @clerk/nextjs (347 tests)
Integration e2e tests pass in CI
Verify dist/ClerkUI.js has "use client" directive
Verify dist/server.js imports from ./ClerkUI.js (which has the client boundary)
No @clerk/ui/entry bare specifier in @clerk/nextjs built output

Summary by CodeRabbit

New Features
- ClerkUI is now exposed as a client-capable export and includes a public mounting API to programmatically ensure components are mounted.
- Runtime version/compatibility checks added with development-time errors and production warnings.
Bug Fixes
- Fixed client-side reference issues when using the UI prop with React Server Components.
Chores
- Converted relevant modules to client mode and updated tests.
- Normalized dynamic chunk naming and added a changeset for the patch release.

…ic import The dynamic import of @clerk/ui/entry with webpackIgnore/turbopackIgnore pragmas caused bare module specifiers to reach the browser runtime, failing with "TypeError: Failed to resolve module specifier". Removing the pragmas caused build failures when @clerk/ui wasn't installed. Instead, mark ClerkUI.ts with 'use client' so the RSC bundler automatically serializes it as a client reference when imported from server.ts (react-server condition). The client resolves the reference on hydration without any dynamic import.

vercel · 2026-02-10T03:30:24Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 10, 2026 4:33am

changeset-bot · 2026-02-10T03:30:26Z

🦋 Changeset detected

Latest commit: d1d2372

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

This PR includes changesets to release 3 packages

Name	Type
@clerk/ui	Patch
@clerk/nextjs	Patch
@clerk/chrome-extension	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

pkg-pr-new · 2026-02-10T03:33:44Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7809

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: d1d2372

coderabbitai · 2026-02-10T03:35:15Z

📝 Walkthrough

Walkthrough

ClerkUI was converted into a client module with a "use client" entry re-export, and server-side ui now includes ClerkUI. The Next.js client provider’s client-side resolution and caching for ClerkUI were removed. Tests were updated to expect ClerkUI as a defined function on the server export. A changeset was added. Two dynamic import chunk names were renamed from "signUp" to "signup".

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 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 primary change: replacing dynamic imports with RSC client references for ClerkUI in the ui and nextjs packages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

No actionable comments were generated in the recent review. 🎉

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

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/ui/src/entry.ts`:
- Line 3: The public export ClerkUI is undocumented; add a JSDoc comment
describing the exported API (either directly above the export in entry.ts or on
the ClerkUI class declaration) that states what ClerkUI is, its purpose, any
important props/options or constructor parameters, and any public methods/events
it exposes; ensure the JSDoc includes `@public` (or appropriate visibility tag)
and param/returns tags where applicable so the new ClerkUI export satisfies the
project’s public API documentation requirement.

packages/ui/src/entry.ts

jacekradko · 2026-02-10T03:45:17Z

!snapshot

clerk-cookie · 2026-02-10T03:47:24Z

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

Package	Version
@clerk/agent-toolkit	0.3.0-snapshot.v20260210034549
@clerk/astro	3.0.0-snapshot.v20260210034549
@clerk/backend	3.0.0-snapshot.v20260210034549
@clerk/chrome-extension	3.0.0-snapshot.v20260210034549
@clerk/clerk-js	6.0.0-snapshot.v20260210034549
@clerk/dev-cli	1.0.0-snapshot.v20260210034549
@clerk/expo	3.0.0-snapshot.v20260210034549
@clerk/expo-passkeys	1.0.0-snapshot.v20260210034549
@clerk/express	2.0.0-snapshot.v20260210034549
@clerk/fastify	2.7.0-snapshot.v20260210034549
@clerk/localizations	4.0.0-snapshot.v20260210034549
@clerk/msw	0.0.1-snapshot.v20260210034549
@clerk/nextjs	7.0.0-snapshot.v20260210034549
@clerk/nuxt	2.0.0-snapshot.v20260210034549
@clerk/react	6.0.0-snapshot.v20260210034549
@clerk/react-router	3.0.0-snapshot.v20260210034549
@clerk/shared	4.0.0-snapshot.v20260210034549
@clerk/tanstack-react-start	1.0.0-snapshot.v20260210034549
@clerk/testing	2.0.0-snapshot.v20260210034549
@clerk/ui	1.0.0-snapshot.v20260210034549
@clerk/upgrade	2.0.0-snapshot.v20260210034549
@clerk/vue	2.0.0-snapshot.v20260210034549

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

npm i @clerk/agent-toolkit@0.3.0-snapshot.v20260210034549 --save-exact

@clerk/astro

npm i @clerk/astro@3.0.0-snapshot.v20260210034549 --save-exact

@clerk/backend

npm i @clerk/backend@3.0.0-snapshot.v20260210034549 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.0.0-snapshot.v20260210034549 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.0.0-snapshot.v20260210034549 --save-exact

@clerk/dev-cli

npm i @clerk/dev-cli@1.0.0-snapshot.v20260210034549 --save-exact

@clerk/expo

npm i @clerk/expo@3.0.0-snapshot.v20260210034549 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.0.0-snapshot.v20260210034549 --save-exact

@clerk/express

npm i @clerk/express@2.0.0-snapshot.v20260210034549 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.7.0-snapshot.v20260210034549 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.0.0-snapshot.v20260210034549 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.1-snapshot.v20260210034549 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.0.0-snapshot.v20260210034549 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.0.0-snapshot.v20260210034549 --save-exact

@clerk/react

npm i @clerk/react@6.0.0-snapshot.v20260210034549 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.0.0-snapshot.v20260210034549 --save-exact

@clerk/shared

npm i @clerk/shared@4.0.0-snapshot.v20260210034549 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.0.0-snapshot.v20260210034549 --save-exact

@clerk/testing

npm i @clerk/testing@2.0.0-snapshot.v20260210034549 --save-exact

@clerk/ui

npm i @clerk/ui@1.0.0-snapshot.v20260210034549 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.0-snapshot.v20260210034549 --save-exact

@clerk/vue

npm i @clerk/vue@2.0.0-snapshot.v20260210034549 --save-exact

Align webpackChunkName for SignUp imports to "signup" (lowercase) to prevent case-sensitivity collision on Linux CI (signUp.js vs signup.js).

github-actions bot added nextjs core-3 labels Feb 10, 2026

coderabbitai bot reviewed Feb 10, 2026

View reviewed changes

packages/ui/src/entry.ts Show resolved Hide resolved

jacekradko changed the title ~~fix(ui,nextjs): use RSC client reference for ClerkUI instead of dynamic import~~ fix(ui,nextjs): use rsc client reference for clerk-ui instead of dynamic import Feb 10, 2026

fix(ui): normalize webpack chunk name casing and add changeset

574a445

Align webpackChunkName for SignUp imports to "signup" (lowercase) to prevent case-sensitivity collision on Linux CI (signUp.js vs signup.js).

vercel bot deployed to Preview February 10, 2026 03:56 View deployment

wobsoriano approved these changes Feb 10, 2026

View reviewed changes

docs(ui): add JSDoc to ClerkUI class, constructor, and ensureMounted

d1d2372

vercel bot deployed to Preview February 10, 2026 04:33 View deployment

jacekradko merged commit 0cca492 into main Feb 10, 2026
41 checks passed

jacekradko deleted the jacek/fix-ui-rsc-client-reference branch February 10, 2026 13:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(ui,nextjs): use rsc client reference for clerk-ui instead of dynamic import #7809

fix(ui,nextjs): use rsc client reference for clerk-ui instead of dynamic import #7809

Uh oh!

jacekradko commented Feb 10, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Feb 10, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Feb 10, 2026 •

edited

Loading

Walkthrough

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

jacekradko commented Feb 10, 2026

Uh oh!

clerk-cookie commented Feb 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fix(ui,nextjs): use rsc client reference for clerk-ui instead of dynamic import #7809

fix(ui,nextjs): use rsc client reference for clerk-ui instead of dynamic import #7809

Uh oh!

Conversation

jacekradko commented Feb 10, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Solution

Test plan

Summary by CodeRabbit

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Walkthrough

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jacekradko commented Feb 10, 2026

Uh oh!

clerk-cookie commented Feb 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jacekradko commented Feb 10, 2026 •

edited by coderabbitai bot

Loading

vercel bot commented Feb 10, 2026 •

edited

Loading

changeset-bot bot commented Feb 10, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 10, 2026 •

edited

Loading

coderabbitai bot commented Feb 10, 2026 •

edited

Loading