fix(expo): make react-dom optional for native apps by mikepitre · Pull Request #8789 · clerk/javascript

mikepitre · 2026-06-09T19:57:38Z

Summary

Make react-dom an optional peer dependency in @clerk/expo so native Expo apps that do not use React DOM are not blocked by npm peer resolution while installing Clerk.

Why this is scoped to `@clerk/expo`

The direct install target for Expo apps is @clerk/expo, so this PR starts by marking react-dom optional on the Expo package itself. This mirrors the shape of Expo packages that expose both native and web entrypoints but should not require React DOM for native-only usage.

@clerk/expo also depends on @clerk/react, which still declares a react-dom peer. I tested the narrower Expo-only change first as requested. With only @clerk/expo patched, npm no longer fails the install with --legacy-peer-deps omitted, but npm still resolves react-dom@19.2.7 through the remaining transitive peer chain and npm ls reports an invalid tree against the app's react@19.2.3.

Root cause

Some native Expo apps do not install react-dom. When installing the current PR build of @clerk/expo into an Expo SDK 56 app with react@19.2.3 and no react-dom, npm selects the latest compatible react-dom, currently react-dom@19.2.7. That package requires react@^19.2.7, which conflicts with the app's react@19.2.3 and causes npm to fail unless --legacy-peer-deps is used.

The default SDK 56 template already includes react-dom@19.2.3, so it does not reproduce this particular resolver failure.

Summary by CodeRabbit

Chores
- Updated @clerk/expo and @clerk/react with patch version bumps
- Configured react-dom as an optional peer dependency to prevent unnecessary packages from being installed in native Expo applications

changeset-bot · 2026-06-09T19:57:45Z

🦋 Changeset detected

Latest commit: aad8157

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

This PR includes changesets to release 1 package

Name	Type
@clerk/expo	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-06-09T19:57:46Z

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

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

coderabbitai · 2026-06-09T19:57:48Z

📝 Walkthrough

Walkthrough

This PR marks react-dom as an optional peer dependency in the @clerk/expo and @clerk/react packages to prevent unnecessary installation in native Expo environments. The changeset documents patch version bumps, and packages/expo/package.json adds react-dom metadata marked as optional.

Changes

Optional react-dom peer dependency

Layer / File(s)	Summary
Optional react-dom peer dependency metadata `.changeset/expo-optional-react-dom-peer.md`, `packages/expo/package.json`	Changeset declares patch updates for `@clerk/expo` and `@clerk/react` with a note documenting that `react-dom` is an optional peer dependency. Package metadata in `peerDependenciesMeta` adds `react-dom` marked as `optional: true`.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

A rabbit hops through deps so fine,
React-dom now optional, by design! 🐰
Expo apps stay light and lean,
Cleanest peer dep ever seen! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(expo): make react-dom optional for native apps' accurately and concisely summarizes the main change: making react-dom optional in Expo packages to resolve peer dependency issues in native apps.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
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.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

pkg-pr-new · 2026-06-09T20:02:37Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: aad8157

github-actions · 2026-06-09T20:15:23Z

API Changes Report

Generated by Break Check on 2026-06-09T20:27:00.643Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	2
🔴 Breaking changes	6
🟡 Non-breaking changes	0
🟢 Additions	0

Warning
6 breaking change(s) detected - Major version bump required

🤖 This report was reviewed by claude-sonnet-4-6.

Note
Break Check could not snapshot 3 subpaths; the diff below excludes them.
@clerk/astro ./env: Internal Error: Unable to determine module for: /home/runner/_work/javascript/javascript/packages/astro/env.d.ts You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
@clerk/shared ./cookie: Internal Error: Unable to follow symbol for "Cookies" You have encountered a software defect. Please consider reporting the issue to the maintainers of this application.
@clerk/testing ./cypress: Symbol not found for identifier: Cypress

🔴 Breaking changes index (6)

Every breaking change, up front. Full diffs are in the package sections below.

Package	Subpath	Change
@clerk/astro	`./client`	`$authStore`
@clerk/astro	`./client`	`$organizationStore`
@clerk/astro	`./client`	`$userStore`
@clerk/shared	`./react`	`UseOrganizationEnterpriseConnectionTestRunsParams`
@clerk/shared	`./react`	`UseOrganizationEnterpriseConnectionTestRunsReturn`
@clerk/shared	`./types`	`CreateOrganizationEnterpriseConnectionParams`

