Add a cmake-rn init command (#488)

Scaffolds a package building a CMake Node-API module, or brings an existing
one up to what `cmake-rn build` expects, mirroring `ferric init`.

- The build moves into a default `build` subcommand, so existing `cmake-rn`
  invocations keep working.
- `--weak-node-api <link|cmake-js|omit>` picks how a new CMakeLists.txt gets
  Node-API. An existing CMakeLists.txt is inspected against it rather than
  replaced.
- Workspace handling, package.json updates and plan output move from ferric
  into @react-native-node-api/cli-utils, shared by both init commands.
- packages/cmake-rn-example is generated by `pnpm run init-cmake-rn-example`,
  checked for drift in the Lint job, built by the native CI jobs and loaded
  by the test app.

Closes #483

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

Author: kraenhansen

.changeset/cli-utils-init-helpers.md

@@ -0,0 +1,5 @@
+---
+"@react-native-node-api/cli-utils": minor
+---
+
+Add the helpers shared by the `ferric init` and `cmake-rn init` commands: planning file changes, updating a `package.json` without overwriting what it declares, printing diffs, and adding a package to a pnpm, npm or yarn workspace.

.changeset/cmake-rn-init-command.md

@@ -0,0 +1,9 @@
+---
+"cmake-rn": minor
+---
+
+Add a `cmake-rn init [path]` command, scaffolding a package building a CMake Node-API module.
+
+It writes the `package.json`, `CMakeLists.txt`, `src/addon.c`, a JavaScript entrypoint with its TypeScript declarations and `.gitignore` a package needs, and adds it to the workspace of the mono-repo it is initialized into. Run against a package that already exists, it bumps outdated dependencies, and inspects an existing `CMakeLists.txt` instead of replacing it, pointing out when it doesn't define or link the `weak-node-api` target. `--weak-node-api <link|cmake-js|omit>` picks how a new `CMakeLists.txt` gets Node-API: linking the `weak-node-api` target (the default), through the cmake-js variables so it also builds with cmake-js, or not at all. A differing entrypoint or source file is skipped with a diff to merge by hand, unless `--force` is passed. `--dry-run` prints all of this without writing anything.
+
+The build is now the default `build` subcommand, so `cmake-rn` invocations keep working as before, and its options are listed by `cmake-rn build --help`.

.github/workflows/check.yml

@@ -81,6 +81,12 @@ jobs:
           git status --porcelain packages/ferric-example
           git diff --exit-code packages/ferric-example
           test -z "$(git status --porcelain packages/ferric-example)"
+      - run: pnpm run init-cmake-rn-example
+      - name: Verify cmake-rn-example matches what cmake-rn init generates
+        run: |
+          git status --porcelain packages/cmake-rn-example
+          git diff --exit-code packages/cmake-rn-example
+          test -z "$(git status --porcelain packages/cmake-rn-example)"
       - run: pnpm run lint
         env:
           DEBUG: eslint:eslint

README.md

@@ -75,3 +75,7 @@ A test app using `react-native-test-app` to exercise the implementation of it al
 ### [`@react-native-node-api/ferric-example`](packages/ferric-example)
 
 A simple example of using the `ferric` CLI to build a Node-API module for React Native in Rust.
+
+### [`@react-native-node-api/cmake-rn-example`](packages/cmake-rn-example)
+
+A simple example of using the `cmake-rn` CLI to build a Node-API module for React Native in C, generated by `cmake-rn init`.

apps/test-app/App.tsx

@@ -24,13 +24,15 @@ type Context = {
   nodeAddonExamples?: boolean;
   nodeTests?: boolean;
   ferricExample?: boolean;
+  cmakeRnExample?: boolean;
 };
 
 function loadTests({
   allTests = false,
   nodeAddonExamples = allTests,
   nodeTests = allTests,
   ferricExample = allTests,
+  cmakeRnExample = allTests,
 }: Context) {
   describeIf(nodeAddonExamples, "Node Addon Examples", () => {
     for (const [suiteName, examples] of Object.entries(
@@ -85,6 +87,18 @@ function loadTests({
       }
     });
   });
+
+  describeIf(cmakeRnExample, "cmake-rn-example", () => {
+    it("exports a callable sum function", () => {
+      const exampleAddon =
+        /* eslint-disable-next-line @typescript-eslint/no-require-imports -- TODO: Determine why a dynamic import doesn't work on Android */
+        require("@react-native-node-api/cmake-rn-example") as typeof import("@react-native-node-api/cmake-rn-example");
+      const result = exampleAddon.sum(1, 3);
+      if (result !== 4) {
+        throw new Error(`Expected 1 + 3 to equal 4, but got ${result}`);
+      }
+    });
+  });
 }
 
 export default function App() {

apps/test-app/package.json

@@ -15,11 +15,13 @@
     "test:android:nodeAddonExamples": "MOCHA_REMOTE_CONTEXT=nodeAddonExamples node --run test:android -- ",
     "test:android:nodeTests": "MOCHA_REMOTE_CONTEXT=nodeTests node --run test:android -- ",
     "test:android:ferricExample": "MOCHA_REMOTE_CONTEXT=ferricExample node --run test:android -- ",
+    "test:android:cmakeRnExample": "MOCHA_REMOTE_CONTEXT=cmakeRnExample node --run test:android -- ",
     "test:ios": "mocha-remote --exit-on-error -- concurrently --passthrough-arguments --kill-others-on-fail npm:metro 'npm:ios -- {@}' --",
     "test:ios:allTests": "MOCHA_REMOTE_CONTEXT=allTests node --run test:ios -- ",
     "test:ios:nodeAddonExamples": "MOCHA_REMOTE_CONTEXT=nodeAddonExamples node --run test:ios -- ",
     "test:ios:nodeTests": "MOCHA_REMOTE_CONTEXT=nodeTests node --run test:ios -- ",
-    "test:ios:ferricExample": "MOCHA_REMOTE_CONTEXT=ferricExample node --run test:ios -- "
+    "test:ios:ferricExample": "MOCHA_REMOTE_CONTEXT=ferricExample node --run test:ios -- ",
+    "test:ios:cmakeRnExample": "MOCHA_REMOTE_CONTEXT=cmakeRnExample node --run test:ios -- "
   },
   "dependencies": {
     "@babel/core": "^7.26.10",
@@ -28,6 +30,7 @@
     "@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/cmake-rn-example": "workspace:*",
     "@react-native-node-api/ferric-example": "workspace:*",
     "@react-native-node-api/node-addon-examples": "workspace:*",
     "@react-native-node-api/node-tests": "workspace:*",

docs/USAGE.md

@@ -39,6 +39,9 @@ We will be implementing this `add` function.
 
 ## Steps needed for the author of the `calculator-lib` library
 
+> [!TIP]
+> Run `npx cmake-rn init` (or `npx ferric init` for Rust) to scaffold a package with the steps below already taken care of, or to bring an existing package up to date.
+
 ### Install `react-native-node-api` as a dev-dependency and declare a peer dependency
 
 ```bash

eslint.config.js

@@ -18,6 +18,8 @@ export default tseslint.config(
     "packages/ferric-example/ferric_example.js",
     "packages/ferric-example/ferric_example.d.ts",
     "packages/ferric-example/target/**",
+    "packages/cmake-rn-example/cmake-rn-example.js",
+    "packages/cmake-rn-example/cmake-rn-example.d.ts",
     "packages/node-tests/node/**",
     "packages/node-tests/tests/**",
     "packages/node-tests/*.generated.js",

package.json

@@ -14,13 +14,14 @@
     "publint": "node scripts/run-in-published.ts pnpm exec publint --strict",
     "prettier:check": "prettier --experimental-cli --check .",
     "prettier:write": "prettier --experimental-cli --write .",
-    "test": "pnpm --filter react-native-node-api --filter cmake-rn --filter gyp-to-cmake --filter ferric-cli run test",
+    "test": "pnpm --filter @react-native-node-api/cli-utils --filter react-native-node-api --filter cmake-rn --filter gyp-to-cmake --filter ferric-cli run test",
     "bootstrap": "node --run build && pnpm --recursive run bootstrap",
     "changeset": "changeset",
     "release": "node --run prerelease && changeset publish",
     "prerelease": "node --run build && pnpm --recursive run prerelease && node --run publint",
     "init-macos-test-app": "node scripts/init-macos-test-app.ts",
-    "init-ferric-example": "node scripts/init-ferric-example.ts"
+    "init-ferric-example": "node scripts/init-ferric-example.ts",
+    "init-cmake-rn-example": "node scripts/init-cmake-rn-example.ts"
   },
   "author": {
     "name": "Callstack",

packages/cli-utils/package.json

@@ -9,17 +9,29 @@
   },
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.d.ts.map"
   ],
   "exports": {
     ".": "./dist/index.js"
   },
+  "scripts": {
+    "test": "tsx --test --test-reporter=@reporters/github --test-reporter-destination=stdout --test-reporter=spec --test-reporter-destination=stdout"
+  },
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
     "bufout": "^1.0.0",
     "chalk": "^5.4.1",
     "commander": "^14.0.1",
+    "diff": "^9.0.0",
     "ora": "^8.2.0",
-    "p-limit": "^7.2.0"
+    "p-limit": "^7.2.0",
+    "picomatch": "^4.0.5",
+    "semver": "^7.8.5"
+  },
+  "devDependencies": {
+    "@types/picomatch": "^4.0.3",
+    "@types/semver": "^7.8.0"
   }
 }