fix(expo): add subpath directory fallbacks for bundlers without exports support

[jacekradko]

Summary

• Adds directory-level package.json fallback stubs for all @clerk/expo subpath exports (token-cache, web, passkeys, local-credentials, secure-store, resource-cache, google, apple, experimental, legacy)
• Ensures subpath imports like @clerk/expo/token-cache resolve correctly when Metro's unstable_enablePackageExports is disabled
• Follows the existing pattern already used by @clerk/expo/native

Context

Closes #8164

Metro's support for the exports field in package.json is gated behind unstable_enablePackageExports, which is experimental and commonly disabled when it causes issues with other packages. When disabled, Metro falls back to traditional Node.js resolution — looking for a physical directory with a package.json containing a main field.

The ./native subpath already had this fallback, but the other 10 subpath exports did not, causing resolution failures for users with unstable_enablePackageExports disabled.

Test plan

• pnpm build passes for @clerk/expo
• Verify @clerk/expo/token-cache resolves in an Expo app with unstable_enablePackageExports disabled

Summary by CodeRabbit

• Chores
  • Added package metadata files to expose module entry points and TypeScript declarations for Expo submodules: Apple, Google, Web, Legacy, Experimental, Passkeys, Local Credentials, Secure Store, Token Cache, and Resource Cache.
  • Added a changeset and updated the main package manifest to ensure those submodule directories are included in published distributions.

[vercel]

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

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

[changeset-bot]

🦋 Changeset detected

Latest commit: a147a04

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

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: a147a04

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 738e2276-bdf4-4910-a036-0658e01b1da2

📥 Commits

Reviewing files that changed from the base of the PR and between 7f74cd9 and a147a04.

📒 Files selected for processing (1)

• .changeset/expo-subpath-fallbacks.md

---

📝 Walkthrough

Walkthrough

This pull request adds multiple package.json configuration files to subdirectories within the @clerk/expo package, establishing package entry points for each module. Each new file defines main and types fields pointing to corresponding built JavaScript and TypeScript declaration files in the distribution directory. The root packages/expo/package.json is also updated to include the experimental and legacy directories in its published files list.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 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 main change: adding directory-level package.json fallbacks for @clerk/expo subpaths to support bundlers without exports support.
Linked Issues check	✅ Passed	The PR successfully addresses issue #8164 by adding directory-level package.json fallback stubs for all @clerk/expo subpath exports, enabling resolution when Metro's exports support is disabled.
Out of Scope Changes check	✅ Passed	All changes are directly in scope: adding package.json files for subpath fallbacks and updating the main package.json files list, with no unrelated modifications.
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.}

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/expo/package.json`:
- Around line 95-96: Add a regression test that simulates Metro package
resolution with unstable_enablePackageExports disabled and asserts that
`@clerk/expo/token-cache` still resolves correctly: create a unit/integration test
in the expo package test suite that sets unstable_enablePackageExports = false
(or toggles the equivalent config), invokes the resolver logic used by the
package (the same code path affected by the "experimental"/"legacy" package.json
export entries), and verifies the module resolution and import behave as
expected; ensure the test fails before the fix and passes after, and include it
in CI so this regression is prevented.

In `@packages/expo/token-cache/package.json`:
- Around line 1-4: Add an integration/regression test that verifies Metro can
resolve `@clerk/expo/token-cache` (and a representative subpath) when
unstable_enablePackageExports is false; specifically, create a test that starts
Metro with unstable_enablePackageExports disabled, attempts to require/import
the package (resolving the "main" and a subpath) and asserts the module loads
successfully (using the package.json "main" ../dist/token-cache/index.js and a
chosen subpath under ../dist/token-cache). Ensure the test lives with other
Metro integration tests and fails if fallback resolution from package exports is
not performed so this regression is covered before merge.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 48eca6d3-b488-4501-8f40-ea5a917172fc

📥 Commits

Reviewing files that changed from the base of the PR and between 1827b50 and 7f74cd9.

📒 Files selected for processing (11)

• packages/expo/apple/package.json
• packages/expo/experimental/package.json
• packages/expo/google/package.json
• packages/expo/legacy/package.json
• packages/expo/local-credentials/package.json
• packages/expo/package.json
• packages/expo/passkeys/package.json
• packages/expo/resource-cache/package.json
• packages/expo/secure-store/package.json
• packages/expo/token-cache/package.json
• packages/expo/web/package.json

[chriscanin]

Reviewing / testing.

[chriscanin]

@jacekradko this is tested, and working on both ios and android, native builds, and js only quickstart.

[chriscanin]

This is looking good! Tested on ios and android, native quickstart and js only quickstart.