Docs: react_native_dependencies in a JS monorepo needs package_json pointed at the workspace root

Context

react_native_dependencies works in a JS monorepo where the app depends on sibling packages via workspace:*, but getting there took several wrong turns that the docs do not cover. This is a documentation request, not a bug — the working configuration is below.

What works

In a Bun workspace laid out as:

package.json          # { "workspaces": ["apps/*", "packages/*"] }
bun.lock
apps/mobile/package.json      # depends on "@acme/theme": "workspace:*"
packages/theme/package.json

the target must point package_json at the workspace root, not at the app:

[[target]]
name = "deps"
kind = "react_native_dependencies"
srcs = ["bun.lock", "package.json", "apps/mobile/package.json", "packages/theme/package.json", "packages/theme/index.js"]
[target.attrs]
package_json = "package.json"          # root manifest, carries `workspaces`
lockfile = "bun.lock"
package_manager = "bun"

Every workspace member reachable through workspace:* has to be listed in srcs, since the install runs against the sandboxed subtree.

The failure modes on the way there

Each of these looks like a different problem but has the same cause — the sandbox not containing what the package manager needs:

1. package_json pointing at the app manifest

   error: Workspace dependency "@acme/theme" not found
   Searched in "./*"
   error: @acme/theme@workspace:* failed to resolve
   

   The app manifest has no workspaces field, so the resolver has nothing to glob. The message is accurate but hard to connect to the target attribute that caused it.

2. once.toml in the app directory, lockfile at the repo root

   resolver source `.../apps/mobile/../../bun.lock` resolves outside its owner package
   

   A monorepo has exactly one lockfile at the root, so an app-level once.toml cannot reference it. The target has to live at the root.

3. Workspace members listed but the root manifest omitted

   error: lockfile had changes, but lockfile is frozen
   note: try re-running without --frozen-lockfile
   

   The install runs frozen (correctly), but the partial tree does not match the lockfile, so the mismatch surfaces as a frozen-lockfile error rather than a missing-input one.

Request

A short monorepo section in the React Native guide showing the root-level target above, and noting that package_json must be the manifest that declares workspaces. If the resolver can detect the enclosing workspace root from the app manifest and pull in the members it references, that would remove the sharp edge entirely.

Environment

• once 0.42.0 (x86_64-unknown-linux-gnu release build)
• bun 1.4.0, react-native 0.86.0
• Linux 6.8, x86_64

No GitHub comments yet.