piral-cli

library1.10.3jsnpmunverified

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.

web-framework devops

npm install piral-cli

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PIRAL-CLI

piral-cli

web-frameworkjavascriptv1.10.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run

✓ import { run } from 'piral-cli'; // or require for CJS const { run } = require('piral-cli');

✗ import run from '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

✓ import type { CliPlugin } from 'piral-cli';

✗ import { CliPlugin } from 'piral-cli';

This type is primarily used when developing custom plugins for the Piral CLI (packages starting with `piral-cli-`).

cliApi

✓ // In a Piral CLI plugin (e.g., piral-cli-my-plugin/index.js): module.exports = function (cliApi) { /* ... */ };

✗ import { cliApi } from 'piral-cli';

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.

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

piral --version

Debug

Known issues

breakingThe 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.

affects: <1.8.0 (likely)

gotchaCompatibility 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.

affects: >=1.8.5

breakingThe `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.

affects: >=1.9.0

gotchaEarlier 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.

affects: <1.8.2

Errors

Common errors & fixes

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

`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: Minimum Node.js version not met. Expected >=18.17.0, got X.Y.Z

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).

Angular Compilation Error: NG04002

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.

Upgrade

Version history

1.10.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/smapiot/piral ↗

packagehttps://www.npmjs.com/package/piral-cli ↗

homepagehttps://piral.io ↗