chore: migrate from npm workspaces to pnpm

Motivation: pnpm's recursive runner (`pnpm -r run`) is fail-fast by default
and runs in topological (dependency-graph) order, so the root `bootstrap`
and `prerelease` no longer need the non-fail-fast `npm run <s> --workspaces`
pattern that buried the real root cause under cascading failures.

Workspace + package manager:
- Replace the root `workspaces` array with pnpm-workspace.yaml
- Add `packageManager: pnpm@10.33.0` and switch devEngines to pnpm ^10
- Allow only esbuild's build script via onlyBuiltDependencies (pnpm 10 blocks
  dependency lifecycle scripts by default); no shamefully-hoist needed
- Replace package-lock.json with pnpm-lock.yaml; keep node_modules isolated

Internal deps -> workspace:* protocol (cmake-rn, ferric, gyp-to-cmake, host,
node-addon-examples, node-tests, ferric-example, test-app). Add explicit
`weak-node-api` edges to node-addon-examples and node-tests so the topological
bootstrap sequences weak-node-api (which builds the xcframework/.so they link)
before its consumers.

Phantom dependencies surfaced by pnpm's isolated node_modules (npm hoisting
had masked these):
- host: add `@types/babel__core` (used by src/node/babel-plugin/plugin.ts)
- host: add `weak-node-api` as a devDependency (used by
  scripts/generate-injector.mts; previously only a peerDependency)

Scripts:
- bootstrap: `tsc --build && pnpm -r run bootstrap` (fail-fast, topological)
- prerelease/release: make the build explicit instead of relying on npm's
  implicit prerelease hook (pnpm disables pre/post scripts by default)
- test: `pnpm --filter ... run test`
- depcheck/run-in-published: replace `npm query .workspace` with `pnpm ls -r`
- Pin prettier to 3.6.2: 3.7+ is incompatible with @prettier/plugin-oxc@0.0.4
  (regenerating any lockfile floated it to 3.9.5 and crashed the plugin)

CI: port check.yml and release.yml to pnpm (pnpm/action-setup, cache: pnpm,
`pnpm install --frozen-lockfile`, `--filter`, `pnpm exec`). The ephemeral,
non-workspace macOS test app keeps its own `npm install` in
scripts/init-macos-test-app.ts.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DnwodAoNbqPec77191HVXn

Author: claude

.github/copilot-instructions.md

