Add node.js prebuild docs and host implementation

Author: kraenhansen

docs/PREBUILDS.md

@@ -4,11 +4,11 @@ This document codifies the naming and directory structure of prebuilt binaries,
 
 At the time of writing, our auto-linking host package (`react-native-node-api`) support two kinds of prebuilds:
 
-## `*.android.node` (for Android)
+## `{name}.android.node` (for Android)
 
-A jniLibs-like directory structure of CPU-architecture specific directories containing a single `.so` library file.
+A jniLibs-like directory structure of CPU-architecture specific directories containing a single shared object / dynamic library file.
 
-The name of all the `.so` library files:
+The name of all the library files:
 
 - must be the same across all CPU-architectures
 - can have a "lib" prefix, but doesn't have to
@@ -21,7 +21,7 @@ The name of all the `.so` library files:
 
 The directory must have a `react-native-node-api-module` file (the content doesn't matter), to signal that the directory is intended for auto-linking by the `react-native-node-api-module` package.
 
-## `*.apple.node` (for Apple)
+## `{name}.apple.node` (for Apple)
 
 An XCFramework of dynamic libraries wrapped in `.framework` bundles, renamed from `.xcframework` to `.apple.node` to ease discoverability.
 
@@ -31,6 +31,16 @@ The Apple Developer documentation on ["Creating a multiplatform binary framework
 
 The directory must have a `react-native-node-api-module` file (the content doesn't matter), to signal that the directory is intended for auto-linking by the `react-native-node-api-module` package.
 
+## `{name}.nodejs.node` (for Node.js)
+
+A directory of OS + CPU architecture -specific directories (named `{process.platform}-{process.arch}`) containing a single shared object / dynamic library file.
+
+The name of all the library files:
+
+- must be the same across all CPU-architectures
+- can have a "lib" prefix, but doesn't have to
+- must have a `.node` file extension
+
 ## Why did we choose this naming scheme?
 
 To align with prior art and established patterns around the distribution of Node-API modules for Node.js, we've chosen to use the ".node" filename extension for prebuilds of Node-API modules, targeting React Native.

packages/host/src/node/index.ts

@@ -2,12 +2,15 @@ export {
   SUPPORTED_TRIPLETS,
   ANDROID_TRIPLETS,
   APPLE_TRIPLETS,
+  NODE_TRIPLETS,
   type SupportedTriplet,
   type AndroidTriplet,
   type AppleTriplet,
+  type NodeTriplet,
   isSupportedTriplet,
   isAppleTriplet,
   isAndroidTriplet,
+  isNodeTriplet,
 } from "./prebuilds/triplets.js";
 
 export {
@@ -22,6 +25,11 @@ export {
   determineXCFrameworkFilename,
 } from "./prebuilds/apple.js";
 
+export {
+  createNodeLibsDirectory,
+  determineNodeLibsFilename,
+} from "./prebuilds/node.js";
+
 export { determineLibraryBasename, prettyPath } from "./path-utils.js";
 
 export { weakNodeApiPath } from "./weak-node-api.js";

packages/host/src/node/prebuilds/node.ts

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+
+import { determineLibraryBasename } from "../path-utils.js";
+import { NodeTriplet } from "./triplets.js";
+
+type OSArchName =
+  | `${typeof process.platform}-${typeof process.arch}`
+  | "darwin-arm64;x86_64";
+
+const DIRECTORY_NAMES_PER_TARGET = {
+  "arm64;x86_64-apple-darwin": "darwin-arm64;x86_64",
+  "arm64-apple-darwin": "darwin-arm64",
+  "x86_64-apple-darwin": "darwin-x64",
+} satisfies Record<NodeTriplet, OSArchName>;
+
+/**
+ * Determine the filename of the Android libs directory based on the framework paths.
+ * Ensuring that all framework paths have the same base name.
+ */
+export function determineNodeLibsFilename(libraryPaths: string[]) {
+  const libraryName = determineLibraryBasename(libraryPaths);
+  return `${libraryName}.nodejs.node`;
+}
+
+type NodeLibsDirectoryOptions = {
+  outputPath: string;
+  libraryPathByTriplet: Record<NodeTriplet, string>;
+  autoLink: boolean;
+};
+
+export async function createNodeLibsDirectory({
+  outputPath,
+  libraryPathByTriplet,
+  autoLink,
+}: NodeLibsDirectoryOptions) {
+  // Delete and recreate any existing output directory
+  await fs.promises.rm(outputPath, { recursive: true, force: true });
+  await fs.promises.mkdir(outputPath, { recursive: true });
+  for (const [triplet, libraryPath] of Object.entries(libraryPathByTriplet) as [
+    NodeTriplet,
+    string,
+  ][]) {
+    assert(
+      fs.existsSync(libraryPath),
+      `Library not found: ${libraryPath} for triplet ${triplet}`,
+    );
+    // Create the architecture-specific directory
+    const osArch = DIRECTORY_NAMES_PER_TARGET[triplet];
+    const osArchOutputPath = path.join(outputPath, osArch);
+    await fs.promises.mkdir(osArchOutputPath, { recursive: true });
+    // Strip the ".so" extension from the library name
+    const libraryName = path.basename(libraryPath, ".so");
+    const nodeSuffixedName =
+      path.extname(libraryName) === ".node"
+        ? libraryName
+        : `${libraryName}.node`;
+    const libraryOutputPath = path.join(osArchOutputPath, nodeSuffixedName);
+    await fs.promises.copyFile(libraryPath, libraryOutputPath);
+  }
+  if (autoLink) {
+    // Write a file to mark the Android libs directory is a Node-API module
+    await fs.promises.writeFile(
+      path.join(outputPath, "react-native-node-api-module"),
+      "",
+      "utf8",
+    );
+  }
+  return outputPath;
+}

packages/host/src/node/prebuilds/triplets.ts

@@ -25,9 +25,18 @@ export const APPLE_TRIPLETS = [
 
 export type AppleTriplet = (typeof APPLE_TRIPLETS)[number];
 
+export const NODE_TRIPLETS = [
+  "arm64;x86_64-apple-darwin",
+  "x86_64-apple-darwin",
+  "arm64-apple-darwin",
+] as const;
+
+export type NodeTriplet = (typeof NODE_TRIPLETS)[number];
+
 export const SUPPORTED_TRIPLETS = [
   ...APPLE_TRIPLETS,
   ...ANDROID_TRIPLETS,
+  ...NODE_TRIPLETS,
 ] as const;
 
 export type SupportedTriplet = (typeof SUPPORTED_TRIPLETS)[number];
@@ -49,3 +58,9 @@ export function isAppleTriplet(
 ): triplet is AppleTriplet {
   return (APPLE_TRIPLETS as readonly unknown[]).includes(triplet);
 }
+
+export function isNodeTriplet(
+  triplet: SupportedTriplet,
+): triplet is NodeTriplet {
+  return (NODE_TRIPLETS as readonly unknown[]).includes(triplet);
+}