feat(ui): Expose profile sub components

[alexcarpenter]

Summary

Ships a composable UserProfile / OrganizationProfile from @clerk/ui/experimental. Consumers render individual panels and sections (Account, Security, Members, Billing, …) inline in their own app instead of inside Clerk's modal/page flow.

The API is a set of flat, top-level named exports — not a namespace object like UserProfile.Account. Each named export of a 'use client' module becomes its own React Server Component client reference, so consumers can render these directly in a Server Component tree without adding their own 'use client' boundary. (Property access on a namespace object would not survive the RSC boundary.)

import {
  UserProfileProvider,
  UserProfileAccountPanel,
  UserProfileSecurityPanel,
  UserProfileEmailSection,
  UserProfilePasswordSection,
} from '@clerk/ui/experimental';

export default function Page() {
  return (
    <UserProfileProvider>
      {/* A panel with no children renders the full standard page… */}
      <UserProfileAccountPanel />
      {/* …or you compose the sub-sections yourself. */}
      <UserProfileSecurityPanel>
        <UserProfilePasswordSection />
      </UserProfileSecurityPanel>
    </UserProfileProvider>
  );
}

Design decisions worth scrutiny

Area	Decision	Why
Flat named exports	Every panel/section is a top-level named export from @clerk/ui/experimental, not a property on a namespace object. flat-exports.test.ts pins the surface and asserts the namespace objects are undefined.	RSC client references (see Summary).
Provider shell (ProfileProviderShell.tsx)	Collapse LazyProviders + LazyComponentRenderer / LazyModalRenderer (portal path) into one shell. ClerkContextProvider omitted.	Composed mounts bypass the portal. Consumer's <ClerkProvider> already supplies clerk via useClerk().
Emotion cache	Shared per clerk instance via WeakMap (internal/styleCacheStore.ts).	Sibling composed roots would otherwise create two cl-internal caches and double-insert rules. Keyed on the clerk instance object, so it auto-GCs on teardown.
moduleManager	clerk-js exposes __internal_moduleManager getter on Clerk (clerk.ts:288); IsomorphicClerk forwards it (isomorphicClerk.ts:298). Composed shell reads clerk.__internal_moduleManager directly.	Makes <ClerkProvider ui={ui} /> optional for composed (Web3 works out of box). Plain property access is the only channel that crosses the bundle boundary — clerk-js loads standalone with its own inlined @clerk/shared, so @clerk/react/@clerk/ui reading @clerk/shared from node_modules see a different copy.
Options threading	Pull localization + supportEmail + nonce from clerk.__internal_getOption, pass via OptionsProvider / SharedStyleCacheProvider.	Only keys reachable from the composed subtree (makeLocalizable, parseLocalization, useSupportEmail, Emotion CSP nonce). nonce needs an as any cast (typed on IsomorphicClerkOptions, not ClerkOptions).
cssLayerName	Apply extractCssLayerNameFromAppearance on globalAppearance before reading.	Matches portal path normalization (Components.tsx:209). Without it, nested appearance.theme.cssLayerName is ignored.
Stub router (stubRouter.ts)	navigate / baseNavigate / resolve are real and SSR-safe. currentPath is a static empty string (no popstate listener). matches() / refresh() / getMatchData() throw in dev, no-op in prod.	Composed sections render outside the AIO Route/Switch tree. Dev throw catches accidental AIO API use, prod no-op keeps consumer apps from crashing on the same call. Contracts pinned by __tests__/stub-limitations.test.ts.
Dual-mode panels	A panel with no children passes through to the full AIO page (e.g. UserProfileAccountPanel → AccountPage). With children, sub-sections render directly under PageContext + CardStateProvider.	Lets consumers either drop in a section as-is or compose sub-parts. Passthrough only breaks if a sub-component calls matches()/refresh()/getMatchData() (dev throw, prod no-op).
Security panel	OrganizationProfileSecurityPanel renders the whole standard OrganizationSecurityPage (SSO overview + configuration wizard). It takes no composable children — the security tab is not section-based, unlike General. There is no standalone ConfigureSSO composable.	Mirrors what <OrganizationProfile /> shows on its security route.
Section dedupe	createSection(name, Component) factory + PageContext guard via useRequirePage.	Each leaf is a one-liner instead of repeating wrapper boilerplate.

