[alexcarpenter]

Description

Compound components (<Avatar.Root>, <Item.Group>, ...) can now be rendered from React Server Components.

Before this change, each compound was a plain object exported from a 'use client' module. Next replaces every export of such a module with a client reference, so Avatar.Root was undefined on the server.

Each of the 25 compound components now follows the Base UI layout:

• <name>.tsx is a 'use client' leaf with prefixed exports (CardRoot, CardBanner, ...).
• <name>.parts.ts re-exports them under the part names (Root, Banner, ...).
• index.ts has no directive and does export * as Card from './card.parts'.

X.Part usage and the XProps types are unchanged. Each compound is now a module namespace object, so its parts are read-only.

Other changes:

• tsdown builds with unbundle: true, so each file keeps its own 'use client' directive.
• scripts/check-bundle.mjs now checks rules instead of a file list. It reads ., ./components/* and ./primitives/* from the exports map. Each entry must either start with 'use client' or only re-export namespaces built from directive-free parts files. Any parts module that imports react must be a 'use client' leaf.
• dist/index.js is now a small re-export file, so pnpm bundlewatch first bundles it with rolldown (dependencies and peer dependencies left external) into dist/.bundlewatch/index.js and measures that against the existing 95KB budget. dist/.bundlewatch is excluded from the published files.
• Panel.Title passes [ref, panelTitleRef] to useRender. The forward-ref-parts rule now checks it because it is exported, and it could not trace the old conditional ref. Behavior is unchanged, because useRender returns before attaching refs when enabled is false.

Notes for review:

• Dialog.createHandle is the one part that isn't a component. On the server it is a client reference and can't be called.

Stacked on #10754.

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[vercel]

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

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Nov 12, 2026 8:50pm UTC
swingset	Ready	Preview	Nov 12, 2026 8:50pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 6733f4e

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

This PR includes changesets to release 2 packages

Name	Type
@clerk/mosaic	Patch
@clerk/swingset	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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: clerk/javascript
• Branch: carp/mosaic-rsc-compound-namespaces
• File: .coderabbit.yaml
• Commit: 6733f4e
• Layers: Repository YAML (base), Organization UI (inherited)
• Review profile: ASSERTIVE
• Plan: Team
• Run ID: c5e21c02-b782-49f6-8453-e624751da4bb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[blacksmith-sh]

Compound parts render from a Server Component

Tested on e2bc13fe, untouched since — Before, the Server Component page crashed on Banner.Root being undefined in dev and failed next build; after, all six compounds render and the page prerenders.

_Merge-base

_{This PR e2bc13fe}

_Merge-base

_{This PR e2bc13fe}

Also checked · 3 match · 2 not run

Panel.Title refs unchanged · Skipped
check-bundle enforces the new rules · Skipped
Client Component usage unchanged
Compound parts are now read-only
Bundlewatch measures the real index size

_{Proof on 6733f4e6 (from e2bc13fe) · Did Proof get it right? Yes · No}

View full Proof report · React 👎 or comment @codesmith dismiss this proof to dismiss