Skip to content

Update the README for npmjs #1233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
minggangw merged 2 commits into from
Aug 26, 2025
Merged

Update the README for npmjs #1233

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d34a15f
Update the README for npmjs
minggangw Aug 26, 2025
a6a2d48
Address comments
minggangw Aug 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 19 additions & 114 deletions scripts/npmjs-readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

`rclnodejs` is a Node.js client for the Robot Operating System (ROS 2). It provides a simple and easy JavaScript API for ROS 2 programming. TypeScript declarations are included to support use of rclnodejs in TypeScript projects.

\* rclnodejs development and maintenance is limited to all active ROS 2 LTS releases and the Rolling development branch
Copy link

Copilot AI Aug 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The backslash before the asterisk (\*) creates escaped markdown. This should be just * to render as a proper bullet point, or use - for consistency with other list items in the document.

Suggested change
\* rclnodejs development and maintenance is limited to all active ROS 2 LTS releases and the Rolling development branch
- rclnodejs development and maintenance is limited to all active ROS 2 LTS releases and the Rolling development branch

Copilot uses AI. Check for mistakes.

Here's an example for how to create a ROS 2 node that publishes a string message in a few lines of JavaScript.

```JavaScript
Expand All @@ -14,137 +16,44 @@ rclnodejs.init().then(() => {
});
```

## Prerequisites

**Node.js**

- [Node.js](https://nodejs.org/en/) version >= 16.13.0.
## Installation

**ROS 2 SDK**
### Prerequisites

- See the ROS 2 SDK [Installation Guide](https://docs.ros.org/en/kilted/Installation.html) for details.
- **DON'T FORGET TO [SOURCE THE ROS 2 STARTUP FILES](https://docs.ros.org/en/kilted/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.htmls)**
- [Node.js](https://nodejs.org/en/) version >= 16.13.0
- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) - **Don't forget to [source the setup file](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files)**

## Install rclnodejs

Install the rclnodejs version that is compatible with your installed version of ROS 2 (see table below).

Run the following command for the most current version of rclnodejs
### Install rclnodejs

```bash
npm i rclnodejs
```

or to install a specific version of rclnodejs use

```bash
npm i rclnodejs@x.y.z
```

#### RCLNODEJS - ROS 2 Version Compatibility

| RCLNODEJS Version | Compatible ROS 2 LTS |
| :----------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| latest version (currently [v1.5.0](https://github.com/RobotWebTools/rclnodejs/tree/1.5.0)) | [Kilted](https://github.com/RobotWebTools/rclnodejs/tree/kilted)<br>[Jazzy](https://github.com/RobotWebTools/rclnodejs/tree/jazzy)<br>[Humble](https://github.com/RobotWebTools/rclnodejs/tree/humble-hawksbill) |
- **Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependency section.

## Documentation

API [documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html) is available online.

## JavaScript Examples

The source for the following examples and many others can be found [here](https://github.com/RobotWebTools/rclnodejs/tree/develop/example).

Use complex message

```JavaScript
const publisher = node.createPublisher('sensor_msgs/msg/JointState', 'topic');
publisher.publish({
header: {
stamp: {
sec: 123456,
nanosec: 789,
},
frame_id: 'main frame',
},
name: ['Tom', 'Jerry'],
position: [1, 2],
velocity: [2, 3],
effort: [4, 5, 6],
});

```

Create a subscription

```JavaScript
const rclnodejs = require('../index.js');

// Create a ROS node and then print out the string message received from publishers
rclnodejs.init().then(() => {
const node = rclnodejs.createNode('subscription_example_node');

node.createSubscription('std_msgs/msg/String', 'topic', (msg) => {
console.log(`Received message: ${typeof msg}`, msg);
});

rclnodejs.spin(node);
});
```

Create a service

```JavaScript
node.createService('example_interfaces/srv/AddTwoInts', 'add_two_ints', (request, response) => {
console.log(`Incoming request: ${typeof request}`, request);
let result = response.template;
result.sum = request.a + request.b;
console.log(`Sending response: ${typeof result}`, result, '\n--');
response.send(result);
});

```

Send a request in a client

```JavaScript
const client = node.createClient('example_interfaces/srv/AddTwoInts', 'add_two_ints');
const request = {
a: Math.floor(Math.random() * 100),
b: Math.floor(Math.random() * 100),
};

console.log(`Sending: ${typeof request}`, request);
client.sendRequest(request, (response) => {
console.log(`Result: ${typeof response}`, response);
});

```

Check out more [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example).
Try the [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) to get started.

## Using rclnodejs with TypeScript

In your node project install the rclnodejs package as described above. You will also need the TypeScript compiler and node typings installed.

```
npm install typescript @types/node -D
```

In your project's tsconfig.json file include the following compiler options:
TypeScript declaration files are included in the `types/` folder. Configure your `tsconfig.json`:

```jsonc
{
"compilerOptions": {
"module": "commonjs",
"moduleResolution": "node",
"target": "es6",
...
}
"target": "es2020",
},
}
```

Here's an earlier JavaScript example reimplemented in TypeScript.
TypeScript example:

```typescript
import * as rclnodejs from 'rclnodejs';
Expand All @@ -156,21 +65,17 @@ rclnodejs.init().then(() => {
});
```

Type-aliases for the ROS2 messages can be found in the `types/interfaces.d.ts` file. To use a message type-alias follow the naming pattern <pkg_name>.[msg|srv].<type>, e.g., sensor_msgs.msg.LaserScan or the std_msgs.msg.String as shown below.
See [TypeScript demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/ts_demo) for more examples.

```typescript
const msg: rclnodejs.std_msgs.msg.String = {
data: 'hello ROS2 from rclnodejs',
};
```
**Note** that the interface.d.ts file is updated each time the generate_messages.js script is run.

Check out more TypeScript [demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/ts_demo).
## Electron-based Visualization

**Note** that the interface.d.ts file is updated each time the generate_messages.js script is run.
Create rich, interactive desktop applications using Electron and web technologies like Three.js. Build 3D visualizations, monitoring dashboards, and control interfaces that run on Windows, macOS, and Linux.

## Using rclnodejs with Electron
Try the `electron_demo/turtle_tf2` demo for real-time coordinate frame visualization with dynamic transforms and keyboard-controlled turtle movement. More examples in [electron_demo](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).

Check out [demos](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo).
![demo screenshot](https://github.com/RobotWebTools/rclnodejs/blob/develop/electron_demo/turtle_tf2/turtle-tf2-demo.gif?raw=true)

## License

Expand Down
Loading