Suggested review order

1. packages/ui/src/composed/ProfileProviderShell.tsx: the architectural heart.
2. packages/clerk-js/src/core/clerk.ts (__internal_moduleManager getter, clerk.ts:288) + packages/react/src/isomorphicClerk.ts (forwards to the wrapper, :298): confirm the cross-bundle wiring and the ABI tradeoff.
3. packages/ui/src/composed/stubRouter.ts + __tests__/stub-limitations.test.ts: router contract and dev/prod asymmetry.
4. packages/ui/src/composed/{UserProfile,OrganizationProfile}/*Provider.tsx: section wiring + __internal_environment cast.
5. packages/ui/src/composed/__tests__/: parity, wiring, style-cache, flat-export, and tree-shaking tests pin the design.
6. integration/tests/composed-components.test.ts: e2e parity — the composed exports run the same trusted sign-in / profile flows as the standard components against a real clerk-js runtime.

__internal_moduleManager ABI tradeoff

New getter on clerk-js's Clerk class. Once shipped, removing it breaks every pinned SDK version that reads it.

Why accept the cost:

• IsomorphicClerk already proxies every other piece of clerk-js state through public-ish properties. One more is consistent.
• __internal_ prefix signals "may change between majors" — same contract as the rest of __internal_* on Clerk.
• Only channel that reliably crosses the bundle boundary.

Alternatives considered and rejected:

• @clerk/shared WeakMap registry (a prior design, now deleted): doesn't cross the bundle boundary. clerk-js inlines its own @clerk/shared, so the WeakMap clerk-js writes isn't the one @clerk/react/@clerk/ui read. Under version skew / no-dedupe the registry splits and dynamic-import features silently fall back to the rejecting manager.
• Symbol.for(...)-keyed globalThis WeakMap: crosses bundles, but hides the contract in an unnamed channel. Action-at-a-distance, lifecycle issues with test workers and HMR, still on the hook to keep the symbol stable forever — same cost, less inspectable.

Resolves PD-56

Test plan

• CI green
• Smoke test in a Next.js sandbox app without <ClerkProvider ui={ui} />: confirm Web3 Add-Coinbase flow resolves the SDK
• Verify a UserProfileProvider and an OrganizationProfileProvider sibling-mounted on one page: single cl-internal cache, localized strings render
• e2e parity in integration/tests/composed-components.test.ts: the composed UserProfile / OrganizationProfile exports pass the same trusted flows as the standard components (account edits, security, org general/members/security)

[changeset-bot]

🦋 Changeset detected

Latest commit: 2389631

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/ui	Minor
@clerk/clerk-js	Patch
@clerk/shared	Patch
@clerk/react	Patch
@clerk/astro	Patch
@clerk/chrome-extension	Patch
@clerk/swingset	Patch
@clerk/vue	Patch
@clerk/electron	Patch
@clerk/expo	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	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	Jul 7, 2026 8:51pm
swingset	Ready	Preview, Comment	Jul 7, 2026 8:51pm

[alexcarpenter]

!snapshot

[alexcarpenter]

!snapshot

[alexcarpenter]

!snapshot

[alexcarpenter]

!snapshot

[alexcarpenter]

!snapshot

[alexcarpenter]

!snapshot

[github-actions]

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

Package	Version
@clerk/astro	3.4.13-snapshot.v20260707124635
@clerk/backend	3.11.1-snapshot.v20260707124635
@clerk/chrome-extension	3.1.49-snapshot.v20260707124635
@clerk/clerk-js	6.25.0-snapshot.v20260707124635
@clerk/electron	0.0.10-snapshot.v20260707124635
@clerk/electron-passkeys	0.0.4-snapshot.v20260707124635
@clerk/eslint-plugin	0.2.1-snapshot.v20260707124635
@clerk/expo	3.7.1-snapshot.v20260707124635
@clerk/expo-passkeys	1.2.1-snapshot.v20260707124635
@clerk/express	2.1.37-snapshot.v20260707124635
@clerk/fastify	3.1.47-snapshot.v20260707124635
@clerk/headless	0.0.8-snapshot.v20260707124635
@clerk/hono	0.1.47-snapshot.v20260707124635
@clerk/localizations	4.13.0-snapshot.v20260707124635
@clerk/msw	0.0.44-snapshot.v20260707124635
@clerk/nextjs	7.5.14-snapshot.v20260707124635
@clerk/nuxt	2.6.13-snapshot.v20260707124635
@clerk/react	6.12.0-snapshot.v20260707124635
@clerk/react-router	3.5.6-snapshot.v20260707124635
@clerk/shared	4.25.0-snapshot.v20260707124635
@clerk/swingset	0.0.15-snapshot.v20260707124635
@clerk/tanstack-react-start	1.4.14-snapshot.v20260707124635
@clerk/testing	2.2.4-snapshot.v20260707124635
@clerk/ui	1.25.0-snapshot.v20260707124635
@clerk/upgrade	2.0.5-snapshot.v20260707124635
@clerk/vue	2.4.12-snapshot.v20260707124635

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

npm i @clerk/astro@3.4.13-snapshot.v20260707124635 --save-exact

@clerk/backend

npm i @clerk/backend@3.11.1-snapshot.v20260707124635 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@3.1.49-snapshot.v20260707124635 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@6.25.0-snapshot.v20260707124635 --save-exact

@clerk/electron

npm i @clerk/electron@0.0.10-snapshot.v20260707124635 --save-exact

@clerk/electron-passkeys

npm i @clerk/electron-passkeys@0.0.4-snapshot.v20260707124635 --save-exact

@clerk/eslint-plugin

npm i @clerk/eslint-plugin@0.2.1-snapshot.v20260707124635 --save-exact

@clerk/expo

npm i @clerk/expo@3.7.1-snapshot.v20260707124635 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@1.2.1-snapshot.v20260707124635 --save-exact

@clerk/express

npm i @clerk/express@2.1.37-snapshot.v20260707124635 --save-exact

@clerk/fastify

npm i @clerk/fastify@3.1.47-snapshot.v20260707124635 --save-exact

@clerk/headless

npm i @clerk/headless@0.0.8-snapshot.v20260707124635 --save-exact

@clerk/hono

npm i @clerk/hono@0.1.47-snapshot.v20260707124635 --save-exact

@clerk/localizations

npm i @clerk/localizations@4.13.0-snapshot.v20260707124635 --save-exact

@clerk/msw

npm i @clerk/msw@0.0.44-snapshot.v20260707124635 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@7.5.14-snapshot.v20260707124635 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@2.6.13-snapshot.v20260707124635 --save-exact

@clerk/react

npm i @clerk/react@6.12.0-snapshot.v20260707124635 --save-exact

@clerk/react-router

npm i @clerk/react-router@3.5.6-snapshot.v20260707124635 --save-exact

@clerk/shared

npm i @clerk/shared@4.25.0-snapshot.v20260707124635 --save-exact

@clerk/swingset

npm i @clerk/swingset@0.0.15-snapshot.v20260707124635 --save-exact

@clerk/tanstack-react-start

npm i @clerk/tanstack-react-start@1.4.14-snapshot.v20260707124635 --save-exact

@clerk/testing

npm i @clerk/testing@2.2.4-snapshot.v20260707124635 --save-exact

@clerk/ui

npm i @clerk/ui@1.25.0-snapshot.v20260707124635 --save-exact

@clerk/upgrade

npm i @clerk/upgrade@2.0.5-snapshot.v20260707124635 --save-exact

@clerk/vue

npm i @clerk/vue@2.4.12-snapshot.v20260707124635 --save-exact