rclnodejs - The ROS 2 Client Library for JavaScript

| ROS Distro* | Status | | :----------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | Rolling<br>Kilted<br>Jazzy<br>Humble | <br><br><br> |

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();
});

This example assumes your ROS 2 environment is already sourced.

Documentation

• Get started: Installation, Quick Start, Tutorials
• Reference: API Documentation, Using TypeScript, ROS 2 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

Choose the path that matches how you plan to use rclnodejs:

• Install from npm: add rclnodejs to your own application.
• Quick Start: run the examples from this repository checkout.

Prerequisites

• Node.js version >= 16.13.0
• ROS 2 SDK

Before installing, building, or running rclnodejs, source your ROS 2 environment:

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

Install from npm

Use this path if you want to depend on rclnodejs from your own ROS 2 Node.js application.

npm i rclnodejs

After installation, use the example at the top of this README as a minimal publisher, or continue with Quick Start to run the examples in this repository.

Install from GitHub

Use this path only if you need a branch or commit that is not yet published to npm.

GitHub installs normally build from source. The published npm package includes prebuilt binaries for supported Linux targets, but this repository does not track those prebuilt artifacts.

npm install RobotWebTools/rclnodejs#<branch>

Or 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 applies to supported Linux environments when installing the published npm package.

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

Use these steps if you are working from this repository checkout and want to run one of the included examples.

These steps assume the installation prerequisites are already satisfied and your ROS 2 environment has been sourced.

1. Install the repository dependencies from the project root.

npm install

2. Run a publisher example from this checkout.

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

You should see messages being published once per second.

If you want to build an application instead of running the repository examples, install rclnodejs into your own project with Install from npm and start from the sample code near the top of this README.

Explore more runnable examples in example/ and step-by-step guides in tutorials/.

rclnodejs-cli

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. To generate it locally from this repository checkout, run 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. | ![turtle_tf2](./electron_demo/turtle_tf2/turtle-tf2-demo.