Riot CLI

5.1.2 · active · verified Sun Apr 19

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.

Common errors

```
'riot' command not found
```
cause The `riot-cli` package was not installed globally or is not in your system's PATH.

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.
```
ERR_REQUIRE_ESM or require() of ES Module
```
cause Attempting to use `require('riot-cli')` programmatically in a CommonJS context, but `riot-cli` has transitioned to ESM since v9.0.0.

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.
```
Error: Node.js version X is not supported by riot-cli. Please upgrade to Node.js vY or higher.
```
cause Your Node.js environment is older than the minimum version required by the installed riot-cli version.

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+).
```
TypeScript compilation error: 'Cannot find name X' or 'Property Y does not exist on type Z'
```
cause Misconfiguration of TypeScript in your Riot.js project, or using an older riot-cli version without adequate TypeScript support.

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.

Warnings

breaking 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.
Fix: Ensure your Node.js environment is at least v22.0.0 for riot-cli v10+, or v18.0.0 for riot-cli v9.
breaking 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.
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.
breaking 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.
Fix: Consult the Riot.js migration guides for your specific framework version to ensure compatibility when updating riot-cli.
gotcha 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.
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.
gotcha 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.
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.
gotcha 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`).
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.

Install

npm install riot-cli npm
yarn add riot-cli yarn
pnpm add riot-cli pnpm

Imports

default
wrong:
```
const cli = require('riot-cli')
```
correct:
```
import cli from 'riot-cli'
```
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.
run
```
import { run } from 'riot-cli'
```
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.
version
```
import { version } from 'riot-cli'
```
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.

Quickstart

Demonstrates global installation and compiling a basic Riot.js tag file into a JavaScript module using the `riot` command.

npm install -g riot-cli

# Create a simple Riot.js tag file (e.g., my-component.riot)
// my-component.riot
<my-component>
  <h1>Hello, {props.name}!</h1>
  <script>
    export default {
      onMounted() {
        console.log('Component mounted with name:', this.props.name)
      }
    }
  </script>
</my-component>

# Compile the tag file to a JavaScript module
riot my-component.riot my-component.js

console.log('my-component.js has been compiled. You can now import and use it in your application.')

view raw JSON →