Piral CLI

1.10.3 verified Thu Apr 23 auth: no javascript

Piral CLI (Command Line Interface) is the essential toolkit for developing microfrontends within the Piral framework. It empowers developers to scaffold new Piral instances (the host shell application) and individual Pilets (the microfrontend modules), and to manage their lifecycle including building, debugging, and deploying. The current stable version is 1.10.3, with a release cadence that includes frequent patch and minor updates to incorporate bug fixes, dependency upgrades, and enhance compatibility with evolving frontend frameworks like Angular and React. Its key differentiators include a bundler-agnostic architecture supporting popular tools such as Webpack, Vite, and Esbuild, strong TypeScript integration, and comprehensive features for orchestrating independently deployable microfrontends, including shared dependencies and dynamic runtime updates.

Common errors

error 'piral' is not recognized as an internal or external command, operable program or batch file. ↓

cause `piral-cli` is not installed globally or `npx` is not used within the project context, or `PATH` is misconfigured.

fix

Install globally: npm install -g piral-cli, or use npx to run commands: npx piral [command].

error Error: Minimum Node.js version not met. Expected >=18.17.0, got X.Y.Z ↓

cause The installed Node.js version is older than the minimum required by `piral-cli`.

fix

Upgrade Node.js to version 18.17 or higher. Use nvm install 18 and nvm use 18 (or your preferred version manager).

error Angular Compilation Error: NG04002 ↓

cause This error often indicates an issue with Angular's Ivy compilation related to module boundaries or standalone component usage, which can arise from `piral-ng` plugin incompatibilities with specific Angular project configurations.

fix

Check the piral-ng documentation and changelog for known issues and required piral-cli versions for your Angular version. Ensure consistent @angular/core versions across your Piral instance and pilets.

Warnings

breaking The Node.js engine requirement for `piral-cli` is `>=18.17`. Using older Node.js versions will result in an error and prevent the CLI from running. ↓

fix Upgrade Node.js to version 18.17 or higher. We recommend using `nvm` to manage Node.js versions.

gotcha Compatibility with specific Angular versions and features (e.g., standalone components, lazy component loaders, input signals) in the `piral-ng` plugin often requires specific `piral-cli` and `piral-ng` versions. Discrepancies can lead to build or runtime errors. ↓

fix Refer to the `piral-ng` documentation and release notes for the exact `piral-cli` version compatibility with your Angular project's version. Update `piral-cli` and `piral-ng` in tandem.

breaking The `container` property was removed from the event arguments for the `unhandled-error` event. Code relying on this property will break. ↓

fix Review and update any custom error handling or event listeners that access the `container` property of the `unhandled-error` event arguments.

gotcha Earlier versions of `piral-cli` (prior to v1.8.2) had issues with command-line argument parsing on Windows, which could lead to unexpected behavior or incorrect command execution. ↓

fix Ensure `piral-cli` is updated to at least version 1.8.2 or later to benefit from fixes to Windows command-line parsing.

Install

npm install piral-cli

yarn add piral-cli

pnpm add piral-cli

Imports

run
wrong
```
import run from 'piral-cli';
```
correct
```
import { run } from 'piral-cli';
// or require for CJS
const { run } = require('piral-cli');
```
While primarily a CLI tool, `run` allows programmatic execution of Piral CLI commands within Node.js scripts. This is useful for CI/CD or custom automation.
CliPlugin
wrong
```
import { CliPlugin } from 'piral-cli';
```
correct
```
import type { CliPlugin } from 'piral-cli';
```
This type is primarily used when developing custom plugins for the Piral CLI (packages starting with `piral-cli-`).
cliApi
wrong
```
import { cliApi } from 'piral-cli';
```
correct
```
// In a Piral CLI plugin (e.g., piral-cli-my-plugin/index.js):
module.exports = function (cliApi) { /* ... */ };
```
The `cliApi` object is passed as an argument to the exported function of a Piral CLI plugin, providing methods to extend or wrap CLI commands. It's not a direct import from `piral-cli` itself.

Quickstart

Demonstrates how to create a new Piral instance (host application) and a Pilet (microfrontend), then run them in debug mode.

# Install Piral CLI globally (recommended for convenience, or use npx)
npm install -g piral-cli

# Or use npx for local execution:
# npx piral new my-piral-app --framework react --install
npx piral new my-piral-app --framework react --install
cd my-piral-app
npx piral debug

# In a new terminal, scaffold a new pilet (microfrontend)
npx pilet new my-pilet --source my-piral-app@1.0.0 --install
cd my-pilet
npx pilet debug