Using a Visual Studio Code extension in Che

In Eclipse Che, Visual Studio Code (VS Code) extensions can be installed to extend the functionality of a Che workspace. VS Code extensions can run in the Che-Theia editor container, or they can be packaged in their own isolated and pre-configured containers with their prerequisites.

This document describes:

  • Use of a VS Code extension in Che with workspaces.

  • Che Plug-ins panel.

  • How to publish a VS Code extension in the Che plug-in registry (to share the extension with other Che users).

    • The extension-hosting sidecar container and the use of the extension in a devfile are optional for this.

    • How to review the compatibility of the VS Code extensions to be informed whether a specific API is supported or has not been implemented yet.

Publishing a VS Code extension into the Che plug-in registry

The user of Che can use a workspace devfile to use any plug-in, also known as Visual Studio Code (VS Code) extension. This plug-in can be added to the plug-in registry, then easily reused by anyone in the same organization with access to that workspaces installation.

Some plug-ins need a runtime dedicated container for code compilation. This fact makes those plug-ins a combination of a runtime sidecar container and a VS Code extension.

The following section describes the portability of a plug-in configuration and associating an extension with a runtime container that the plug-in needs.

Writing a meta.yaml file and adding it to a plug-in registry

The plug-in meta information is required to publish a VS Code extension in an Eclipse Che plug-in registry. This meta information is provided as a meta.yaml file. This section describes how to create a meta.yaml file for an extension.

Procedure
  1. Create a meta.yaml file in the following plug-in registry directory: <apiVersion>/plugins/<publisher>/<plug-inName>/<plug-inVersion>/.

  2. Edit the meta.yaml file and provide the necessary information. The configuration file must adhere to the following structure:

    apiVersion: v2                                                   (1)
    publisher: myorg                                                 (2)
    name: my-vscode-ext                                              (3)
    version: 1.7.2                                                   (4)
    type: value                                                      (5)
    displayName:                                                     (6)
    title:                                                           (7)
    description:                                                     (8)
    icon: https://www.eclipse.org/che/images/logo-eclipseche.svg     (9)
    repository:                                                     (10)
    category:                                                       (11)
    spec:
      containers:                                                   (12)
        - image:                                                    (13)
          memoryLimit:                                              (14)
          memoryRequest:                                            (15)
          cpuLimit:                                                 (16)
          cpuRequest:                                               (17)
      extensions:                                                   (18)
              - https://github.com/redhat-developer/vscode-yaml/releases/download/0.4.0/redhat.vscode-yaml-0.4.0.vsix
              - https://github.com/SonarSource/sonarlint-vscode/releases/download/1.16.0/sonarlint-vscode-1.16.0.vsix
    1 Version of the file structure.
    2 Name of the plug-in publisher. Must be the same as the publisher in the path.
    3 Name of the plug-in. Must be the same as in path.
    4 Version of the plug-in. Must be the same as in path.
    5 Type of the plug-in. Possible values: Che Plugin, Che Editor, Theia plugin, VS Code extension.
    6 A short name of the plug-in.
    7 Title of the plug-in.
    8 A brief explanation of the plug-in and what it does.
    9 The link to the plug-in logo.
    10 Optional. The link to the source-code repository of the plug-in.
    11 Defines the category that this plug-in belongs to. Should be one of the following: Editor, Debugger, Formatter, Language, Linter, Snippet, Theme, or Other.
    12 If this section is omitted, the VS Code extension is added into the Che-Theia IDE container.
    13 The Docker image from which the sidecar container will be started. Example: eclipse/che-theia-endpoint-runtime:next.
    14 The maximum RAM which is available for the sidecar container. Example: "512Mi". This value might be overridden by the user in the component configuration.
    15 The RAM which is given for the sidecar container by default. Example: "256Mi". This value might be overridden by the user in the component configuration.
    16 The maximum CPU amount in cores or millicores (suffixed with "m") which is available for the sidecar container. Examples: "500m", "2". This value might be overridden by the user in the component configuration.
    17 The CPU amount in cores or millicores (suffixed with "m") which is given for the sidecar container by default. Example: "125m". This value might be overridden by the user in the component configuration.
    18 A list of VS Code extensions run in this sidecar container.
Additional resources

To set up a custom plug-in registry, see: Building a custom devfile registry.

Adding a plug-in registry VS Code extension to a workspace

When the required VS Code extension is added into a Che plug-in registry, the user can add it into the workspace through the Che Plugins panel or through the workspace configuration.

Adding a VS Code extension using the Che Plugins panel

Prerequisites
  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.

Procedure

To add a VS Code extension using the Che Plugins panel:

  1. Open the Che Plugins panel by pressing CTRL+SHIFT+J or navigate to View/Plugins.

  2. Change the current registry to the registry in which the VS Code extension was added.

  3. In the search bar, click the Menu button and then click Change Registry to choose the registry from the list. If the required registry is not in the list, add it using the Add Registry menu option. The registry link points to the plugins segment of the registry, for example: https://my-registry.com/v3/plugins/index.json.

  4. To update the list of plug-ins after adding a new registry link, use Refresh command from the search bar menu.

  5. Search for the required plug-in using the filter, and then click the Install button.

  6. Restart the workspace for the changes to take effect.

Adding a VS Code extension using the workspace configuration

Prerequisites
Procedure

To add a VS Code extension using the workspace configuration:

  1. Click the Workspaces tab on the Dashboard and select the workspace in which you want to add the plug-in. The Workspace <workspace-name> window is opened showing the details of the workspace.

  2. Click the devfile tab.

  3. Locate the components section, and add a new entry with the following structure:

     - type: chePlugin
       id:              (1)
    1 ID format: <publisher>/<plug-inName>/<plug-inVersion>

    Che automatically adds the other fields to the new component.

    Alternatively, you can link to a meta.yaml file hosted on GitHub, using the dedicated reference field.

     - type: chePlugin
       reference:              (1)
    1 https://raw.githubusercontent.com/<username>/<registryRepository>/v3/plugins/<publisher>/<plug-inName>/<plug-inVersion>/meta.yaml
  4. Restart the workspace for the changes to take effect.