@@ -33,14 +33,14 @@ See the [README.md](../README.md#packages) for detailed descriptions of each pac
 ### Development Setup
 
 ```bash
-npm ci && npm run build      # Install deps and build all packages
-npm run bootstrap           # Build native components (weak-node-api, examples)
+pnpm install && pnpm run build   # Install deps and build all packages
+pnpm run bootstrap               # Build native components (weak-node-api, examples)
 ```
 
 ### Package Development
 
 - **TypeScript project references**: Use `tsc --build` for incremental compilation
-- **Workspace scripts**: Most build/test commands use npm workspaces (`--workspace` flag)
+- **Workspace scripts**: Most build/test commands use pnpm workspaces (`--filter` flag), run in topological (dependency) order and fail fast
 - **Focus on Node.js packages**: AI development primarily targets the Node.js tooling packages rather than native mobile code
 - **No TypeScript type asserts**: You have to ask explicitly and justify if you want to add `as` type assertions.
 
@@ -70,8 +70,8 @@ Library names use double-dash separation: `package-name--path-component--addon-n
 
 ### Testing
 
-- **Individual packages**: Some packages have VS Code test tasks and others have their own `npm test` scripts for focused iteration (e.g., `npm test --workspace cmake-rn`). Use the latter only if the former is missing.
-- **Cross-package**: Use root-level `npm test` for cross-package testing once individual package tests pass
+- **Individual packages**: Some packages have VS Code test tasks and others have their own test scripts for focused iteration (e.g., `pnpm --filter cmake-rn run test`). Use the latter only if the former is missing.
+- **Cross-package**: Use root-level `pnpm test` for cross-package testing once individual package tests pass
 - **Mobile integration**: Available but not the primary AI development focus - ask the developer to run those tests as needed
 
 **Documentation**: Integration details, platform setup, and toolchain configuration are covered in existing repo documentation files.

.github/workflows/check.yml

@@ -24,9 +24,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: lts/krypton
+          cache: pnpm
       - name: Setup cpp tools
         uses: aminya/setup-cpp@v1
         with:
@@ -47,18 +49,18 @@ jobs:
         with:
           packages: tools platform-tools ndk;${{ env.NDK_VERSION }}
       - run: rustup target add x86_64-linux-android
-      - run: npm ci
-      - run: npm run build
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
       # Bootstrap weak-node-api and ferric-example to get types
       # TODO: Solve this by adding an option to ferric to build only types or by committing the types into the repo as a fixture for an "init" command
-      - run: npm run bootstrap --workspace weak-node-api
-      - run: npm run bootstrap --workspace @react-native-node-api/ferric-example
-      - run: npm run lint
+      - run: pnpm --filter weak-node-api run bootstrap
+      - run: pnpm --filter @react-native-node-api/ferric-example run bootstrap
+      - run: pnpm run lint
         env:
           DEBUG: eslint:eslint
-      - run: npm run prettier:check
-      - run: npm run depcheck
-      - run: npm run publint
+      - run: pnpm run prettier:check
+      - run: pnpm run depcheck
+      - run: pnpm run publint
   unit-tests:
     strategy:
       fail-fast: false
@@ -71,9 +73,11 @@ jobs:
     name: Unit tests (${{ matrix.runner }})
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: lts/krypton
+          cache: pnpm
       - name: Setup cpp tools
         uses: aminya/setup-cpp@v1
         with:
@@ -92,9 +96,15 @@ jobs:
         with:
           packages: tools platform-tools ndk;${{ env.NDK_VERSION }}
       - run: rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi i686-linux-android aarch64-apple-ios-sim
-      - run: npm ci
-      - run: npm run bootstrap
-      - run: npm test
+      # macOS runners ship a newer CMake than the project supports; pin it to match the version used elsewhere in CI
+      - name: Install compatible CMake version
+        if: runner.os == 'macOS'
+        uses: jwlawson/actions-setup-cmake@v2
+        with:
+          cmake-version: ${{ env.CMAKE_VERSION }}
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run bootstrap
+      - run: pnpm test
   weak-node-api-tests:
     if: github.ref == 'refs/heads/main' || contains(github.event.pull_request.labels.*.name, 'weak-node-api')
     strategy:
@@ -108,9 +118,11 @@ jobs:
     name: Weak Node-API tests (${{ matrix.runner }})
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: lts/krypton
+          cache: pnpm
       - name: Setup cpp tools
         uses: aminya/setup-cpp@v1
         with:
@@ -119,10 +131,16 @@ jobs:
         uses: hendrikmuhs/ccache-action@v1.2
         with:
           key: ${{ github.job }}-${{ runner.os }}
-      - run: npm ci
-      - run: npm run build
+      # macOS runners ship a newer CMake than the project supports; pin it to match the version used elsewhere in CI
+      - name: Install compatible CMake version
+        if: runner.os == 'macOS'
+        uses: jwlawson/actions-setup-cmake@v2
+        with:
+          cmake-version: ${{ env.CMAKE_VERSION }}
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
       - name: Prepare weak-node-api
-        run: npm run prebuild:prepare --workspace weak-node-api
+        run: pnpm --filter weak-node-api run prebuild:prepare
       - name: Build and run weak-node-api C++ tests
         run: |
           cmake -S . -B build -DBUILD_TESTS=ON
@@ -135,9 +153,11 @@ jobs:
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: lts/krypton
+          cache: pnpm
       - name: Setup cpp tools
         uses: aminya/setup-cpp@v1
         with:
@@ -156,17 +176,22 @@ jobs:
         with:
           packages: tools platform-tools ndk;${{ env.NDK_VERSION }}
       - run: rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi i686-linux-android aarch64-apple-ios-sim
-      - run: npm ci
-      - run: npm run bootstrap
+      # macOS runners ship a newer CMake than the project supports; pin it to match the version used elsewhere in CI
+      - name: Install compatible CMake version
+        uses: jwlawson/actions-setup-cmake@v2
+        with:
+          cmake-version: ${{ env.CMAKE_VERSION }}
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run bootstrap
         env:
           CMAKE_RN_TRIPLETS: arm64;x86_64-apple-ios-sim
           FERRIC_TARGETS: aarch64-apple-ios-sim
-      - run: npm run pod-install
+      - run: pnpm run pod-install
         working-directory: apps/test-app
       - name: Run tests (iOS)
-        run: npm run test:ios:allTests
+        run: pnpm run test:ios:allTests
         # TODO: Enable release mode when it works
-        # run: npm run test:ios:allTests -- --mode Release
+        # run: pnpm run test:ios:allTests -- --mode Release
         working-directory: apps/test-app
   test-macos:
     # Disabling this on main for now, as initializing the template takes a long time and
@@ -176,9 +201,11 @@ jobs:
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: lts/krypton
+          cache: pnpm
       - name: Setup cpp tools
         uses: aminya/setup-cpp@v1
         with:
@@ -192,13 +219,17 @@ jobs:
         with:
           java-version: "17"
           distribution: "temurin"
+      - name: Install compatible CMake version
+        uses: jwlawson/actions-setup-cmake@v2
+        with:
+          cmake-version: ${{ env.CMAKE_VERSION }}
       - run: rustup target add x86_64-apple-darwin
-      - run: npm ci
-      - run: npm run bootstrap
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run bootstrap
         env:
           CMAKE_RN_TRIPLETS: arm64;x86_64-apple-darwin
           FERRIC_TARGETS: aarch64-apple-darwin,x86_64-apple-darwin
-      - run: npm run init-macos-test-app
+      - run: pnpm run init-macos-test-app
       - run: pod install --project-directory=macos
         working-directory: apps/macos-test-app
       - name: Bundle test app
@@ -213,18 +244,16 @@ jobs:
         env:
           MOCHA_REMOTE_CONTEXT: allTests
   test-android:
-    # Temporarily gated to labeled PRs only: the ubuntu-self-hosted runner is
-    # offline, so running this on main pushes leaves the job queued forever and
-    # blocks the whole Check run from completing. Re-enable on main once the
-    # self-hosted runner is back. Tracked in #379.
-    if: contains(github.event.pull_request.labels.*.name, 'Android 🤖')
+    if: github.ref == 'refs/heads/main' || contains(github.event.pull_request.labels.*.name, 'Android 🤖')
     name: Test app (Android)
     runs-on: ubuntu-self-hosted
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: lts/krypton
+          cache: pnpm
       - name: Setup cpp tools
         uses: aminya/setup-cpp@v1
         with:
@@ -243,15 +272,15 @@ jobs:
         with:
           packages: tools platform-tools ndk;${{ env.NDK_VERSION }} cmake;${{ env.CMAKE_VERSION }}
       - run: rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi i686-linux-android aarch64-apple-ios-sim
-      - run: npm ci
-      - run: npm run bootstrap
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run bootstrap
         env:
           CMAKE_RN_TRIPLETS: x86_64-linux-android
           FERRIC_TARGETS: x86_64-linux-android
       - name: Clone patched Hermes version
         shell: bash
         run: |
-          REACT_NATIVE_OVERRIDE_HERMES_DIR=$(npx react-native-node-api vendor-hermes --silent)
+          REACT_NATIVE_OVERRIDE_HERMES_DIR=$(pnpm exec react-native-node-api vendor-hermes --silent)
           echo "REACT_NATIVE_OVERRIDE_HERMES_DIR=$REACT_NATIVE_OVERRIDE_HERMES_DIR" >> $GITHUB_ENV
         working-directory: apps/test-app
       # - name: Setup Android Emulator cache
@@ -269,9 +298,9 @@ jobs:
           sudo udevadm control --reload-rules
           sudo udevadm trigger --name-match=kvm
       - name: Build weak-node-api for all Android architectures
-        run: npm run prebuild:build:android --workspace weak-node-api
+        run: pnpm --filter weak-node-api run prebuild:build:android
       - name: Build ferric-example for all architectures
-        run: npm run build -- --android
+        run: pnpm run build -- --android
         working-directory: packages/ferric-example
       - name: Run tests (Android)
         timeout-minutes: 75
@@ -293,7 +322,7 @@ jobs:
             adb logcat > emulator-logcat.txt 2>&1 &
             LOGCAT_PID=$!
             # Build, install and run the app
-            npm run test:android:allTests -- --mode Release
+            pnpm run test:android:allTests -- --mode Release
             # Wait a bit for the sub-process to terminate, before terminating the emulator
             sleep 5
             # Stop logcat
@@ -310,9 +339,11 @@ jobs:
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: lts/krypton
+          cache: pnpm
       - name: Setup cpp tools
         uses: aminya/setup-cpp@v1
         with:
@@ -328,14 +359,19 @@ jobs:
           distribution: "temurin"
       - run: rustup target add x86_64-apple-darwin x86_64-apple-ios aarch64-apple-ios aarch64-apple-ios-sim
       - run: rustup toolchain install nightly --component rust-src
-      - run: npm ci
-      - run: npm run build
+      # macOS runners ship a newer CMake than the project supports; pin it to match the version used elsewhere in CI
+      - name: Install compatible CMake version
+        uses: jwlawson/actions-setup-cmake@v2
+        with:
+          cmake-version: ${{ env.CMAKE_VERSION }}
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run build
       - name: Build weak-node-api for all Apple architectures
         run: |
-          npm run prebuild:prepare --workspace weak-node-api
-          npm run prebuild:build:apple --workspace weak-node-api
+          pnpm --filter weak-node-api run prebuild:prepare
+          pnpm --filter weak-node-api run prebuild:build:apple
       # Build Ferric example for all Apple architectures
-      - run: npx ferric --apple
+      - run: pnpm exec ferric --apple
         working-directory: packages/ferric-example
       - name: Inspect the structure of the prebuilt binary
         run: lipo -info ferric_example.apple.node/*/libferric_example.framework/libferric_example > lipo-info.txt

.github/workflows/release.yml

@@ -18,9 +18,11 @@ jobs:
     environment: main
     steps:
       - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
           node-version: lts/krypton
+          cache: pnpm
       - name: Setup cpp tools
         uses: aminya/setup-cpp@v1
         with:
@@ -39,12 +41,12 @@ jobs:
         with:
           packages: tools platform-tools ndk;${{ env.NDK_VERSION }}
       - run: rustup target add x86_64-linux-android aarch64-linux-android armv7-linux-androideabi i686-linux-android aarch64-apple-ios-sim
-      - run: npm install
+      - run: pnpm install
 
       - name: Create Release Pull Request or Publish to NPM
         id: changesets
         uses: changesets/action@v1
         with:
-          publish: npm run release
+          publish: pnpm run release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.prettierignore

@@ -5,6 +5,9 @@ Pods
 target
 .cxx
 
+# Ignore the pnpm lockfile (managed by pnpm, not formatted by Prettier)
+pnpm-lock.yaml
+
 # Ignore hermes
 packages/host/hermes
 packages/node-addon-examples/examples

apps/test-app/package.json

@@ -27,9 +27,9 @@
     "@react-native-community/cli": "^20.0.2",
     "@react-native-community/cli-platform-android": "^20.0.2",
     "@react-native-community/cli-platform-ios": "^20.0.2",
-    "@react-native-node-api/ferric-example": "*",
-    "@react-native-node-api/node-addon-examples": "*",
-    "@react-native-node-api/node-tests": "*",
+    "@react-native-node-api/ferric-example": "workspace:*",
+    "@react-native-node-api/node-addon-examples": "workspace:*",
+    "@react-native-node-api/node-tests": "workspace:*",
     "@react-native/babel-preset": "0.81.4",
     "@react-native/metro-config": "0.81.4",
     "@react-native/typescript-config": "0.81.4",
@@ -42,8 +42,8 @@
     "mocha-remote-react-native": "^1.13.2",
     "react": "19.1.0",
     "react-native": "0.81.4",
-    "react-native-node-api": "*",
+    "react-native-node-api": "workspace:*",
     "react-native-test-app": "^4.4.7",
-    "weak-node-api": "*"
+    "weak-node-api": "workspace:*"
   }
 }