JSDoc: Home

JavaScript and TypeScript ROS 2 API

rclnodejs 1.7.0

ROS2.0 JavaScript client with Node.js

Build ROS 2 nodes with a Node.js-native workflow, generated message bindings, and TypeScript-friendly APIs.

Get Started Browse Core API TypeScript Guide

ROS 2 Node.js TypeScript

Quick Start

npm i rclnodejs

Works with sourced ROS 2 environments
Supports generated message and IDL workflows
Covers topics, services, actions, lifecycle, and time

2 Modules

Primary entry points and supporting package surfaces

62 Classes

Runtime building blocks for nodes, services, actions, and time

54 Globals

Enums, constants, policies, and top-level helpers

Why rclnodejs

Engineering ergonomics for robotics teams using JavaScript

rclnodejs lets teams build ROS 2 software in Node.js without losing alignment with the broader ROS ecosystem. The API stays close to core ROS concepts while fitting JavaScript and TypeScript workflows.

Core API

Start with the runtime module

Move from the package entry point into Node, Publisher, Subscription, Client, Service, and Action primitives.

Reference

Inspect globals and enums

Policies, event types, clock kinds, return codes, and shared constants are collected in one place for fast lookup.

Setup

Installation and environment

Install Node.js 16.13.0 or newer, install a compatible ROS 2 distribution, then source the ROS 2 setup file before using the package.

source /opt/ros/<distro>/setup.bash
npm i rclnodejs

Use npm i rclnodejs@x.y.z when you need a specific package version.
Generate a local reference site at any time with npm run docs.
Start exploring the runtime surface in the core API module.

TypeScript

Typed project setup

rclnodejs ships declaration files in the types/ folder so projects get editor assistance, generated message types, and compile-time checks.

{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node",
    "target": "es6"
  }
}

Use the generated declarations for message interfaces after running the message generator.
Follow the TypeScript workflow here before moving into application code.
Pair typed code with the class docs for Node, Publisher, Subscription, Service, and Action primitives.

Interfaces

Message and IDL generation

When your ROS installation changes or your project depends on additional message packages, regenerate the JavaScript and TypeScript bindings from the current environment.

npx generate-ros-messages
npm run generate-messages-idl

Use npx generate-ros-messages for standard ROS interfaces available in the sourced environment.
Use npm run generate-messages-idl when you need IDL-driven generation.
Generated JavaScript files are written under your installed package's generated/ directory.

First Node

Publish a message in a few lines

The package stays close to ROS 2 concepts while keeping the Node.js workflow straightforward.

const rclnodejs = require('rclnodejs');
rclnodejs.init().then(() => {
  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();
});

Home