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

This example assumes your ROS 2 environment is already sourced.

Documentation

• Get started: Installation, Quick Start, Web SDK guide, Tutorials
• Reference: API Documentation, ROS 2 Interface Message Generation, Using TypeScript
• Features: ROS 2 in the browser, Observable Subscriptions, Electron-based Visualization
• Project docs: Efficient Usage Tips, FAQ and Known Issues, Building from Scratch, Contributing

Installation

Most users only need Install from npm below. If you have cloned this repository and want to run the bundled examples, see Quick Start instead.

Prerequisites

• Node.js version >= 20.20.2
• 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 not yet published to npm. GitHub installs build from source.

npm install RobotWebTools/rclnodejs#<branch>

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

Prebuilt Binaries

rclnodejs ships with prebuilt native binaries for common Linux configurations, so most installs skip compilation.

Supported Platforms:

• Ubuntu 22.04 (Jammy) - ROS 2 Humble
• Ubuntu 24.04 (Noble) - ROS 2 Jazzy, Kilted
• Ubuntu 26.04 (Resolute) - ROS 2 Lyrical
• Architectures: x64, arm64
• Node.js: >= 20.20.2 (N-API compatible)

Installations outside this matrix automatically fall back to building from source. To force a source build even when a prebuilt binary is available:

export RCLNODEJS_FORCE_BUILD=1
npm install rclnodejs

Quick Start

From a clone of this repository, after sourcing your ROS 2 environment:

1. Install the repository dependencies from the project root.

npm install

1. Run a publisher example from this checkout.

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

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

ROS 2 in the browser

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

• rclnodejs/web — typed, allow-listed, curl-able ROS 2 in the browser. A web.json file is your public API; the browser SDK types call / publish / subscribe end-to-end from your ROS 2 message types; and every capability is also a plain HTTP endpoint — curl -X POST http://<host>/capability/call/<name>, with subscribe streaming as Server-Sent Events (GET .../capability/subscribe/<name>) — so shell scripts, Postman, AI-agent tool-use, and even a bare browser fetch() / EventSource (CORS-enabled) just work.

  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`

  No SDK needed for subscribe — with the HTTP/SSE transport enabled (--http-sse, plus --http-cors for cross-origin), any browser streams a live ROS 2 topic via built-in EventSource:

  const es = new EventSource('http://host:9001/capability/subscribe/chatter');
  es.onmessage = (e) => console.log(JSON.parse(e.data)); // live ROS 2 messages

• 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. Use operators like throttleTime(), debounceTime(), map(), and combineLatest() to build declarative message processing pipelines.

import { throttleTime, map } from '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.

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 available in your sourced ROS 2 environment. This happens during npm install, so in most projects you do not need to run anything by hand.

Use the generated types directly:

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

Re-running message generation

If you install additional ROS packages after rclnodejs was installed, re-run the generator 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/.

IDL Message Generation

For custom .idl files (Interface Definition Language), this repo also exposes npm run generate-messages-idl. See docs/BUILDING.md for when you'd need it.

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 the same as the JavaScript example at the top of this README. See TypeScript demos for more.

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.