Developing Che-Theia plug-ins
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).
-
Yeoman wizard (launched from the command palette).
List of available plug-in samples
The Che-Theia plug-in generator provides several predefined 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:
-
Choose project name for the future plug-in.
-
Select plug-in type. The Che-Theia plug-in API has two plug-in types:
-
frontend: The plug-in works on the client side
-
back end: 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.
-
-
Select a plug-in sample.
Installing the plug-in generator
-
Run the following command to install the plug-in generator:
$ yarn global add yo @theia/generator-plugin
-
Check that the
@theia/plugin
generator is available:$ yo --help
The command returns a list of pre-installed generators.
Generating a new plug-in in the console
-
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. -
Enter the information to configure the plug-in. For example:
When the plug-in is generated, it appears in the Files panel. The sample is already compiled and contains the plug-in binary file. In this example, the plug-in binary file 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.
-
To launch the command palette, press Ctrl+Shift+p (or Cmd+Shift+p on macOS).
-
Type
Yeom
to filter the commands. Select theYeoman Wizard
command.Note that launching the wizard may take a few seconds.
-
Enter the new project name.
-
Select the desired plug-in type (client-side or server-side).
-
Select the plug-in sample to use.
When the plug-in is generated, the Yeoman wizard displays a notification.
The plug-in sample displays in the Files panel. Use the Output tab in the bottom panel to access logs for plug-in generation.
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.
-
A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.
-
chectl
management tool is available. See Using the chectl management tool.-
Create a workspace for development. Che has stack for plug-in development. In the Dashboard, click the Workspaces tab, and click the Add Workspace button.
-
Select the NodeJS React Web Application sample.
-
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:
-
-
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.
-
Open the Files panel, to see the sources of the generated plug-in in the
src
directory. -
Build the plug-in. After the plug-in is created, build the plug-in:
-
Open a new terminal in the development container (use Ctrl+`, then select
ws/dev
). -
In the terminal, go to the plug-in directory, and run the
yarn
command:# cd my-first-plugin/ # yarn
The plug-in generator automatically builds the plug-in after its generation.
-
-
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.
-
In the command palette, run:
Hosted Plugin: Start Instance
command (press F1, and type the command). -
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 Che-Theia instance (with the developed plug-in loaded) is opened.
-
-
Debug the plug-in.
-
In the source code of your plug-in, set a breakpoint by clicking behind a line number (in the editor gutter).
-
Using the command palette, stop your Hosted Plug-in instance (if any) by running the
Hosted Plugin: Stop Instance
command. -
Start the Hosted Plug-in instance again in the debugging mode by running the
Hosted Plugin: Debug Instance
command. -
Switch to the Hosted Instance tab and perform the required actions to reach the code with the breakpoint.
-
Go back to the Main Che-Theia window, and use the Debug panel as you need.
When developing a frontend plug-in, debug it using your browser’s Developer Tools option.
-
-