rclnodejs - The ROS 2 Client Library for JavaScript

ROS Distro*	Status
Rolling Kilted Jazzy Humble

Note: Supported ROS 2 distributions include Humble, Jazzy, Kilted, and Rolling.

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

• Get started: Installation, Quick Start, Tutorials
• Reference: API Documentation, Using TypeScript, ROS2 Interface Message Generation
• Features and examples: rclnodejs-cli, Electron-based Visualization, Observable Subscriptions, Performance Benchmarks
• Project docs: 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

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)

Installations outside this prebuilt matrix automatically fall back to building from source.

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

Quick Start

1. Source your ROS 2 environment.

source /opt/ros/<distro>/setup.bash

2. Install the repository dependencies.

3. Run a publisher example from this checkout.

node example/topics/publisher/publisher-example.js

You should see messages being published once per second. Explore more runnable examples in example/ and step-by-step guides in tutorials/.

rclnodejs-cli is a separate companion project that provides command-line tooling for working with rclnodejs-based ROS 2 applications. It is particularly useful for creating ROS 2 Node.js packages and working with launch files for multi-node orchestration.

See the rclnodejs-cli repository for installation instructions and the current command set.

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.

Demo	Description	Screenshot
🐢 turtle_tf2	Real-time coordinate frame visualization with turtle control. Features TF2 transforms, keyboard control, and dynamic frame updates.
🦾 manipulator	Interactive two-joint robotic arm simulation. Features 3D joint visualization, manual/automatic control, and visual movement markers.

Explore more examples in electron_demo.

Using rclnodejs with TypeScript

TypeScript declaration files are included in the package and exposed through the types entry in package.json. In most projects, configuring your tsconfig.json is sufficient:

TypeScript example:

import * as rclnodejs from '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();
});

See TypeScript demos for more examples.

Observable Subscriptions

rclnodejs supports RxJS Observable subscriptions for reactive programming with ROS 2 messages. Use operators like throttleTime(), debounceTime(), map(), and combineLatest() to build declarative message processing pipelines.

const { throttleTime, map } = require('rxjs');

const obsSub = node.createObservableSubscription(
  'sensor_msgs/msg/LaserScan',
  '/scan'
);
obsSub.observable
  .pipe(
    throttleTime(200),
    map((msg) => msg.ranges)
  )
  .subscribe((ranges) => console.log('Ranges:', ranges.length));

See the Observable Subscriptions Tutorial for more details.

ROS2 Interface Message Generation

ROS client libraries convert IDL message descriptions into target language source code. rclnodejs provides the generate-ros-messages script to generate JavaScript message interface files and TypeScript declarations.

Example usage:

import * as rclnodejs from 'rclnodejs';
let stringMsgObject = rclnodejs.createMessageObject('std_msgs/msg/String');
stringMsgObject.data = 'hello world';

Running Message Generation

Run the message generation script when new ROS packages are installed:

npx generate-ros-messages

Generated files are located at <yourproject>/node_modules/rclnodejs/generated/.

Note: This step is not needed for rclnodejs > 1.5.0 because bundled interfaces are generated during installation. Rerun this command only after adding new ROS packages to your environment.

IDL Message Generation

In addition to the standard ROS2 message generation (.msg, .srv, and .action), rclnodejs provides advanced support for generating JavaScript message files directly from IDL (Interface Definition Language) files. This feature is particularly useful when working with custom IDL files or when you need more control over the message generation process.

To generate messages from IDL files, use the generate-messages-idl npm script:

npm run generate-messages-idl

Performance Benchmarks

Benchmark results for 1000 iterations with 1024KB messages (Ubuntu 24.04.3 WSL2, i7-1185G7):

These numbers are workload- and environment-specific. See benchmark/README.md for the full setup and methodology.

Contributing

Please read the Contributing Guide before making a pull request.

Thanks to all contributors!

License

This project abides by the Apache License 2.0.