How to add extensions and plugins to Eclipse Theia

How to add extensions and plugins to Eclipse Theia

The Eclipse Theia IDE is an extensible platform to build web-based tools and IDEs. In this article, we focus on how to add new features to Theia by adding extensions and/or plugins. Please see this article for a comparison of Eclipse Theia extensions and Theia plugins and here for a quick introduction of Theia and here about frequently asked questions about Theia

In Eclipse Theia, there are four ways of adding new functionality, which we describe in the following sections:

  • Adding extensions to Eclipse Theia
  • Adding plugins to Eclipse Theia at build time
  • Adding plugins to Eclipse Theia at runtime
  • Adding plugins to Eclipse Theia using Che

How to add an extension to Eclipse Theia

This is actually very simple. As Eclipse Theia is essentially a node application, adding an extension to Theia just means  adding another dependency to the package.json of your Theia instance. Please see the article on How to launch Eclipse Theia from your own custom package.json for more details.

There are two sources  you can get new extensions from, either you add an extension which is published in the node package registry, or — if you are developing a Theia extension yourself — you can add it locally. The following example package.json adds two extensions to a Theia product, one being the existing outline view extension, published in the node package registry, the second one being a custom extension, that you have created locally (“myExtension”).

{
  "private": true,
  "dependencies": {
    "typescript": "latest",
    "...": "...",
    "...": "...",
    "@theia/outline-view@theia/java": "next".
    "myExtension": "myVersion"
  },
  "devDependencies": {
    "@theia/cli": "next"
  }
}

After rebuilding your Theia instance you will have those extensions available, e.g. with the outline view in the example above, you can now use the view to browse Java source files:

Please see here for a list of Theia extensions, which are currently published in the node package registry.

How to add plugins to Eclipse Theia at build/launch time

Please note that in the previous section we described how to add extensions to Theia, the remaining sections are about plugins. Please see this article on a comparison between Eclipse Theia plugins and extensions to get a more detailed picture on the differences between extensions and plugins.

One of the differences is that, in contrast to extensions, plugins can be added at runtime. However, if you want to add a plugin to your Eclipse Theia instance before you even launch Theia, you can specify either:

  •  local directory to be scanned for plugins
  • Remote locations for plugins to be downloaded and installed

All plugins from these two sources will be added automatically when Theia is launched. To enable the extensibility via plugins in general, you first need to add the “plugin-ext” extension to your Theia (to the package.json). This has to be done once and enables the general ability to extend Theia with plugins.

