Improving DX of co-shipping Node.js prebuilds

[kraenhansen]

Library authors might want to publish packages containing prebuilds for Node.js alongside the React Native specific prebuilds, if they have a use-case for targeting Node.js or wants to make it easier for app developers to test without having to mock the native addon of the library.

Library authors can use cmake-js, node-gyp (if they use CMake or GYP respectively) to build for Node.js.

Annoyance 1: Prebuild / output location

By default, both cmake-js and node-gyp output the dynamic library produced when building to ${projectRoot}/build/${configuration}/${targetName}.node.

☝ has the disadvantage that dynamic libraries compiled on different operating systems / architectures share the same path of disk.

Developers use tools like prebuild or prebuildify (supports only GYP), to build and structure multiple os+arch specific binaries.

The cmake-rn store its output platform-specific & arch-specific subdirectories of ${projectRoot} (see out PREBUILDS.md for details on the structure of these directories).

Note

${projectRoot} in the paths above is not the package root, but instead the directory containing the binding.gyp or CMakeLists.txt configurations of the particular build system.

Annoyance 2: Executing two commands

It's annoying to have to invoke multiple tools (which might have slightly different runtime options / args).

Ideally a library author should be able to just select the platforms / triplets they want to build for:

• React Native (iOS / Android)
• Node.js (Windows, Linux, MacOS)

---

To be more compatible with the existing tools for Node.js, we could:

1. write our prebuilds into the ${projectRoot}/build/${configuration} directory, the same way cmake-js and node-gyp does: I've opened Add --out-to-build option #148 to add an opt-in option for this.
2. make it easier to build for Node.js
   1. by adding Node.js as a target for cmake-rn (feels wrong, as the -rn suffix).
   2. provide yet another CLI wrapping cmake-js and cmake-rn (feels a bit too abstracted).
   3. provide yet another CLI with direct support for multiple platforms / operating-systems, with a pluggable architecture to make it easier to add support for future out-of-tree platforms as well.

[shirakaba]

By default, both cmake-js and node-gyp output the dynamic library produced when building to ${projectRoot}/build/${configuration}/${targetName}.node.

☝ has the disadvantage that dynamic libraries compiled on different operating systems / architectures share the same path of disk.

I’ve run into problems with this kind of thing in other contexts, using an ARM Windows VM on a Mac. We probably do want to reach a solution that distinguishes operating system. While they surely exist, I think it’s relatively rare that all of your project’s Node-API modules happen to be OS-agnostic libraries that only need to be split on an architecture.

[shirakaba]

by adding Node.js as a target for cmake-rn (feels wrong, as the -rn suffix).

I think this is the right solution, and only a naming problem. I’m not even convinced we have to rename it. It was made “for” RN, but respects the wider ecosystem too.

[shirakaba]

Whilst writing the Getting started with Node API docs, I felt a --node flag feels quite natural and would avoid having to explain both cmake-rn and cmake-js.

     "build:rn": "cmake-rn",
-    "build:node": "cmake-js"
+    "build:node": "cmake-rn --node"

To illustrate, right now my explanation is longer than it has to be, because I have to mention both tools:

What do you think?

[shirakaba]

I've just realised, a --node flag would also make the prepublishOnly script look way friendlier:

- "prepublishOnly": "npm run build:node && cmake-rn --android --apple"
+ "prepublishOnly": "cmake-rn --android --apple --node"