Skip to content

Developing plugins

Adam Wolfe edited this page Aug 1, 2024 · 1 revision

Imperative CLI Framework provides the capability build plug-ins that you integrate with imperative-based applications, such as Zowe CLI.

When you enable the plug-ins feature, consumers of your application can develop their own plug-ins or install third-party plugins. Plug-ins are enabled by default in new applications, but you can manually switch the feature on or off.

Designing and developing plug-ins

The following topics provide you with tip, best practices, and examples to help you design and develop plug-ins. However, before you read further, review the following tips and recommendations:

  • We recommend that you develop plug-ins in TypeScript. Alternatively, you can develop plug-ins in JavaScript. Regardless of the language with which you develop plug-ins, the architecture that you define must be robust and plug-ins must be well structured.
  • Every plug-in installed in an Imperative CLI Framework application increases the load time of your applications. Consider the size and complexity of your plug-ins during development to minimize load times.

Coding plug-ins

The following requirements must be met for your plug-in to function after you install it to a base application:

  • The plug-in must:
    • Be an npm package.
    • Define an imperative configuration property in package.json.
    • Specify the main property of package.json.
  • The configuration that you provide must:
    • Be valid to Imperative CLI Framework.
    • Define the properties that we list in Define Plug-in Configuration.
  • The new plug-in command groups that you define must:
    • Have unique command group names that do not exist in the base CLI application. This restriction includes command groups that were added previously by other plug-ins.
    • Have a valid command tree structure.

Defining the plug-in NPM package:

Plug-ins require name, version, description, and main parameters to define the Node Package Manager (npm) package.

More information:

Defining plug-in configurations

You define plug-in configurations in the same manner that you configure a CLI application.

You specify the following configuration properties for plug-ins:

  • name:

    The name of a new command group.

  • definitions:

    The command definitions (command tree) for the plug-in.

  • rootCommandDescription:

    A description of the command group that appears in help text.

  • pluginHealthCheck:

    (Optional) The location the health check handler for the plug-in.

More information:

Defining plug-in handlers

To be considered a valid plug-in, your plug-in must define at least one command and a corresponding handler.

The syntax for a command handler is the same whether you are developing a plug-in or a CLI application.

More information:

The following example illustrates a basic, sample plug-in handler written in TypeScript. Use this example as reference when creating your plug-ins:

import {ICommandHandler, IHandlerParameters} from "@brightside/imperative";

export default class FooHandler implements ICommandHandler {
  public async process(params: IHandlerParameters): Promise<void> {
    // Insert handler code

    // Example:
    // Write to log file, add a response output, build response
    params.response.log.debug("Invoked sample-plugin foo handler");
    params.response.writeMessage("You have executed the Foo command!");
    params.response.build();
  }
}

Implementing profiles

Plug-ins can introduce new profile types to CLI applications. You develop profiles for the plug-in commands in the same manner that you develop profiles for applications.

More information:

Clone this wiki locally