Extending/Adopting the Theia IDE
This guide provides an overview on how to extend and customize the Theia IDE to your own custom IDE or tool. In this scenario, the Eclipse Theia IDE is an example product used as a reference on how to build desktop IDE-like products based on the Eclipse Theia framework. If you just want to use the Theia IDE, see the user guide
Please note that adopting the Theia IDE as a basis is just one of several ways to get started with building a Theia-based application. We recommend reading the article "Build your own IDE/Tool" as a first step. Furthermore, this guide is focused on building a desktop app. We also provide an experimental Docker version of the Theia IDE as an alternative.
The Theia IDE assembles a selected subset of existing Theia features and extensions. We provide installers for the Theia IDE to be downloaded (see links below). In the respective git repository you can also find the source code for the Theia IDE and its installers.
This documentation will use these sources as a template. We will explain how to customize this template so that you can build your own custom Theia-based product including installers and packaging for installing the desktop-based version of your custom product on all major operating systems. Please note that the technical name (e.g. in the source code) for the Theia IDE is "Theia Blueprint" to avoid confusion with the generic term "IDE".
- Building a product and installers
- Signing
- Adding/removing Features
- Updating Bundled VS Code Extensions
- Customizing Theia Extensions
- Branding
- Configure Publish and Update
Building a product and installers
The Theia IDE build uses electron-builder to package the product as a desktop application.
The product can be built and packaged with yarn. Note that you usually can only package the product for the operating system you execute the build on. For more information see the electron-builder documentation on multi-platform builds.
The following commands may be run from the root directory of the repository.
To install dependencies and build the application, simply execute yarn
.
You can also directly run the unpackaged application, e.g. to test it during development with yarn electron start
.
With yarn electron package
, you package the application into an executable file for your current operating system.
The packaged application will be located in applications/electron/dist
.
The folder applications/electron/dist/<OS>-unpackaged
will contain the files that are bundled into the final packaged executable.
For Linux, this is an executable .AppImage
, for Windows a .exe
installer, and a .dmg
disk image for macOS.
You can also just create the unpackaged content by running yarn electron package:preview
.
This is useful to see the bundled files and saves time compared to a full package.
To publish the current version, the command yarn electron deploy
can be used.
For more information on publishing also see section "Configure publish and update".
Signing
Electron-builder supports signing the packaged application on Windows and macOS.
The current signing scripts for the Theia IDE are located in applications/electron/scripts
.
The file after-pack.js
is the current entry point for the configured signing via Eclipse infrastructure.
However, as signing is highly dependent on your setup, see the electron builder’s signing documentation on how to properly set up your own signing.
Adding/Removing Features
The Theia IDE is based on the Theia platform, which is a flexible and adaptable platform for build tools and IDEs. Therefore, you can adapt the feature set and general appearance of the Theia IDE to your custom requirements with almost no limits. The Theia platform provides two mechanism to add your custom extensions: VS Code extensions and Theia extensions. Please have a look at the overview about Theia extension capabilities for details. When assembling a product such as the Theia IDE, you can freely decide, which VS Code extensions and Theia extensions are part of it and thereby influence the feature set of your custom product. The following two sections describe how to modify which VS Code Extensions and which Theia extensions are part of your product. Please also note that you can allow users of a Theia-based tool to install VS Code extensions at runtime.
Updating Bundled VS Code Extensions
All VS Code extensions that are already included in the product at start-up ("built-ins"), are defined in applications/electron/package.json
.
They are listed under the theiaPlugins
property as key-value pairs.
The keys can be freely chosen as long as they represent a valid folder name and are unique within the theiaPlugins
property.
We suggest using the extension’s unique identifier.
The value is the download URL of the extensions.
It will automatically be downloaded during the application’s build process.
Any new plugin will be automatically downloaded the next time one of the following npm scripts is executed:
install
(which is the same as just runningyarn
)prepare
download:plugins
To remove an extension from the product, simply delete its entry.
If plugins were not already downloaded, no further steps are required as downloaded plugins are ignored via gitignore.
However, previously downloaded plugins are not automatically removed.
Therefore, you need to remove its folder from the applications/electron/plugins
folder.
Alternatively, you can remove the whole applications/electron/plugins
folder and execute yarn electron download:plugins
to download all defined plugins.
Extension sources
We use the Open VSX Registry of the Eclipse Foundation to install extensions. It is an open and community-driven VS Code extension marketplace. More information can be found at eclipse.org.
Customizing Theia Extensions
Eclipse Theia extensions can be added through dependencies
in applications/electron/package.json
.
Like any other dependency, it will be installed via yarn.
Similarly, removing an extension works by removing it from dependencies
.
For extensions already published on npm (or your private npm registry) this is all you need to do.
An alternative approach is developing your extension inside Theia IDE’s mono repo. The advantage of doing this is that you don’t need to publish the extension and can build the product with the local version of the extension. This is facilitated by the lerna build already configured in the Theia IDEs’s repository. It links the product and all extensions in the repository together during the build.
The easiest way to create a new extension is to use the official yeoman generator for Theia extensions.
Assuming you have yeoman globally installed on your system, simply create a new extension in the repository root with yo theia-extension --standalone
.
The --standalone
flag is used to only create an extension but not a whole Theia application frame because it is already provided by the Theia IDE.
After successfully generating the extension, add its folder name to the Theia IDEs’s root package.json
in the workspaces property.
After adding the extension to the dependencies in applications/electron/package.json
as described above, the new extension will be part of the built product.
Branding
You can also add your own branding to the product by customizing the application icons and title, the welcome page and the About dialog. In addition, some parts of the installer can be customized.
Customizing the App
Application Window Title
The window title is the application’s name if no workspace is opened and <workspace name> — <application name>
if a workspace is opened.
The application name can be adapted in applications/electron/package.json
:
Open the file and adapt the value of property theia.frontend.config.applicationName
to the desired name.
Application Icons
Application icons are located in applications/electron/resources/
.
Simply replace them with your own icons.
Because each operating system handles icons differently, they should all be replaced to ensure proper use.
They map as follows:
- macOS: icons.icns
- Windows: icon.ico
- Linux: icons subfolder
Customizing the Welcome Page
The Eclipse Theia welcome page can be customized by binding a custom WidgetFactory
for Theia’s GettingStartedWidget
.
This is done with the Theia IDE in the theia-blueprint-product extension.
The easiest way to customize the welcome page is to adapt the class TheiaBlueprintGettingStartedWidget
in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-getting-started-widget.tsx
.
The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts
like this:
bind(TheiaBlueprintGettingStartedWidget).toSelf();
bind(WidgetFactory).toDynamicValue(context => ({
id: GettingStartedWidget.ID,
createWidget: () => context.container.get<TheiaBlueprintGettingStartedWidget>(TheiaBlueprintGettingStartedWidget),
})).inSingletonScope();
To use another custom widget, remove this code and bind your widget correspondingly.
Customizing the About Dialog
The Eclipse Theia about dialog can be customized by binding a custom subclass of Theia’s AboutDialog
class to AboutDialog
.
This is done with Theia IDE in the theia-blueprint-product extension.
The easiest way to customize the about dialog is to adapt the class TheiaBlueprintAboutDialog
in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-about-dialog.tsx
.
The widget is bound in theia-extensions/theia-blueprint-product/src/browser/theia-blueprint-frontend-module.ts
like this:
isBound(AboutDialog) ? rebind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope() : bind(AboutDialog).to(TheiaBlueprintAboutDialog).inSingletonScope();
To use another custom dialog widget, remove this code, extend Theia’s AboutDialog class, and (re)bind it as above.
Customizing the Preferences
The default preferences directory in Eclipse Theia IDE is .theia-blueprint
and is located as described in the Preferences documentation. You can customize this location by modifying theia-blueprint-variables-server.ts
.
Customizing the Electron Splash Screen
Since Theia 1.49.0
Theia Electron applications support displaying a splash screen before showing the main window.
The splash screen can be enabled within the application package.json
's Theia options by providing an object at theia.frontend.config.electron.splashScreenOptions
with the following properties:
{
content: string // <mandatory> path to the content to render within the splash screen, resolved from application root
width: number // default 640
height: number // default 480
minDuration: number // minimum amount of time in milliseconds to show the splash screen before main window is shown. default 0
maxDuration: number // maximum amount of time in milliseconds before splash screen is removed and main window is shown. default 30000
}
If not configured otherwise via minDuration
, the splash screen will be shown until the frontend is ready, i.e. when the loading spinner is gone.
Then the splash screen will be closed and the main window is shown.
Showing Windows Early
The main window / splash screen can be configured to be shown "early", i.e. the window will be shown before it's ready to render content.
By default this is true
to give the user visual feedback as early as possible.
If you prefer only showing the main window / splash screen once they are ready to render content, then you can configure theia.frontend.config.electron.showWindowEarly: false
in your application's package.json
.
Customizing the Installer
The installers are created using electron-builder.
The corresponding configuration file is located at applications/electron/electron-builder.yml
.
Installer File Base Name
The installer files’ base names are defined by the productName
property in applications/electron/electron-builder.yml
.
Windows Installer
As is typical for Windows applications, there is an installation wizard for the Windows version of the Theia IDE. The installer is configured in the nsis section of the configuration file. Available customizations include settings such as:
- Icons
- Sidebar image
- License
- One click installation
- Automatic application start after installation
- Whether users can change the installation directory
More details on available options and how they can be customized can be found in the official electron builder documentation. This documentation also includes information about more advanced features such as custom NSIS scripts.
Configure Publish and Update
The Theia IDE uses electron-builder to create and publish installers. It also uses electron-updater, developed by the electron-builder organization, to provide automatic updates of the installed application.
There are various deployment targets which can be configured in the applications/electron/package.json
and applications/electron/electron-builder.yml
as documented here in the Electron Builder documentation.
Multiple publish configurations can be configured.
Thereby, the first one is automatically used by the updater to look for available updates.
The currently used generic publishing method does not automatically publish to the specified server, but is just used as the lookup location for the updater.