{"id":11953,"library":"riot-cli","title":"Riot CLI","description":"Riot CLI is the command-line utility for precompiling Riot.js tags, an open-source UI library. As of its latest stable release, v10.0.0, it wraps the `@riotjs/compiler` to transform Riot.js component files (typically `.riot` files) into standard JavaScript modules. While often installed implicitly with the main `riot` package, it can also be installed and used as a standalone tool. The project follows an active development cycle, releasing major versions to align with new Riot.js framework updates and Node.js environment changes, such as the shift to ESM and stricter Node.js version requirements. Key differentiators include its tight integration with the Riot.js ecosystem, support for various pre-processors and TypeScript, and its ability to not only compile individual tags but also bundle entire Riot.js applications for quick prototypes or development workflows.","status":"active","version":"5.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/riot/cli","tags":["javascript","riot","cli"],"install":[{"cmd":"npm install riot-cli","lang":"bash","label":"npm"},{"cmd":"yarn add riot-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add riot-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for compiling Riot.js tags; riot-cli acts as a command-line wrapper around this compiler.","package":"@riotjs/compiler","optional":false}],"imports":[{"note":"riot-cli is primarily a command-line utility and rarely imported programmatically. Since v9.0.0, it uses ESM, making CommonJS 'require' incorrect for programmatic use.","wrong":"const cli = require('riot-cli')","symbol":"default","correct":"import cli from 'riot-cli'"},{"note":"While riot-cli is a CLI, some CLI packages expose a 'run' function for programmatic execution in build scripts. This is not a commonly documented public API for riot-cli but represents a plausible (though uncommon) programmatic import.","symbol":"run","correct":"import { run } from 'riot-cli'"},{"note":"Many packages expose their version string. This would be a static named export if riot-cli provided a programmatic API, but it's not its primary use case.","symbol":"version","correct":"import { version } from 'riot-cli'"}],"quickstart":{"code":"npm install -g riot-cli\n\n# Create a simple Riot.js tag file (e.g., my-component.riot)\n// my-component.riot\n<my-component>\n  <h1>Hello, {props.name}!</h1>\n  <script>\n    export default {\n      onMounted() {\n        console.log('Component mounted with name:', this.props.name)\n      }\n    }\n  </script>\n</my-component>\n\n# Compile the tag file to a JavaScript module\nriot my-component.riot my-component.js\n\nconsole.log('my-component.js has been compiled. You can now import and use it in your application.')","lang":"javascript","description":"Demonstrates global installation and compiling a basic Riot.js tag file into a JavaScript module using the `riot` command."},"warnings":[{"fix":"Ensure your Node.js environment is at least v22.0.0 for riot-cli v10+, or v18.0.0 for riot-cli v9.","message":"Node.js version support has been frequently updated. Version 10.0.0 drops support for Node.js versions older than 22.0.0. Earlier, v9.0.0 dropped support for Node.js versions older than 18.0.0.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"For programmatic use (which is uncommon for this CLI), ensure your project is configured for ESM imports if you intend to interact with its internal modules.","message":"Starting with v9.0.0, riot-cli adopted ESM (ECMAScript Module) syntax internally. This change primarily affects consumers attempting programmatic integration who were using CommonJS `require()` statements.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Consult the Riot.js migration guides for your specific framework version to ensure compatibility when updating riot-cli.","message":"Major versions of riot-cli (e.g., v6.0.0, v10.0.0) are typically tied to specific major versions of the Riot.js framework and its compiler. Upgrading riot-cli may require corresponding updates to your Riot.js framework dependencies.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Review your build pipeline if you rely on external dependencies being external to the riot-cli generated output. You might need to adjust bundler configurations.","message":"From v6.1.0 onwards, riot-cli improves bundling by including external npm dependencies directly into its output. This changes how generated bundles might interact with existing module resolution strategies in larger projects.","severity":"gotcha","affected_versions":">=6.1.0"},{"fix":"Upgrade riot-cli to at least v5.2.0 for basic TypeScript support, or a more recent version for full compatibility with modern TypeScript features in Riot.js tags.","message":"TypeScript support was gradually added around v5.2.0 and v5.3.0. Older versions of riot-cli do not natively support TypeScript syntax within Riot.js tags.","severity":"gotcha","affected_versions":"<5.2.0"},{"fix":"Always install `riot-cli` separately via `npm install -g riot-cli` or `npm install -D riot-cli` if you need the command-line utility for Riot.js v4 and newer.","message":"Prior to Riot.js v4, the CLI was often bundled with the main `riot` npm package. Since Riot.js v4, `riot-cli` became a separate, explicitly installed package (`npm i -g @riotjs/cli`).","severity":"gotcha","affected_versions":"<4.0.0 (of riot-cli for standalone install)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install globally using `npm install -g riot-cli` or `yarn global add riot-cli`. Ensure your system's PATH includes the npm global bin directory.","cause":"The `riot-cli` package was not installed globally or is not in your system's PATH.","error":"'riot' command not found"},{"fix":"If programmatic interaction is necessary, switch your project to use ES modules (`import ... from 'riot-cli'`) or consider using `child_process.exec` to run the CLI command directly.","cause":"Attempting to use `require('riot-cli')` programmatically in a CommonJS context, but `riot-cli` has transitioned to ESM since v9.0.0.","error":"ERR_REQUIRE_ESM or require() of ES Module"},{"fix":"Upgrade your Node.js version using a tool like `nvm` (Node Version Manager) to meet the requirements of your riot-cli version (e.g., Node.js >=22 for riot-cli v10+).","cause":"Your Node.js environment is older than the minimum version required by the installed riot-cli version.","error":"Error: Node.js version X is not supported by riot-cli. Please upgrade to Node.js vY or higher."},{"fix":"Ensure your `tsconfig.json` is correctly set up for Riot.js components, upgrade `riot-cli` to a version that supports TypeScript (v5.2.0+), and export `RiotComponent` interfaces for proper type checking as per Riot.js documentation.","cause":"Misconfiguration of TypeScript in your Riot.js project, or using an older riot-cli version without adequate TypeScript support.","error":"TypeScript compilation error: 'Cannot find name X' or 'Property Y does not exist on type Z'"}],"ecosystem":"npm"}