Raise Node.js Minimum to 20.20.2 (#1478)

This PR raises the minimum supported Node.js version to `20.20.2` and includes the follow-up fixes from PR review.

### What changed

- Updated the Node.js minimum across package metadata, CI, and docs.
- Moved the Linux ARM64 CI lane to Node `20.20.2`.
- Aligned install/prerequisite docs across the main README, build docs, npm README, benchmark docs, Electron demos, TypeScript demos, and JSDoc template.
- Reconciled stale Electron demo guidance in:
  - [electron_demo/manipulator/README.md](electron_demo/manipulator/README.md)
  - [electron_demo/turtle_tf2/README.md](electron_demo/turtle_tf2/README.md)
- Fixed prebuild packaging so Node and Electron binaries are generated and resolved separately:
  - [package.json](package.json)
  - [lib/prebuilds.js](lib/prebuilds.js)
  - [lib/native_loader.js](lib/native_loader.js)
  - [scripts/install.js](scripts/install.js)
  - [scripts/tag_prebuilds.js](scripts/tag_prebuilds.js)

### Tests

- Added runtime-specific assertions to:
  - [test/test-native-loader.js](test/test-native-loader.js)
- Added a focused helper test file locally:
  - [test/test-prebuilds.js](test/test-prebuilds.js)

### Validation

```bash
npx mocha test-native-loader.js test-prebuilds.js
```

Fix: #1458

Author: minggangw

.github/workflows/linux-arm64-build-and-test.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [16.X]
+        node-version: [20.20.2]
         architecture: [arm64]
         ros_distribution:
           - humble

README.md

@@ -42,7 +42,7 @@ Choose the path that matches how you plan to use rclnodejs:
 
 ### Prerequisites
 
-- [Node.js](https://nodejs.org/en/) version >= 16.13.0
+- [Node.js](https://nodejs.org/en/) version >= 20.20.2
 - [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html)
 
 Before installing, building, or running rclnodejs, source your ROS 2 environment:
@@ -86,7 +86,7 @@ rclnodejs ships with prebuilt native binaries for common Linux configurations si
 - **Ubuntu 22.04 (Jammy)** - ROS 2 Humble
 - **Ubuntu 24.04 (Noble)** - ROS 2 Jazzy, Kilted
 - **Architectures:** x64, arm64
-- **Node.js:** >= 16.20.2 (N-API compatible)
+- **Node.js:** >= 20.20.2 (N-API compatible)
 
 Installations outside this prebuilt matrix automatically fall back to building from source.
 

benchmark/README.md

@@ -5,7 +5,7 @@ Performance benchmarks for comparing ROS 2 client libraries: C++ (rclcpp), Pytho
 ## Prerequisites
 
 1. **ROS 2**: Install from [ros.org](https://docs.ros.org/en/jazzy/Installation.html)
-2. **Node.js**: v16+ for rclnodejs (from [nodejs.org](https://nodejs.org/))
+2. **Node.js**: v20.20.2+ for rclnodejs (from [nodejs.org](https://nodejs.org/))
 3. **rclnodejs**: Follow [installation guide](https://github.com/RobotWebTools/rclnodejs#installation)
 4. **Build Dependencies**: For C++ benchmarks: `sudo apt install libssl-dev cmake build-essential`
 

docs/BUILDING.md

@@ -13,7 +13,7 @@ Alternatively, you can build ROS 2 from scratch. Please select the platform you
 ### Install `Node.js`
 
 **Notice:**
-`rclnodejs` requires Node.js version >= 16.13.0.
+`rclnodejs` requires Node.js version >= 20.20.2.
 
 I install Nodejs from either:
 

electron_demo/car/README.md

@@ -30,7 +30,7 @@ This demo showcases how to use **rclnodejs** with **Electron** to create an inte
 Before running this demo, ensure you have:
 
 1. **ROS2 installed** (Humble, Jazzy, Kilted, or Rolling)
-2. **Node.js** (version 16 or higher)
+2. **Node.js** (version 20.20.2 or higher)
 3. **rclnodejs built** and working
 
 ### ROS2 Setup
@@ -288,7 +288,6 @@ Extend the joystick commands by modifying the switch statement in `main.js` and
 ### Common Issues
 
 1. **"Failed to initialize ROS2" Error**
-
    - Ensure ROS2 is properly sourced before running npm start
    - Check that rclnodejs is built correctly
 
@@ -301,7 +300,6 @@ Extend the joystick commands by modifying the switch statement in `main.js` and
    ```
 
 3. **Topic Not Appearing**
-
    - Verify ROS2 daemon is running: `ros2 daemon status`
    - Check topic list: `ros2 topic list`
 

electron_demo/manipulator/README.md

@@ -16,7 +16,7 @@ An interactive Electron application demonstrating a two-joint robotic manipulato
 
 ## 📋 Prerequisites
 
-- **Node.js** (>= 16.13.0) - JavaScript runtime
+- **Node.js** (>= 20.20.2) - JavaScript runtime
 - **ROS 2** (Humble, Jazzy, or newer) - Robot Operating System 2
 - **rclnodejs compatible environment** - Linux recommended (tested on Ubuntu/WSL)
 
@@ -81,7 +81,6 @@ npm start
 ### Interactive Controls
 
 - **Joint Sliders**: Use the sliders in the control panel to manually adjust joint angles
-
   - **Joint 1 (Base)**: Rotates the entire arm around the vertical axis (±180°)
   - **Joint 2 (Elbow)**: Bends the upper arm segment (±135°)
 
@@ -105,13 +104,11 @@ npm start
 The demo includes visual indicators to help identify joint movements:
 
 - **🔴 Red Markers**: Joint 1 (Base rotation)
-
   - Red ring around the base joint
   - Red arrow showing rotation direction
   - "Joint1" text label
 
 - **🟢 Green Markers**: Joint 2 (Elbow)
-
   - Green ring around the elbow joint
   - Green arrow showing rotation direction
   - "Joint2" text label
@@ -285,10 +282,10 @@ manipulator/
 
 ### Key Dependencies
 
-- **electron**: `^31.7.7` - Desktop application framework
-- **rclnodejs**: `^1.5.1` - ROS2 JavaScript client library (latest compatible)
-- **@electron/rebuild**: `^3.7.2` - Native module rebuilding tool
-- **three.js**: `r128` - 3D graphics library (loaded via CDN)
+- **electron**: `^40.1.0` - Desktop application framework
+- **rclnodejs**: `^1.8.1` - ROS2 JavaScript client library
+- **@electron/rebuild**: `^4.0.3` - Native module rebuilding tool
+- **three**: `^0.182.0` - 3D graphics library
 
 ### Debugging
 
@@ -308,14 +305,13 @@ manipulator/
    npm start
    ```
 
-2. **Build errors with latest Electron**
+2. **Build errors with Electron**
 
-   - This demo uses Electron 31.7.7 for rclnodejs compatibility
-   - Electron 38+ requires C++20, which rclnodejs doesn't support yet
-   - The current versions are tested and stable
+- This demo currently uses Electron 40.1.0
+- If you change Electron or other native-module dependencies, rerun `npm run rebuild`
+- The versions recorded in `package.json` and `package-lock.json` are the tested baseline for this demo
 
 3. **No ROS2 messages received**
-
    - Check if ROS2 daemon is running: `ros2 daemon start`
    - Verify topic exists: `ros2 topic list`
    - Check message flow: `ros2 topic echo /joint_states`

electron_demo/topics/README.md

@@ -21,7 +21,7 @@ A minimal Electron application demonstrating basic ROS2 topic communication usin
 
 ## 📋 Prerequisites
 
-- **Node.js** (>= 16.13.0) - JavaScript runtime
+- **Node.js** (>= 20.20.2) - JavaScript runtime
 - **ROS 2** (Humble, Jazzy, or newer) - Robot Operating System 2
 - **rclnodejs compatible environment** - Linux recommended (tested on Ubuntu/WSL)
 

electron_demo/turtle_tf2/README.md

@@ -51,7 +51,7 @@ The turtle_tf2 demo showcases:
 ### System Requirements
 
 - **ROS2**: Humble, Iron, or Rolling distribution
-- **Node.js**: Version 18 or higher (for compatibility with latest Electron)
+- **Node.js**: Version 20.20.2 or higher
 - **turtlesim**: ROS2 turtle simulation package
 - **Electron**: For desktop application framework
 
@@ -317,46 +317,39 @@ You can observe the following behavior by:
 ### Common Issues
 
 1. **"Cannot connect to ROS2" or "librcl.so: cannot open shared object file"**
-
    - Ensure ROS2 is sourced: `source /opt/ros/$ROS_DISTRO/setup.bash`
    - **Critical**: Source ROS2 in the SAME terminal where you run `npm start`
    - Check if ROS2 daemon is running: `ros2 daemon status`
    - Verify ROS2 installation: `ros2 --version`
 
 2. **"Turtlesim not responding" or "Failed to spawn turtle2"**
-
    - Verify turtlesim is running: `ros2 run turtlesim turtlesim_node`
    - Check available topics: `ros2 topic list`
    - Ensure spawn service is available: `ros2 service list | grep spawn`
    - Try restarting turtlesim_node if spawn calls fail
 
 3. **"No transforms detected"**
-
    - Ensure demo is started: Click "Start Demo" button
    - Check TF2 tree: `ros2 run tf2_tools view_frames`
 
 4. **"Dynamic frame not visible when toggling"**
-
    - **Check if the demo is started**: Click "Start Demo" button first to initialize all broadcasters
    - **Look for an orange sphere near coordinates (2,3)**: The dynamic frame appears as an orange sphere orbiting around the red static frame
    - **Wait for circular motion**: The dynamic frame moves in a 2-unit radius circle, taking about 6 seconds for a full rotation
    - **The orange sphere is now bigger**: The dynamic frame has been made 3x larger for better visibility
    - **Check the transform list**: The dynamic frame should appear in the left panel's transform list with changing coordinates around (2±2, 3±2, 0)
 
 5. **"3D visualization not loading"**
-
    - Check browser console for WebGL errors
    - Ensure hardware acceleration is enabled
    - Try restarting the Electron application
 
 6. **"electron: not found" or native module errors**
-
    - Make sure you ran `npm run rebuild` after `npm install`
-   - Ensure Node.js version is compatible (18 or higher)
+   - Ensure Node.js version is compatible (20.20.2 or higher)
    - Try deleting `node_modules` and running `npm install && npm run rebuild` again
 
 7. **"THREE is not defined" or script loading errors**
-
    - Ensure Three.js is properly installed: `npm install three@0.155.0`
    - Check that `node_modules/three/build/three.min.js` exists
    - If issues persist, try reinstalling: `rm -rf node_modules && npm install && npm run rebuild`

lib/native_loader.js

@@ -20,6 +20,10 @@ const { execSync } = require('child_process');
 const { NativeError } = require('./errors.js');
 const bindings = require('bindings');
 const debug = require('debug')('rclnodejs');
+const {
+  detectPrebuildRuntime,
+  getTaggedPrebuildFilename,
+} = require('./prebuilds');
 const { detectUbuntuCodename } = require('./utils');
 
 let nativeModule = null;
@@ -35,6 +39,7 @@ function customFallbackLoader() {
 
   const rosDistro = process.env.ROS_DISTRO;
   const arch = process.arch;
+  const runtime = detectPrebuildRuntime();
   const ubuntuCodename = detectUbuntuCodename();
 
   // Require all three components for exact match
@@ -58,16 +63,22 @@ function customFallbackLoader() {
   }
 
   try {
-    // Look for exact match binary: {ros_distro}-{ubuntu_codename}-{arch}-rclnodejs.node
-    const exactMatchFilename = `${rosDistro}-${ubuntuCodename}-${arch}-rclnodejs.node`;
-    const exactMatchPath = path.join(prebuildDir, exactMatchFilename);
-
-    if (fs.existsSync(exactMatchPath)) {
-      debug(`Found exact match binary: ${exactMatchFilename}`);
-      return require(exactMatchPath);
+    const candidate = getTaggedPrebuildFilename({
+      rosDistro,
+      ubuntuCodename,
+      arch,
+      runtime,
+    });
+    const candidatePath = path.join(prebuildDir, candidate);
+
+    if (fs.existsSync(candidatePath)) {
+      debug(`Found ${runtime} prebuilt binary: ${candidate}`);
+      return require(candidatePath);
     }
 
-    debug(`No exact match found for: ${exactMatchFilename}`);
+    debug(
+      `No matching ${runtime} prebuilt binary found for ${rosDistro}-${ubuntuCodename}-${arch}`
+    );
     return null;
   } catch (e) {
     debug('Error in simplified prebuilt loader:', e.message);
@@ -110,10 +121,11 @@ function loadNativeAddon() {
   }
 
   const rosDistro = process.env.ROS_DISTRO;
+  const runtime = detectPrebuildRuntime();
   const ubuntuCodename = detectUbuntuCodename();
 
   debug(
-    `Platform: ${process.platform}, Arch: ${process.arch}, Ubuntu: ${ubuntuCodename || 'unknown'}, ROS: ${rosDistro || 'unknown'}`
+    `Platform: ${process.platform}, Arch: ${process.arch}, Runtime: ${runtime}, Ubuntu: ${ubuntuCodename || 'unknown'}, ROS: ${rosDistro || 'unknown'}`
   );
 
   // Prebuilt binaries are only supported on Linux (Ubuntu)

lib/prebuilds.js

@@ -0,0 +1,47 @@
+// Copyright (c) 2026, The Robot Web Tools Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+const PREBUILD_PACKAGE_NAME = 'rclnodejs';
+const SUPPORTED_PREBUILD_RUNTIMES = new Set(['node', 'electron']);
+
+function detectPrebuildRuntime() {
+  if (process.env.npm_config_runtime === 'electron') {
+    return 'electron';
+  }
+
+  return process.versions.electron ? 'electron' : 'node';
+}
+
+function getTaggedPrebuildFilename({
+  rosDistro,
+  ubuntuCodename,
+  arch,
+  runtime,
+}) {
+  return `${rosDistro}-${ubuntuCodename}-${arch}-${runtime}-${PREBUILD_PACKAGE_NAME}.node`;
+}
+
+function getRuntimeFromGeneratedPrebuild(fileName) {
+  const runtime = fileName.split('.')[0];
+  return SUPPORTED_PREBUILD_RUNTIMES.has(runtime) ? runtime : null;
+}
+
+module.exports = {
+  detectPrebuildRuntime,
+  getRuntimeFromGeneratedPrebuild,
+  getTaggedPrebuildFilename,
+  PREBUILD_PACKAGE_NAME,
+};