rclnodejs - The ROS 2 Client Library for JavaScript

ROS Distro*	Status
Rolling Kilted Jazzy Humble

Note: rclnodejs development and maintenance is limited to the ROS 2 LTS releases and the Rolling development branch

rclnodejs is a Node.js client library for ROS 2 that provides comprehensive JavaScript and TypeScript APIs for developing ROS 2 solutions.

const rclnodejs = require('rclnodejs');
rclnodejs.init().then(() => {
  const node = new rclnodejs.Node('publisher_example_node');
  const publisher = node.createPublisher('std_msgs/msg/String', 'topic');
  publisher.publish(`Hello ROS 2 from rclnodejs`);
  node.spin();
});

Documentation

• Installation
• rclnodejs-cli
• API Documentation
• Tutorials
• Electron-based Visualization
• Using TypeScript
• Observable Subscriptions
• ROS2 Interface Message Generation
• Performance Benchmarks
• Efficient Usage Tips
• FAQ and Known Issues
• Building from Scratch
• Contributing

Installation

Prerequisites

• Node.js version >= 16.13.0
• ROS 2 SDK - Don’t forget to source the setup file

Install rclnodejs

npm i rclnodejs

Note: To install rclnodejs from GitHub: add "rclnodejs":"RobotWebTools/rclnodejs#<branch>" to your package.json dependency section.

Docker: For containerized development, see the included Dockerfile for building and testing with different ROS distributions and Node.js versions.

See the features and try the examples to get started.

Prebuilt Binaries

rclnodejs ships with prebuilt native binaries for common Linux configurations since v1.5.2, eliminating the need for compilation during installation. This significantly speeds up installation and reduces dependencies.

Supported Platforms:

• 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)

Force Building from Source:

If you need to build from source even when a prebuilt binary is available, set the environment variable:

export RCLNODEJS_FORCE_BUILD=1
npm install rclnodejs

rclnodejs-cli

rclnodejs-cli is a companion project we recently launched to provide a commandline interface to a set of developer tools for working with this rclnodejs. You may find rclnodejs-cli particularly useful if you plan to create ROS 2 node(s) and launch files for working with multiple node orchestrations.

Usage: rclnodejs [command] [options]

Options:
  -h, --help                               display help for command

Commands:
  create-package [options] <package-name>  Create a ROS2 package for Nodejs development.
  generate-ros-messages                    Generate JavaScript code from ROS2 IDL interfaces
  help [command]                           display help for command

API Documentation

API documentation is available online or generate locally with npm run docs.

Electron-based Visualization

Create rich, interactive desktop applications using Electron and web technologies like Three.js. Demos leverage Electron Forge for easy packaging on Windows, macOS, and Linux.

File truncated at 100 lines see the full file