rclnodejs

rclnodejs is a Node.js client library for ROS 2 that provides JavaScript and TypeScript APIs for building ROS 2 applications.

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.

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

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.

Installation

Prerequisites

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

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

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

Install rclnodejs

npm i rclnodejs

To install from GitHub instead of npm, run:

npm install RobotWebTools/rclnodejs#<branch>

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.

Documentation and Examples

• API documentation: robotwebtools.github.io/rclnodejs/docs
• Tutorials: tutorials/
• JavaScript examples: example/
• TypeScript demos: demo/typescript/
• Browser demos: demo/web/ (typed Web SDK) and demo/rosocket/ (WebSocket gateway)
• HTTP/SSE actions: Fibonacci demo
• Electron demos: demo/electron/
• Companion CLI: rclnodejs-cli

Message Generation

rclnodejs auto-generates JavaScript message interfaces and TypeScript declarations during npm install, so in most projects you do not need to run anything by hand. 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/.

Using rclnodejs with TypeScript

TypeScript declaration files are included in the package. 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.

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 — 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, subscribe, and action, typed from generated ROS interfaces.
  • Two transports — WebSocket for all verbs, or HTTP (--http-port) for calls, publishes, and SSE actions. Action cancellation requires WebSocket and server acceptance. SDK subscriptions use WebSocket; --http-sse enables raw HTTP subscriptions.
  • OpenAPI 3.1 — export service, topic, and action schemas with rclnodejs-web openapi.

  import type {} from 'rclnodejs';
  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`

  See the Fibonacci action demo for a runnable example.

  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

  See the Web SDK guide.

• 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

  See the rosocket guide.

License

Apache License 2.0