piral-cli

Piral CLI ·

Piral CLI is a command-line tool that can also be used as a library. It should make common tasks such as building a pilet, scaffolding a pilet, or debugging a piral instance simple.

Internally, Piral CLI is build upon existing tools with connection points to their respective eco-systems.

Documentation

For details on the available commands check out the documentation at Piral or on GitHub.

Plugins

The Piral CLI can be extended with plugins.

Available Plugins

Right now the following generic plugins exist:

• piral-cli-local-feed, provides the ability to start a local feed service
• piral-cli-dotenv, provides the ability to easily integrate environment variables

Also the following bundler plugin exists (bringing build/debug capabilities):

• piral-cli-parcel, provides an integration for Parcel (v1) as a bundler
• piral-cli-parcel2, provides an integration for Parcel (v2) as a bundler
• piral-cli-webpack, provides an integration for Webpack (v4) as a bundler
• piral-cli-webpack5, provides an integration for Webpack (v5) as a bundler
• piral-cli-esbuild, provides an integration for ES Build as a bundler
• piral-cli-rollup, provides an integration for Rollup as a bundler
• piral-cli-vite, provides an integration for Vite as a bundler
• piral-cli-xbuild, provides the possibility of using npm scripts for building and debugging

You'll find an updated list on NPM using the keyword piral-cli.

Building a Plugin

A plugin has to be an NPM module with a name that starts with piral-cli-, e.g., piral-cli-local-feed.

Recommendation: If your CLI plugin adds a new command, name your plugin accordingly, e.g., for a new command named foo-piral create an NPM package called piral-cli-foo-piral. The foo-piral command can be invoked by the user in the command line via piral foo or pb foo-piral.

The NPM module needs to look as follows:

module.exports = function (cliApi) {
  // your code
};

With the CLI API you can do things such as wrapping commands or adding new commands. For commands the yargs command definition is followed.

An example command for a pilet:

module.exports = function (cliApi) {
  cliApi.withCommand({
    name: 'dependencies-pilet',
    alias: ['deps-pilet'],
    description: 'Lists the dependencies of the current pilet.',
    arguments: [],
    flags(argv) {
      return argv
        .boolean('only-shared')
        .describe('only-shared', 'Only outputs the declared shared dependencies.')
        .default('only-shared', false)
        .string('base')
        .default('base', process.cwd())
        .describe('base', 'Sets the base directory. By default the current directory is used.');
    },
    run(args) {
      // your code here, where args.onlyShared refers to our custom argument
    },
  });
};

The resolution for plugins is as follows:

1. Take the plugins from the local project (piral-cli must be installed/run locally)
2. Take the plugins from the global modules

Plugins are never loaded twice. Local versions have precedence.

Using a plugin you can also attach to the hooks of the pilet build/debug and piral build/debug commands.

module.exports = function (cliApi) {
  cliApi.wrapCommand('debug-pilet', (args, run) => run({
    ...args,
    hooks: {
      afterBuild({ outFile, outDir }) {
        console.log('Build done', outFile, outDir);
      },
    },
  }));
};

In this case the afterBuild hook of the pilet debug command is set. You can do whatever else hook, too. Furthermore, you are not limited to a single command - you might want to wrap multiple here.

License

Piral is released using the MIT license. For more information see the license file.

Changelog

1.7.2 (November 8, 2024)

• Fixed removal of MutationEvent in recent Chrome in piral-blazor (#724) by @dheid
• Fixed inclusion of React components in serialized dev tools message (#726)