{
  "private": true,
  "dependencies": {
    "...": "...",
    "@theia/plugin-ext": "latest".
  }

In the following two sections we describe how to add plugins from a local directory (if you downloaded them or you are developing them yourself) or from remote locations (if you want to add existing feature plugins from the Theia ecosystem).

Add plugins from a local directory

For this option, you need to place your plugins in a directory and let Theia use them. There are two ways to specify the directory containing the plugins to be added on start up, either with a command line argument…

theia start --plugins=local-dir:/pathTo/plugins/

… or via an environment variable:

export THEIA_DEFAULT_PLUGINS=local-dir://absolute-path-to-plugins-folder

In both cases, Theia will scan the specified directory on start up, unzip all contained plugins and add them to your instance. You can check that they are correctly installed by opening the “Plugins View” as shown in the following screenshot (this view is added by the “plugin-ext” extension)

A plugin installed in the Eclipse Theia IDE

Add plugins from remote locations

Several features in the Theia ecosystem are available as plugins. Please note that Theia has switched to reusing quite a few VS Code plugins instead of native extensions, especially for language support. So most Theia products will include some plugins by default.

If you want to install plugins as defaults in your solution, you can enhance the package.json of your product so that these plugins are automatically downloaded and installed.

To do so, you first need to specify a folder, in which downloaded plugins are stored, e.g. “plugins”. Second, you specify a list of remote URLs pointing to plugins to be downloaded (see following listing). The following example adds two plugins to Theia, which enable Java language support.

"theiaPluginsDir": "plugins",

"theiaPlugins": {

"vscode-builtin-java": "https://github.com/theia-ide/vscode-builtin-extensions/releases/download/v1.39.1-prel/java-1.39.1-prel.vsix",

"java-lsp": "https://download.jboss.org/jbosstools/static/jdt.ls/stable/java-0.50.0-1825.vsix"

 }

Finally, you need to let Theia scan the folder, in which the plugins have been downloaded (like in the previous section). In the example above, the following argument would do the trick:

theia start --plugins=local-dir:./plugins

To validate that the plugins have been installed correctly, you can have a look again at the plugin view in your running Theia product:

In the example above, the two added plugins would enable Java Language support including auto completion as shown in the following screen shot:

How to add plugins to Eclipse Theia at runtime

Plugins can also be installed at runtime, which is one of the main differences to extensions. This also covers the use case, that the user of a tool based on Eclipse Theia can extend their workbench as they like.

Again, as described in the previous section, you need to add the extension “plugin-ext” beforehand to enable plugins in general. The extension adds the “Plugins View”, shown before, but also contributes a new command called “Deploy plugin by ID”. This command supports several source locations to install plugins from. By default, “plugin-ext” currently supports to install plugins:

  • From a local directory using: local-dir:/pathTo/plugins/
  • Via HTTP/HTTPS using: https://path/to/my.plugin
  • Via the GitHub protocol using: github:<org>/<repo>/<filename>@<version>

The following screencast shows the plugin installation from a local directory, as you can see, the plugin is installed at runtime and can directly be used.

Installing a plugin into the Eclipse Theia IDE

There is actually a fourth source where you can install plugins from, the VS Code Plugin marketplace. This due to the fact that Theia plugins provide the same API as VS Code (as described in this article). As this fourth option is of special interest, we describe it in more detail in this article on how to use VS Code extensions in Eclipse Theia.

How to add plugins to Eclipse Theia using Che

Eclipse Che is a workspace server and uses Theia as default IDE. Please see our article on the relationship between Eclipse Che and Theia for more details. Che adds some nice features on top of standard Theia, e.g. a plugin registry, from where users can install plugins. So when using Theia in Eclipse Che, you can open the following view called “Plugins” in your workspace configuration, select from a list of available plugins and even specify the version to be used. Please note that Eclipse Che plugins can contain more than just a Theia plugin, they can also extend the runtime and Che itself (as described in more detail in this article). Please note that quite a few of the  plugins provided in Che rely on VS Code plugins. As mentioned before, we will describe this capability more in detail in a follow up article.

Adding a Che-Theia plugin to Eclipse Che

Conclusion

Eclipse Theia is extensible in several ways,- using extension or plugins, at build time, at start-up or even at runtime. This covers various use cases – as a provider of a tool, you can add default features using extensions or by adding default plugins on start-up. As a user, you can add your favorite features by installing plugins as you like. Therefore, even if the two extension models might be a little confusing when getting started with Theia, their existence provides a lot of flexibility. As you can see with Che, which adopts Theia, you can even provide your own extension mechanism on top of Theia, make it simpler or more focused and therefore target your specific user group.

If you want to build such an extensible product based on Eclipse Theia or Che; or provide your own custom extension or plugin; miss a feature, or need general support and advice on Eclipse Theia, have a look at our support and consulting offering for Eclipse Theia and for Eclipse Che, our service offering for web-based tools or tools in general and please get in contact with us!

Finally, if you are interested in more articles on the topic, e.g. how to extend Eclipse Theia and how to customize, please follow us on Twitter, we will publish the next parts of this article series soon.

No Comments

Post a Comment

Comment
Name
Email
Website

By publishing a comment, you accept the Terms of Use and the Privacy Policy

This site uses Akismet to reduce spam. Learn how your comment data is processed.