rclnodejs - The ROS 2 Client Library for JavaScript

| ROS 2 Distro | CI Status | | :---: | :---: | | |


|

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

Key features: Topics, Services, Actions, Parameters, Lifecycle Nodes, TypeScript support, RxJS Observables, Electron integration, ROS 2 in the browser (typed Web SDK + thin WebSocket gateway — rclnodejs/web, rosocket), and prebuilt binaries for Linux x64/arm64.

import rclnodejs from 'rclnodejs';
await rclnodejs.init();
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

• Reference:

• Project docs:

Installation

Prerequisites

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

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

Add rclnodejs to your project

npm i rclnodejs

For a branch or commit not yet published to npm, use npm install RobotWebTools/rclnodejs#, which builds from source.

Prebuilt binaries ship for Ubuntu 22.04 (Humble), 24.04 (Jazzy, Kilted) and 26.04 (Lyrical) on x64 and arm64, so most installs skip compilation; anything else builds from source. Set RCLNODEJS_FORCE_BUILD=1 to always build from source, and see the Dockerfile for containerized development.

Run the examples from a clone

npm install
node example/topics/publisher/publisher-example.mjs

More in example/ and step-by-step guides in tutorials/.

Bring ROS 2 to the Web

rclnodejs ships two ways to reach ROS 2 from the browser — pick one based on how much glue you want to write.

• rclnodejs/web — a typed layer over your ROS 2 graph:

import { connect } from 'rclnodejs/web';
  const ros = await connect('ws://host:9000/capability');
  const reply = await ros.call<'example_interfaces/srv/AddTwoInts'>(
    '/add_two_ints', { a: '2n', b: '40n' }
  ); // reply.sum is typed as ${number}n

• rosocket — thin WebSocket gateway,

npx rosocket --port 9000 --topic /chatter:std_msgs/msg/String

Observable Subscriptions

rclnodejs supports RxJS Observable subscriptions for reactive programming with ROS 2 messages — operators like throttleTime(), debounceTime(), map(), and combineLatest() build declarative message processing pipelines. See the Observable Subscriptions Tutorial for the full API and runnable examples.

Electron-based Visualization

Build desktop ROS 2 apps with Electron + Three.js, packaged for Windows/macOS/Linux via Electron Forge. Featured demo: 🦾 manipulator — a two-joint arm with manual/automatic control. More in demo/electron.

ROS 2 Interface Message Generation

rclnodejs auto-generates JavaScript bindings and TypeScript declarations for every ROS 2 .msg, .srv, and .action interface in your sourced environment. This runs during npm install, so in most projects you never invoke it by hand.

If you install additional ROS packages afterwards, re-run it from your project so the new interfaces are picked up:

npx generate-ros-messages

Generated files are written to /node_modules/rclnodejs/generated/. For custom .idl files, this repo also exposes npm run generate-messages-idl.

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:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "es2022",
  },
}

Then import * as rclnodejs from 'rclnodejs' works as in the example above. See TypeScript demos.

More

• Performance — faster than rclpy and competitive with rclcpp for both topic and service round-trips. Full benchmarks in benchmark/README.md.
• Companion CLI — rclnodejs-cli scaffolds rclnodejs application skeletons and orchestrates launch files for multi-node setups.

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.