How To Build A Custom IDE With Eclipse Theia

|

Integrated Development Environments (IDEs) are essential tools for developers, offering a unified platform for coding, debugging, and managing projects. While traditional IDEs like Visual Studio Code or IntelliJ are powerful, organizations often need tailored development environments to suit specific workflows or technologies. This is where Eclipse Theia comes in.

Eclipse Theia is a modern, extensible, and open-source framework that allows developers to build their own IDEs or customized developer tools. It combines flexibility, modern web technologies, and compatibility with VS Code extensions, making it a powerful foundation for crafting development environments that can be run as desktop or web applications.

In this guide, we’ll walk through everything you need to know about building a custom IDE with Eclipse Theia—from setup to customization—with code examples and practical insights.

Understanding Eclipse Theia

Eclipse Theia is an open-source project developed under the Eclipse Foundation. It’s designed with a modular architecture built on TypeScript, Node.js, and Electron, allowing it to run both in the browser and as a desktop application.

Theia follows a frontend-backend architecture, similar to how VS Code operates:

  • Frontend (Client): Manages the user interface, layout, menus, and interactions.

  • Backend (Server): Handles file system operations, language services, and processes.

This architecture enables Theia to be flexible and extensible, supporting numerous use cases such as:

  • Custom web IDEs for proprietary languages

  • Cloud-based development environments

  • Embedded development tools for specific hardware

  • Enterprise developer portals

Why Build a Custom IDE with Theia?

Building a custom IDE using Theia offers several benefits:

  1. VS Code Extension Compatibility – Theia can reuse most VS Code extensions directly, extending its capabilities easily.

  2. Modular Architecture – Every feature is a separate package, so you can pick and choose only what you need.

  3. Open Source and Extensible – You can freely modify and extend the codebase.

  4. Cross-Platform – Works on Windows, macOS, Linux, and can run in browsers using Electron or web servers.

  5. Custom Branding and Features – Tailor UI, themes, and functionality for your organization’s needs.

Prerequisites

Before diving into coding, ensure you have the following installed:

  • Node.js (version 16 or later)

  • Yarn (for package management)

  • Git

  • Basic knowledge of TypeScript and Node.js

Setting Up a New Theia Application

The easiest way to start building your custom IDE is by using the Theia Application Manager, which scaffolds a Theia-based project quickly.

Create a New Directory

mkdir my-custom-ide
cd my-custom-ide

Initialize a Theia Application

You can use @theia/application-manager to bootstrap your project.

npx @theia/application-manager@latest init my-theia-app
cd my-theia-app

This command generates a ready-to-run Theia application with a predefined structure.

Install Dependencies

yarn

Start the Application

yarn start

This launches Theia in development mode. By default, it runs a backend server and opens a frontend web UI at http://localhost:3000.

You now have a working base IDE that you can customize and extend.

Theia Project Structure

The generated project typically includes:

my-theia-app/
├── browser-app/
├── electron-app/
├── packages/
│ ├── core/
│ ├── editor/
│ ├── file-search/
│ ├── ...
└── package.json

Here’s what each component does:

  • browser-app/: Runs Theia in the browser using a Node.js backend.

  • electron-app/: Builds a desktop version using Electron.

  • packages/: Contains all Theia extensions (modules).

  • package.json: Defines dependencies, build commands, and configuration.

Each Theia feature—such as the editor, terminal, or file explorer—is a separate extension package, making it easy to include or exclude functionality.

Customizing Your Theia IDE

Customization lies at the heart of Eclipse Theia. You can add new features or modify existing ones by creating or configuring Theia extensions.

Create a New Extension

Inside the packages folder, create a new extension package:

cd packages
npx @theia/cli generate my-extension

This will scaffold a new Theia extension named my-extension.

Your new extension will have a structure like:

my-extension/
├── src/
│ ├── browser/
│ │ └── my-extension-frontend-contribution.ts
│ └── node/
│ └── my-extension-backend-contribution.ts
├── package.json
└── README.md

Add a Simple Command

Commands are actions that can be invoked from menus, keybindings, or command palettes. Let’s add one to your new extension.

Edit src/browser/my-extension-frontend-contribution.ts:

import { injectable } from '@theia/core/shared/inversify';
import { Command, CommandContribution, CommandRegistry } from '@theia/core/lib/common';
import { MessageService } from '@theia/core/lib/common/message-service';const HelloWorldCommand: Command = {
id: ‘hello-world.command’,
label: ‘Say Hello’
};@injectable()
export class MyExtensionCommandContribution implements CommandContribution {constructor(private readonly messageService: MessageService) {}registerCommands(registry: CommandRegistry): void {
registry.registerCommand(HelloWorldCommand, {
execute: () => this.messageService.info(‘Hello from My Custom Theia IDE!’)
});
}
}

