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: API Documentation, Web SDK guide, Tutorials
• Project docs: Efficient Usage Tips, FAQ and Known Issues, Building from Scratch, Contributing

Installation

Prerequisites

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

Source your ROS 2 environment before installing, building or running rclnodejs:

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#<branch>, 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: you allow-list capabilities in web.json or via CLI flags; anything else is rejected before it reaches ROS 2. Best for typed web apps and HTTP clients.

  • Typed SDK — call, publish and subscribe, typed end-to-end from your generated message and service types.
  • Two transports — WebSocket, plus an optional HTTP listener (--http-port) so call and publish work from curl, Postman or fetch(). subscribe needs WebSocket, or --http-sse to stream it as Server-Sent Events.
  • OpenAPI 3.1 — rclnodejs-web openapi emits a machine-readable spec for codegen, API explorers and agent tool-use.

  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, zero browser dependencies (just built-in WebSocket + JSON). Best for quick prototypes and roslibjs-style apps.

  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 <your-project>/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.