Developing plugins

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.

• Using the Plugin Management Facility (PMF)
• Enabling the Plugin Management Facility
• Managing and loading installed plug-ins
• Designing and developing plug-ins
  • Coding plug-ins
  • Defining the plug-in NPM package:
  • Defining plug-in configurations
  • Defining plug-in handlers
• Implementing profiles

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:

• package.json: Specifics of npm's package.json handling

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:

• Command definition and processing.

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:

• Command Definition & Processing Example: plug-in handler (typeScript):

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:

• Working with profiles