Bootstrapping a Che-Theia plug-in development with Yeoman

There are two ways to scaffold a new plug-in development environment in Che-Theia:

  • Console plug-in generator (based on the Yeoman generator)

  • Yeomand wizard (launched from the command palette)

List of available plug-in samples

The Che-theia plug-in generator provides a number of pre-defined samples:

  • Hello World plug-in: The plug-in registers a new Che-Theia command. When the user launches this command, Che-Theia displays a notification with the Hello World message. The example illustrates how to define and use commands in Che-Theia.

  • Skeleton plug-in: The plug-in prints the current Che-Theia window state in the browser log.

  • Samples plug-in: The plug-in contains examples of how to use the Che-Theia API:

    • Commands sample: The plug-in shows how to define a Che-Theia command with arguments. Command arguments are useful when another plug-in needs to call a command with parameters.

    • Information message sample: An example of how to define and show a modal information message.

    • Quick-pick sample: An example of how to define a command list with items and a handler for a selected item.

    • Status-bar item sample: An example of how to apply information to the status bar. The status bar is a widget located at the bottom of the Che-Theia window (a footer).

Overview of generating plug-ins

To simplify plug-in development, there is a plug-in generator (@theia/generator-plugin) for creating new plug-ins from scratch. The plug-in generator provides the Yeoman wizard for a step-by-step plug-in generation:

  1. Choose project name for the future plug-in.

  2. Select plug-in type. The Che-Theia plug-in API has two plug-in types:

    • frontend: The plug-in works on the client side

    • backend: The plug-in works on the server side

    During plug-in creation, you need to decide the purpose of the plug-in and, accordingly, select the plug-in type.

  3. Select a plug-in sample.

TODO Apply stack for development: For plugin development inside Eclipse CHE You could use any stack, but apply theia-dev plugin. This stack contains installed npm, node, git and preinstalled @theia/generator-plugin.

Installing the plug-in generator

  1. Run the following command to install the plug-in generator:

    $ yarn add global yo @theia/generator-plugin

  2. Check that the @theia/plugin generator is installed:

    $ yo --help

    The command returns a list of pre-installed generators.

Generating a new plug-in in the console

  1. Create a new terminal inside your workspace using the Terminal menu, and run the plug-in generator:

    $ yo @theia/plugin

    Alternatively, run yo without any parameters and select the @theia/plugin generator from the list of available generators.

    yo select plug in generator

  2. Enter the information to configure the plug-in. For example:

    launching console plug in generator

When the plug-in is generated, it appears in the Files panel. The sample is already compiled and contains the plug-in binary. In this example, the plug-in binary is named my_first_plugin.theia.

Generating a new plug-in using the Yeoman wizard

Che-theia provides the Yeoman wizard command for creating new plug-ins from the command palette.

  1. To launch the command palette, press Ctrl+Shift+p (or Cmd+Shift+p on macOS).

  2. Type Yeom to filter the commands. Select the Yeoman Wizard command.

    yeoman wizard launching

    Note that launching the wizarad may take a few seconds.

  3. Enter the new project name.

    yeoman wizard choosing plug in name

  4. Select the desired plug-in type (client-side or server-side).

    yeoman wizard choosing plug in type

  5. Select the plug-in sample to use.

    yeoman wizard choosing plug in sample

When the plug-in is generated, the Yeoman wizard displays a notification.

yeoman wizard plug in generated

The plug-in sample displays in the Files panel. Use the Output tab in the botton panel to access logs for plug-in generation.

yeoman wizard logs
The Yeoman wizard only works when a workspace is opened in Che-Theia.

Developing a Che-Theia plug-in using Che

This section describes how to set up an environment for developing the Che-Theia plug-ins in Eclipse Che.

Prerequisites

  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Che 'quick-starts'.

  • chectl management tool is installed. See Installing the chectl management tool

    1. Create a workspace for development. Che has dedicated stacks for plug-in development. In the Dashboard, click the Workspaces tab, and click the Add Workspace button.

      adding workspace
      Figure 1. Adding a workspace

    2. Select the Che 7 Dev stack, and click the CREATE & OPEN button.

      choosing che 7 dev stack
      Figure 2. Choosing the 'Che 7 Dev' stack

    3. Generate a plug-in scaffold. The workspace created from this stack provides an easy way to scaffold a new plug-in. When the workspace is started and fully ready, execute the Yeoman Wizard from the command palette:

      1. Press F1 or Ctrl+Shift+p to invoke the command palette, and start typing the command name Yeoman …​ (note that you can also use the keyboard to navigate through the offered commands).

        launching yeoman wizard
        Figure 3. Launching the Yeoman Wizard

      2. Fill in the following fields about the plug-in that you want to create:

  • plug-in name: For example, my-first-plugin.

  • plug-in type: Select backend plug-in.

  • plug-in template: Select the Hello World plug-in.

    A message confirming that the plug-in generation has been successful indicates creation of the plug-in.

    yeoman successful
    Figure 4. Yeoman successfully generated a new plug-in

    1. Open the Files panel, to see the sources of the generated plug-in in the src directory.

    2. Build the plug-in. After the plug-in is created, build the plug-in:

      1. Open a new terminal in the development container (use Ctrl+`, then select ws/dev).

        open terminal in container
        Figure 5. Opening a new terminal in the development container

      2. In the terminal, go to the plug-in directory, and run the yarn command:

        # cd my-first-plugin/
# yarn
        building plug in using yarn
        Figure 6. Building a Che-Theia plug-in using yarn
        The plug-in generator automatically builds the plug-in after its generation.

    3. Run the plug-in. To see your plug-in in action in the IDE, use the Hosted mode to start a new IDE instance and to install the plug-in in it. You now have two IDEs running: one for developing your plug-in and one for testing it.

      1. In the command palette, run: Hosted Plugin: Start Instance command (press F1, and type the command).

      2. Select the path to the root directory of the plug-in in your workspace.

        If you get a warning that your browser prevented the opening of a new tab, click the Open button in the dialog box. A new tab with another Theia instance (with the developed plug-in loaded) is opened.
        running plug in hosted mode
        Figure 7. Running a Che-Theia plug-in in Hosted mode

    4. Debug the plug-in.

      1. In the source code of your plug-in, set a breakpoint by clicking behind a line number (in the editor gutter).

      2. Using the command palette, stop your Hosted Plug-in instance (if any) by running the Hosted Plugin: Stop Instance command.

      3. Start the Hosted Plug-in instance again in the debugging mode by running the Hosted Plugin: Debug Instance command.

      4. Switch to the Hosted Instance tab and perform the required actions to reach the code with the breakpoint.

      5. Go back to the Main Theia window, and use the Debug panel as you need.

        debugging plug ins
        Figure 8. Debugging a Che-Theia plug-in
        When developing a frontend plug-in, debug it using your browser’s Developer Tools option.
Tags: