Che-Theia plug-in API

The Che-Theia plug-in API consists of two namespaces:

Namespace Description


Provides a Che-Theia IDE-related API that allows to interact with its different components


Provides a plug-in API to access parts of the Che API

theia namespace

The available resources of the theia namespace are described in the theia.d.ts file in the Theia repository. The root of the namespace contains types declaration and the following API sections:


API for adding new and executing existing Che-Theia commands


API for debugger configuration and debugger events


API for accessing environment variables and query parameters of the Che-Theia IDE


API and events related to language support; typically is used by language servers

languageServer (experimental)

API for language-server integration


API for retrieving information about loaded plug-ins


API for providing custom task runners


API to control visual components of the IDE. It allows to manipulate the editor tabs, terminals, status bar, and so on. The section contains events for changing the state of selected components and the whole IDE. Dialog popups.


API related to the Che-Theia workspace with information about the current workspace state, documents in it, file-related operations including watching, finding, and so on. The section contains state-change events.

che namespace

Many APIs in the namespace are experimental and can change in the future.

Available resources of the che namespace are described in the che.d.ts file in the Che-Theia repository.

This namespace contains APIs and types related to Che. Some sections are a bridge to Che API. The following is a list of the sections:


Allows to work with the Che factory API; provides functionality to retrieve specified factory configuration


Allows to add Che-aware commands (Che-specific attributes, such as workspace ID or container name, are accessible from within task implementation)


Allows to add a variable resolver


Allows to work with the Che workspace API; provides functionality to access workspaces, their lifecycle, and user settings.

Using the che namespace in plug-ins

VS Code extensions
  1. Adding the @eclipse-che/plugin dependency for backend plug-ins to a package.json file is a possibility.

  2. For quick calls, it is simpler to use VS Code extension mechanism because it does not require relying on a third-party party dependency or trying and catching the error.

  3. Import and use the namespace. For example:

    const eclipseCheExtPlugin = vscode.extensions.getExtension('@eclipse-che.ext-plugin');
    if (eclipseCheExtPlugin) {
      // grab user
      const user = await eclipseCheExtPlugin.exports.user.getCurrentUser();
     vscode.window.showInformationMessage(`Eclipse Che user information: id ${} with name ${}`);
    } else {
      vscode.window.showWarningMessage('Not running inside Eclipse Che, not displaying any user information');

Using the che namespace in plug-ins

Backend plug-in
  1. Add the @eclipse-che/plugin dependency to a plug-in package.json file.

  2. Import and use the namespace. For example:

    import * as che from '@eclipse-che/plugin';
    const wsConfig = che.workspace.getById(workspaceID);
Frontend plug-in
  1. Perform the same steps as for a back-end plug-in.

  2. Modify the externals section in webpack.config.js by adding the @eclipse-che/plugin key with the following value: che.<your_plugin_ID> (copy the @theia/plugin value, and substitute theia. for che.). For example:

    externals: {
       "@theia/plugin": "theia.theia_test_api",
       "@eclipse-che/plugin": "che.theia_test_api"
It is possible to add a new API namespace for plug-ins using a separate extension.