{"id":14895,"library":"ros-typescript-generator","title":"ROS TypeScript Generator","description":"ros-typescript-generator is a Command Line Interface (CLI) tool designed to generate TypeScript interfaces and enums directly from ROS (Robot Operating System) message (`.msg`), service (`.srv`), and action (`.action`) definition files. Currently at version 1.10.0, this package sees active development with several minor releases annually, often introducing new features and bug fixes. A key differentiator is its focus on generating pure TypeScript types without any runtime dependencies or classes in the output, making it an ideal choice for frontend applications or any project requiring only type definitions. It supports both ROS1 and ROS2 message formats and offers configurable output options like type prefixes, namespaces, and 'smart enums', setting it apart from alternatives that might include Node.js-specific runtime components.","status":"active","version":"1.10.0","language":"javascript","source_language":"en","source_url":"https://github.com/Greenroom-Robotics/ros-typescript-generator","tags":["javascript","typescript"],"install":[{"cmd":"npm install ros-typescript-generator","lang":"bash","label":"npm"},{"cmd":"yarn add ros-typescript-generator","lang":"bash","label":"yarn"},{"cmd":"pnpm add ros-typescript-generator","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally by the CLI for parsing ROS message definition files during the generation process.","package":"@foxglove/rosmsg","optional":false}],"imports":[{"note":"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.","symbol":"generate","correct":"import { generate } from 'ros-typescript-generator'"},{"note":"Type definition for the configuration object used by the CLI tool, useful if constructing configuration programmatically or for type-checking custom CLI wrappers.","symbol":"CliConfig","correct":"import { CliConfig } from 'ros-typescript-generator'"},{"note":"An exported enum or type representing the supported ROS versions (1 or 2), potentially useful for programmatic validation or configuration.","symbol":"RosVersion","correct":"import { RosVersion } from 'ros-typescript-generator'"}],"quickstart":{"code":"{\n  \"output\": \"./generated/ros_msgs.ts\",\n  \"rosVersion\": 2,\n  \"typePrefix\": \"IRosType\",\n  \"useNamespaces\": false,\n  \"smartEnums\": true,\n  \"input\": [\n    {\n      \"namespace\": \"std_msgs\",\n      \"path\": \"/opt/ros/iron/share/std_msgs\"\n    },\n    {\n      \"namespace\": \"geometry_msgs\",\n      \"path\": \"/opt/ros/iron/share/geometry_msgs\"\n    }\n  ]\n}\n\n// 1. Save the above JSON content into a file named `ros-ts-generator-config.json` in your project root.\n\n// 2. Run the generator using npx:\nnpx ros-typescript-generator --config ros-ts-generator-config.json\n\n// 3. Example of how to use the generated types in your TypeScript project (e.g., in `src/app.ts`):\n// import { IRosTypeStdMsgsHeader } from './generated/ros_msgs';\n\n// const myHeader: IRosTypeStdMsgsHeader = {\n//   seq: 10,\n//   stamp: { sec: 1678886400, nanosec: 500000000 },\n//   frame_id: 'robot_base'\n// };\n\n// console.log('Generated ROS Header:', myHeader);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.8.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.9.0"},{"fix":"Always ensure your configuration includes `\"rosVersion\": 1` or `\"rosVersion\": 2` to specify the target ROS environment.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The generator could not find one of the ROS package directories specified in the `input` array of your `ros-ts-generator-config.json`.","error":"Error: ENOENT: no such file or directory, stat '/opt/ros/iron/share/std_msgs'"},{"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`.","cause":"The `ros-typescript-generator` CLI was invoked but could not locate the configuration file at the path provided by the `--config` argument.","error":"Error: No config file found at specified path."},{"fix":"Correct the `rosVersion` entry in your configuration file to either `1` for ROS1 or `2` for ROS2.","cause":"The `rosVersion` property in your `ros-ts-generator-config.json` is set to an invalid value (e.g., `0`, `3`, or a string).","error":"Error: Invalid ROS version '0' specified in config. Must be 1 or 2."}],"ecosystem":"npm"}