ROS TypeScript Generator

Common errors

• Error: ENOENT: no such file or directory, stat '/opt/ros/iron/share/std_msgs'

  cause The generator could not find one of the ROS package directories specified in the `input` array of your `ros-ts-generator-config.json`.
  fix Double-check the `path` values in your configuration file. Ensure they are correct, absolute paths to existing ROS share directories, and that you have read permissions.

• Error: No config file found at specified path.

  cause The `ros-typescript-generator` CLI was invoked but could not locate the configuration file at the path provided by the `--config` argument.
  fix Verify that the `ros-ts-generator-config.json` file exists at the specified location and that the `--config` flag includes the correct full path and filename, e.g., `npx ros-typescript-generator --config ./ros-ts-generator-config.json`.

• Error: Invalid ROS version '0' specified in config. Must be 1 or 2.

  cause The `rosVersion` property in your `ros-ts-generator-config.json` is set to an invalid value (e.g., `0`, `3`, or a string).
  fix Correct the `rosVersion` entry in your configuration file to either `1` for ROS1 or `2` for ROS2.

Warnings

• breaking Version 1.8.0 introduced a change where service messages are bundled into a single message type containing distinct `Request` and `Response` sub-interfaces. This significantly alters the generated type structure for services.
  Fix: Existing code consuming generated service types from versions prior to 1.8.0 must be updated. For instance, `MyService` will now expose `MyService.Request` and `MyService.Response` for its respective components.
• gotcha Incorrect or inaccessible paths specified in the `input` array of your configuration file will cause the generation process to fail silently or with an error, as the CLI cannot locate the ROS message files.
  Fix: Carefully verify that all `path` entries in `ros-ts-generator-config.json` are correct absolute paths or paths relative to the config file, and that the CLI has necessary read permissions for these directories.
• gotcha The `smartEnums` feature, introduced in v1.9.0, changes how constants within `.msg` files are interpreted. When enabled, it attempts to infer distinct enum types, which might lead to unexpected enum generations if your constant naming conventions are ambiguous.
  Fix: If the generated enums are not as expected, either disable `smartEnums` in your configuration (`"smartEnums": false`) or refine the constant definitions in your `.msg` files to be more distinct for better inference.
• gotcha The `rosVersion` field in the `ros-ts-generator-config.json` is mandatory and must be explicitly set to either `1` or `2`. Omitting it or providing an invalid value will result in a generation error.
  Fix: Always ensure your configuration includes `"rosVersion": 1` or `"rosVersion": 2` to specify the target ROS environment.

Install

• npm install ros-typescript-generator npm
• yarn add ros-typescript-generator yarn
• pnpm add ros-typescript-generator pnpm

Imports

• generate

  import { generate } from 'ros-typescript-generator'

  While primarily a CLI tool, a core `generate` function may be exposed for programmatic use in build scripts or custom tooling, allowing direct invocation with a configuration object.
• CliConfig

  import { CliConfig } from 'ros-typescript-generator'

  Type definition for the configuration object used by the CLI tool, useful if constructing configuration programmatically or for type-checking custom CLI wrappers.
• RosVersion

  import { RosVersion } from 'ros-typescript-generator'

  An exported enum or type representing the supported ROS versions (1 or 2), potentially useful for programmatic validation or configuration.

Quickstart

Demonstrates the typical CLI usage by providing a sample configuration file and the command to run the generator, along with a brief illustration of using the resulting TypeScript types.

{
  "output": "./generated/ros_msgs.ts",
  "rosVersion": 2,
  "typePrefix": "IRosType",
  "useNamespaces": false,
  "smartEnums": true,
  "input": [
    {
      "namespace": "std_msgs",
      "path": "/opt/ros/iron/share/std_msgs"
    },
    {
      "namespace": "geometry_msgs",
      "path": "/opt/ros/iron/share/geometry_msgs"
    }
  ]
}

// 1. Save the above JSON content into a file named `ros-ts-generator-config.json` in your project root.

// 2. Run the generator using npx:
npx ros-typescript-generator --config ros-ts-generator-config.json

// 3. Example of how to use the generated types in your TypeScript project (e.g., in `src/app.ts`):
// import { IRosTypeStdMsgsHeader } from './generated/ros_msgs';

// const myHeader: IRosTypeStdMsgsHeader = {
//   seq: 10,
//   stamp: { sec: 1678886400, nanosec: 500000000 },
//   frame_id: 'robot_base'
// };

// console.log('Generated ROS Header:', myHeader);