This adds a simple “Say Hello” command that displays a message when triggered.

Register Your Extension

Add your new extension to the package.json dependencies in the root directory:

"theia": {
"extensions": [
"packages/my-extension"
]
}

Now, rebuild and start your app:

yarn rebuild
yarn start

Open the command palette (Ctrl+Shift+P or Cmd+Shift+P), search for Say Hello, and run it. You should see a message pop up in the IDE.

Adding Custom Menus and Keybindings

Theia allows you to extend menus, context menus, and keyboard shortcuts.

Example: Adding your “Say Hello” command to the main menu.

Edit your frontend contribution file again:

import { MenuContribution, MenuModelRegistry, MAIN_MENU_BAR } from '@theia/core/lib/common/menu';

export class MyExtensionMenuContribution implements MenuContribution {
registerMenus(menus: MenuModelRegistry): void {
menus.registerMenuAction([…MAIN_MENU_BAR, ‘1_custom’], {
commandId: ‘hello-world.command’,
label: ‘Greet Developer’
});
}
}

This adds a “Greet Developer” option to your IDE’s main menu that triggers the “Say Hello” command.

To bind a shortcut key, modify your extension’s package.json:

"keybindings": [
{
"command": "hello-world.command",
"keybinding": "ctrl+alt+h"
}
]

Now pressing Ctrl+Alt+H will show the “Hello” message.

Integrating VS Code Extensions

One of Theia’s biggest advantages is its VS Code extension compatibility. You can install VSIX files or integrate extensions directly from open-source repositories.

For example, to include the Python extension:

yarn theia download:plugins vscode:ms-python.python

This command downloads the Python VS Code extension into your Theia application’s plugin directory. Restart your IDE, and you’ll have Python language support and debugging available.

Building and Packaging the IDE

Once you’re satisfied with your custom features, you can package your IDE for distribution.

Building the Browser Version

yarn build

Then run:

yarn start

This serves the built frontend and backend locally.

Building the Desktop Version (Electron)

yarn build:electron

This creates a distributable Electron application, which can be installed on Windows, macOS, or Linux.

You can further customize your Electron configuration (icons, app name, etc.) in the electron-app directory.

Advanced Customization Ideas

After mastering basic extensions, you can create advanced features like:

  • Custom file types with syntax highlighting and language servers.

  • Project templates for specific frameworks.

  • Integrated terminals or Docker controls.

  • Cloud workspace integration using Kubernetes or GitHub Codespaces APIs.

  • Custom themes and icons to match corporate branding.

Example of a simple custom theme addition in package.json:

"theia": {
"frontend": {
"themes": [
{
"id": "dark-custom",
"label": "Dark Custom Theme",
"uiTheme": "vs-dark",
"path": "path/to/dark-theme.json"
}
]
}
}

This allows you to brand your IDE visually for users.

Troubleshooting Tips

  • Port Conflicts: Change default ports in your launch.json if other services use port 3000.

  • Plugin Compatibility: Some VS Code extensions may require newer APIs not fully supported in Theia—test before deploying.

  • Build Errors: Run yarn clean before rebuilding to clear cached artifacts.

  • Debugging Extensions: Use Chrome Developer Tools to debug frontend issues and Node inspector for backend debugging.

Deploying to the Cloud

You can host your Theia IDE on any cloud platform. Common setups include:

  • Docker Containers – Theia provides official Docker images for quick deployment.

  • Kubernetes Clusters – Deploy scalable, multi-user instances.

  • Gitpod or OpenVSX Integration – For remote developer environments.

A basic Dockerfile example:

FROM theiaide/theia:latest
WORKDIR /home/theia
COPY . .
RUN yarn
EXPOSE 3000
CMD ["yarn", "start"]

Run it:

docker build -t my-theia-ide .
docker run -p 3000:3000 my-theia-ide

Your custom IDE will be available in the browser at http://localhost:3000.

Conclusion

Building a custom IDE with Eclipse Theia empowers developers and organizations to craft tailored, scalable, and extensible development environments. Unlike traditional monolithic IDEs, Theia’s modular design allows you to integrate only the components you need—whether it’s file navigation, language servers, or custom debugging tools.

By following the steps above, you’ve learned how to:

  • Set up and configure a Theia application.

  • Create custom extensions and commands.

  • Add menus, keybindings, and VS Code plugins.

  • Build and deploy the IDE for desktop or cloud use.

Theia’s blend of web technologies, VS Code compatibility, and flexibility make it a top-tier choice for building custom development tools. Whether you’re crafting an in-house IDE for a specialized language, a cloud-based dev environment, or an educational coding platform, Eclipse Theia offers all the foundations you need to create an innovative, feature-rich experience—your IDE, your way.