Skip to content
RobotWebToolsPublic

About

ROS 2 client library for Node.js, with browser integration

Topics

Resources

Contributing

Stars

450 stars

Watchers

21 watching

Forks

Latest commit

 

History

1,127 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

rclnodejs - The ROS 2 Client Library for JavaScript

npm npm downloads GitHub stars Coverage Status node TypeScript

ROS 2 Distro CI Status
ROS 2 Linux x64
Linux arm64
Windows
ASan

Nightly Compatibility

Nightly Compatibility checks: ROS Rolling nightlies with Node.js 27 alpha. See the build documentation.

rclnodejs is a Node.js client library for ROS 2 with JavaScript and TypeScript APIs. It supports topics, services, actions, parameters, lifecycle nodes, RxJS subscriptions, and Electron and browser apps.

Start with Writing Your First rclnodejs Nodes for setup, topics, and service calls.

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

Installation

Prerequisites

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

Install an unpublished branch or commit with npm install RobotWebTools/rclnodejs#<branch>. GitHub installs and source checkouts need newer Node.js/npm versions than the runtime minimum; see the build guide.

Prebuilt binaries cover Ubuntu 22.04 (Humble), 24.04 (Jazzy, Kilted), and 26.04 (Lyrical) on x64 and arm64. Other platforms build from source. Set RCLNODEJS_FORCE_BUILD=1 to force compilation, or use the Dockerfile for container 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

Build robot dashboards, control panels, and 3D visualizations in JavaScript or TypeScript. Your browser app connects to a Node.js runtime that handles ROS 2 communication.

Typed Web SDK

rclnodejs/web provides call, publish, subscribe, and action, with payload types derived from your generated ROS interfaces.

  • Choose which services, topics, and actions to expose in web.json or CLI flags. Unlisted operations are rejected before reaching ROS 2.
  • Use WebSocket for all four operations, or HTTP/SSE for service calls, publishing, and actions. HTTP endpoints also work with curl and Postman.
  • Export OpenAPI 3.1 with rclnodejs-web openapi for API explorers and client generation.

With the runtime and a ROS /add_two_ints service running:

import type {} from 'rclnodejs';
import { connect } from 'rclnodejs/web';

const ros = await connect('ws://localhost:9000/capability');
const reply = await ros.call<'example_interfaces/srv/AddTwoInts'>(
  '/add_two_ints',
  { a: '2n', b: '40n' }
);
console.log(reply.sum);
await ros.close();

SDK subscriptions and action cancellation use WebSocket; cancellation also requires server acceptance. Raw HTTP topic subscriptions are available with --http-sse.

Try Fibonacci actions in the browser, or watch a terminal-controlled manipulator in 3D. See all web demos for setup and runnable code.

WebSocket URLs Without an SDK

rosocket exposes one topic or service per WebSocket connection. Browser clients use only the built-in WebSocket and JSON APIs.

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

Observable Subscriptions

rclnodejs exposes topic subscriptions as RxJS Observables. See the Observable Subscriptions Tutorial for a runnable example and subscription cleanup.

Electron-based Visualization

See the Electron demos for desktop ROS 2 apps and packaging with Electron Forge. The manipulator uses Electron and Three.js to control a two-joint arm.

ROS 2 Interface Message Generation

rclnodejs generates JavaScript bindings and TypeScript declarations during npm install for ROS 2 .msg, .srv, and .action interfaces in your sourced environment.

After adding ROS interface packages, source their workspace and run from your project:

npx generate-ros-messages

JavaScript bindings are written to <your-project>/node_modules/rclnodejs/generated/ and TypeScript declarations to node_modules/rclnodejs/types/interfaces.d.ts. For custom .idl files, this repo also exposes npm run generate-messages-idl.

Using rclnodejs with TypeScript

The package includes TypeScript declarations. Use NodeNext module resolution in tsconfig.json:

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

See the TypeScript demos.

More

  • Benchmarks record topic publishing and service request-response measurements for rclnodejs v1.5.0, rclcpp, and rclpy.
  • rclnodejs-cli creates application skeletons and launch files for multi-node setups.

Contributing

Please read the Contributing Guide before making a pull request.

Thanks to all contributors!

License

Licensed under Apache 2.0.

About

ROS 2 client library for Node.js, with browser integration

Topics

Resources

Contributing

Stars

450 stars

Watchers

21 watching

Forks

Releases

Packages

Used by

Contributors

Languages