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, 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, or the browser manipulator demo for terminal keyboard control and live Three.js visualization. Browse all web demos by scenario and implementation.

File truncated at 100 lines see the full file