@clerk/astro

Current version: 3.3.3
Recommended bump: MAJOR → 4.0.0

Subpath `./client`

🔴 Breaking Changes (3)

Changed: `$authStore`

 $authStore: nanostores.ReadableAtom<{
userId: string | null | undefined;
- user: _clerk_shared__chunks_index_U8nAlSHe.hs | null | undefined;+ user: _clerk_shared__chunks_index_BTxz__kZ.hs | null | undefined;
sessionId: string | null | undefined;
- session: _clerk_shared__chunks_index_U8nAlSHe.es | null | undefined;+ session: _clerk_shared__chunks_index_BTxz__kZ.es | null | undefined;
sessionStatus: "active" | "pending" | undefined;
- sessionClaims: _clerk_shared__chunks_index_U8nAlSHe.ro | null | undefined;- organization: _clerk_shared__chunks_index_U8nAlSHe.Co | null | undefined;+ sessionClaims: _clerk_shared__chunks_index_BTxz__kZ.ro | null | undefined;+ organization: _clerk_shared__chunks_index_BTxz__kZ.Co | null | undefined;
orgId: string | null | undefined;
orgRole: string | null | undefined;
orgSlug: string | null | undefined;
- orgPermissions: _clerk_shared__chunks_index_U8nAlSHe.ym<_clerk_shared__chunks_index_U8nAlSHe.uo>[] | null | undefined;- actor: _clerk_shared__chunks_index_U8nAlSHe.Qa | null | undefined;+ orgPermissions: _clerk_shared__chunks_index_BTxz__kZ.ym<_clerk_shared__chunks_index_BTxz__kZ.uo>[] | null | undefined;+ actor: _clerk_shared__chunks_index_BTxz__kZ.Qa | null | undefined;
factorVerificationAge: [number, number] | null;
}>

Static analyzer: Breaking change in variable $authStore: Type changed: $authStore:import("nanostores").ReadableAtom<{userId:string|null|undefined;user:!_clerk_shared__chunks_index_U8nAlSHe.h… → $authStore:import("nanostores").ReadableAtom<{userId:string|null|undefined;user:!_clerk_shared__chunks_index_BTxz__kZ.h…

🤖 AI review (confirmed) (95%): The referenced chunk module _clerk_shared__chunks_index_U8nAlSHe has been replaced with _clerk_shared__chunks_index_BTxz__kZ, a content-hashed internal bundle chunk. Per rule 12, these are non-resolvable specifiers and structural equivalence cannot excuse the change; consumer code referencing the old chunk path will fail to compile.

Migration: Upgrade any direct references to the internal _clerk_shared__chunks_index_U8nAlSHe chunk to use the new chunk or, preferably, reference only the public entry-point types exposed by @clerk/astro.

Changed: `$organizationStore`

- $organizationStore: nanostores.ReadableAtom<_clerk_shared__chunks_index_U8nAlSHe.Co | null | undefined>+ $organizationStore: nanostores.ReadableAtom<_clerk_shared__chunks_index_BTxz__kZ.Co | null | undefined>

Static analyzer: Breaking change in variable $organizationStore: Type changed: $organizationStore:import("nanostores").ReadableAtom<!_clerk_shared__chunks_index_U8nAlSHe.Co:type|null|undefined> → $organizationStore:import("nanostores").ReadableAtom<!_clerk_shared__chunks_index_BTxz__kZ.Co:type|null|undefined>

🤖 AI review (confirmed) (95%): The type parameter of $organizationStore now references _clerk_shared__chunks_index_BTxz__kZ.Co instead of _clerk_shared__chunks_index_U8nAlSHe.Co; both chunk specifiers contain a content-hashed segment that is non-resolvable by consumers (rule 12), making this a breaking import path change.

Migration: Avoid importing types directly from internal _chunks paths; rely solely on the public @clerk/astro entry-point types for Organization.

Changed: `$userStore`

- $userStore: nanostores.ReadableAtom<_clerk_shared__chunks_index_U8nAlSHe.hs | null | undefined>+ $userStore: nanostores.ReadableAtom<_clerk_shared__chunks_index_BTxz__kZ.hs | null | undefined>

Static analyzer: Breaking change in variable $userStore: Type changed: $userStore:import("nanostores").ReadableAtom<!_clerk_shared__chunks_index_U8nAlSHe.hs:type|null|undefined> → $userStore:import("nanostores").ReadableAtom<!_clerk_shared__chunks_index_BTxz__kZ.hs:type|null|undefined>

🤖 AI review (confirmed) (95%): The type parameter of $userStore now references _clerk_shared__chunks_index_BTxz__kZ.hs instead of _clerk_shared__chunks_index_U8nAlSHe.hs; the old chunk specifier is a non-resolvable content-hashed internal path (rule 12), breaking consumers who previously resolved the User type from it.

Migration: Avoid importing types directly from internal _chunks paths; rely solely on the public @clerk/astro entry-point types for User.

@clerk/shared

Current version: 4.15.0
Recommended bump: MAJOR → 5.0.0

Subpath `./react`

🔴 Breaking Changes (2)

Changed: `UseOrganizationEnterpriseConnectionTestRunsParams`

// ... 2 unchanged lines elided ...
params?: GetEnterpriseConnectionTestRunsParams;
pollIntervalMs?: number;
enabled?: boolean;
- keepPreviousData?: boolean;
};

Static analyzer: Breaking change in type alias UseOrganizationEnterpriseConnectionTestRunsParams: Type changed: {enterpriseConnectionId:string|null;params?:import("@clerk/shared").~GetEnterpriseConnectionTestRunsParams;pollInterval… → {enterpriseConnectionId:string|null;params?:import("@clerk/shared").~GetEnterpriseConnectionTestRunsParams;pollInterval…

🤖 AI review (confirmed) (95%): The keepPreviousData optional property was removed from UseOrganizationEnterpriseConnectionTestRunsParams; consumers who passed { keepPreviousData: true } will get a type error since the property no longer exists on the type.

Migration: Remove keepPreviousData from any object passed as UseOrganizationEnterpriseConnectionTestRunsParams; the property is no longer accepted.

Changed: `UseOrganizationEnterpriseConnectionTestRunsReturn`

// ... 4 unchanged lines elided ...
isLoading: boolean;
isFetching: boolean;
isPolling: boolean;
- revalidate: (options?: RevalidateTestRunsOptions) => Promise<void>;+ revalidate: () => Promise<void>;
};

Static analyzer: Breaking change in type alias UseOrganizationEnterpriseConnectionTestRunsReturn: Type changed: {data:import("@clerk/shared").~EnterpriseConnectionTestRunResource[]|undefined;totalCount:number|undefined;error:!Error… → {data:import("@clerk/shared").~EnterpriseConnectionTestRunResource[]|undefined;totalCount:number|undefined;error:!Error…

🤖 AI review (confirmed) (97%): The revalidate method's parameter options?: RevalidateTestRunsOptions was removed, so callers who invoke revalidate(options) with an argument will get a type error since the function no longer accepts any parameters.

Migration: Update all call sites that pass an argument to revalidate(...) to call it without arguments: revalidate().

Subpath `./types`

🔴 Breaking Changes (1)

Changed: `CreateOrganizationEnterpriseConnectionParams`

 type CreateOrganizationEnterpriseConnectionParams = {
provider: OrganizationEnterpriseConnectionProvider;
name: string;
- domains?: string[];
organizationId?: string | null;
saml?: OrganizationEnterpriseConnectionSamlInput | null;
oidc?: OrganizationEnterpriseConnectionOidcInput | null;
// ... 1 unchanged line elided ...

Static analyzer: Breaking change in type alias CreateOrganizationEnterpriseConnectionParams: Type changed: {provider:import("@clerk/shared").OrganizationEnterpriseConnectionProvider;name:string;domains?:string[];organizationId… → {provider:import("@clerk/shared").OrganizationEnterpriseConnectionProvider;name:string;organizationId?:string|null;saml…

🤖 AI review (confirmed) (95%): The optional domains?: string[] property was removed from CreateOrganizationEnterpriseConnectionParams, which is used as an input parameter to createEnterpriseConnection and CreateMeEnterpriseConnectionParams; consumers who passed domains in that object will have their code break at compile time.

Migration: Remove the domains property from any objects passed to createEnterpriseConnection or CreateMeEnterpriseConnectionParams.

Report generated by Break Check

_{Last ran on aad8157.}

wobsoriano

thanks for the fix!

github-actionsBot added react expo labels Jun 9, 2026

vercelBotdeployed to Preview June 9, 2026 19:58 View deployment

mikepitre requested a review from wobsoriano June 9, 2026 20:11

mikepitre marked this pull request as ready for review June 9, 2026 20:11

fix(expo): make react-dom optional for native apps
aad8157

mikepitre force-pushed the mike/expo-optional-react-dom-peer branch from 166b0ae to aad8157Compare June 9, 2026 20:20

vercelBotdeployed to Preview June 9, 2026 20:21 View deployment

wobsoriano approved these changes Jun 9, 2026
View reviewed changes

wobsoriano merged commit 400d10c into mainJun 9, 2026
54 checks passed

wobsoriano deleted the mike/expo-optional-react-dom-peer branch June 9, 2026 20:54

clerk-cookie mentioned this pull request Jun 9, 2026
ci(repo): Version packages #8735
Merged

coderabbitaiBot mentioned this pull request Jul 12, 2026
Dev Lionel2026/Language-Larp#2
Merged

coderabbitaiBot mentioned this pull request Jul 28, 2026
Implemetned Clerk Authentication abuhasansarkar/Subscription-Management-Mobile-App#4
Merged

Navigation Menu

Uh oh!

fix(expo): make react-dom optional for native apps - #8789

fix(expo): make react-dom optional for native apps#8789
wobsoriano merged 1 commit into
mainfrom
mike/expo-optional-react-dom-peer

mikepitre commented Jun 9, 2026•
edited by coderabbitai Bot
Loading

Uh oh!

changeset-botBot commented Jun 9, 2026•
edited
Loading

Uh oh!

vercelBot commented Jun 9, 2026•
edited
Loading

Uh oh!

coderabbitaiBot commented Jun 9, 2026•
edited
Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

pkg-pr-newBot commented Jun 9, 2026•
edited
Loading

Uh oh!

github-actionsBot commented Jun 9, 2026•
edited
Loading

Uh oh!

wobsoriano left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

mikepitre commented Jun 9, 2026• edited by coderabbitai BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why this is scoped to @clerk/expo

Root cause

Summary by CodeRabbit

Uh oh!

changeset-botBot commented Jun 9, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

pkg-pr-newBot commented Jun 9, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actionsBot commented Jun 9, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

🔴 Breaking changes index (6)

@clerk/astro

Subpath ./client

🔴 Breaking Changes (3)

Changed: $authStore

Changed: $organizationStore

Changed: $userStore

@clerk/shared

Subpath ./react

🔴 Breaking Changes (2)

Changed: UseOrganizationEnterpriseConnectionTestRunsParams

Changed: UseOrganizationEnterpriseConnectionTestRunsReturn

Subpath ./types

🔴 Breaking Changes (1)

Changed: CreateOrganizationEnterpriseConnectionParams

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mikepitre commented Jun 9, 2026•
edited by coderabbitai Bot
Loading

Why this is scoped to `@clerk/expo`

changeset-botBot commented Jun 9, 2026•
edited
Loading

vercelBot commented Jun 9, 2026•
edited
Loading

coderabbitaiBot commented Jun 9, 2026•
edited
Loading

pkg-pr-newBot commented Jun 9, 2026•
edited
Loading

github-actionsBot commented Jun 9, 2026•
edited
Loading

Subpath `./client`

Changed: `$authStore`

Changed: `$organizationStore`

Changed: `$userStore`

Subpath `./react`

Changed: `UseOrganizationEnterpriseConnectionTestRunsParams`

Changed: `UseOrganizationEnterpriseConnectionTestRunsReturn`

Subpath `./types`

Changed: `CreateOrganizationEnterpriseConnectionParams`