Switch branches/tags
CHE-9990-2 GH-707 GH-1244 GH-1344 GH-1352 GH-1564 GH-1888 GH-2009 GH-2138 GH-2272 GH-2485 GH-2599 GH-2624 GH-2733 GH-2767 GH-2906 GH-2965 GH-3010 GH-3071 GH-3145 GH-3168 GH-3197 GH-3338 GH-3736 GH-3759 GH-3834 JB/GH-3338 TerminalSelectionColor ab/DebugPluginApi ak/advanced_breakpoints ak/close_widgets_on_resource_disposal ak/get_rid_of_ts_node ak/incremental_document_updates ak/json_rpc_over_web_worker ak/ts_fs_events at/calls at/fix-callhierarchy at/fix-dugite-git at/fix-while-in-md at/http-opener-encoding at/update-xterm at/user-storage-resolver change-minibrowser-link-color claude_langevin comma cpp-ls-trace dave_smith eclipse_foundation_submission electron-3 epatpol/preferences fix-terminal-plugin-api-docs folder-pick-api generate-app-name-patch git-diff git-navigable-list-widget-react-migration issue-2831 jk/gh3204 jk/gh3791 loader logPath logPath2 master mp/browser-test-fix mp/build-management mp/cpp-build-task mp/cpp-debug-ext mp/electron-dev-tools mp/electron-main-simple mp/electron-startup-menu mp/example-hybrid mp/fix-slow-load mp/issue-2831 mp/missing-theia-dep mp/tabnav++ mp/watcher-awaiting mp/willChangeModelOnSave msp_issue1923 nicolas_viens olivier_champagne plugin-api-documentation plugin-ext-open prefComent process-args queryWorkAround rerun-tasks revert-3598-vf/file-icons se/xtend-support search-in-workspace-react-tree simark/christina_gauthier simark/felix_paradis simark/process-async simark/python-venv simark/samuel_legault skip-duplicates startTaskEvent svenefftinge-patch-1 theia#2786 ui-test-temp-workspace unbreak-tslint vf/clean-up-plugin vf/git-changes-status-bar vf/git-misc vf/search-results vf/sync-stale vf/ui-tests vplugin-id vscode-debug-protocol waitfor william_noel
Nothing to show
Find file Copy path
342 lines (225 sloc) 13 KB

This file contains tips to help you take (and understand) your first steps in the world of Theia development. Are you in a hurry? See the Quick Start.

How to build Theia and the example applications

Theia is a framework to build IDEs, so you can't really "run" Theia itself. However, you can run the example applications included in its repository. One is a browser-based IDE and the other is the Electron-based equivalent.

The following instructions are for Linux and macOS.

For Windows instructions click here.


  • Node.js >= 8.x, < 9.x.
    • Preferably, use version 8.11.4, it has the active LTS.
    • Node.js 9.x is untested.
    • Node.js 10.x is not supported yet due to a known issue in nsfw.
  • Yarn package manager v1.7.0
  • git (If you would like to use the Git-extension too, you will need to have git version 2.11.0 or higher.)

nvm is recommended to easily switch between Node.js versions.

Quick Start

To build and run the browser example:

git clone \
&& cd theia \
&& yarn \
&& cd examples/browser \
&& yarn run start

Start your browser on http://localhost:3000.

To build and run the Electron example:

git clone \
&& cd theia \
&& yarn \
&& yarn run rebuild:electron \
&& cd examples/electron \
&& yarn run start

Run the browser example with SSL

To run the browser example using SSL use:

git clone \
&& cd theia \
&& yarn \
&& cd examples/browser \
&& yarn run start --ssl --cert /path/to/cert.crt --certkey /path/to/certkey.key

Start your browser on https://localhost:3000.

Run the browser example with Gitpod

Gitpod is a Theia-based IDE for GitHub. You can start by prefixing any GitHub URL in the Theia repository with

  • Open to start development with the master branch.

  • Gitpod will start a properly configured for Theia development workspace, clone and build the Theia repository.

  • After the build is finished, run from the terminal in Gitpod:

      cd examples/browser \
      && yarn run start ../.. --hostname

Clone the repository

git clone

The directory containing the Theia repository will now be referred to as $THEIA, so if you want to copy-paste the examples, you can set the THEIA variable in your shell:


The repository structure

Theia repository has multiple folders:

  • packages folder contains runtime packages, as the core package and extensions to it
  • dev-packages folder contains devtime packages
    • @theia/cli is a command line tool to manage Theia applications
    • @theia/ext-scripts is a command line tool to share scripts between Theia runtime packages
  • examples folder contains example applications, both Electron-based and browser-based
  • doc folder provides documentation about how Theia works
  • scripts folder contains JavaScript scripts used by npm scripts when installing
  • the root folder lists dev dependencies and wires everything together with Lerna

Build core, extensions and examples packages

You can download dependencies and build it using:


This command downloads dev dependencies, links and builds all packages. To learn more and understand precisely what's going on, please look at scripts in package.json.

Build extension packages individually

From the root:

npx run build @theia/package-name

From the package:

yarn --ignore-scripts && yarn build

Run the browser-based example application

We can start the application from the examples/browser directory with:

yarn run start

This command starts the backend application listening on port 3000. The frontend application should be available on http://localhost:3000.

If you rebuild native Node.js packages for Electron then rollback these changes before starting the browser example by running from the root directory:

yarn run rebuild:browser

Run the Electron-based example application

From the root directory run:

yarn run rebuild:electron

This command rebuilds native Node.js packages against the version of Node.js used by Electron.

It can also be started from the examples/electron directory with:

yarn run start


In the root directory run:

yarn run build


Watch the core and extension packages

To rebuild each time a change is detected run:

yarn run watch

Watch the examples

To rebuild each time a change is detected in frontend or backend you can run:

yarn run watch

Watch a specific package

You can use npx to watch a single package:

npx run watch @theia/the-package-name

Watch a specific package and its local upstream dependencies

Let assume you have to work for instance in the @theia/navigator extension. But you might have to apply changes in any of its upstream dependencies such as @theia/filesystem or @theia/core, you can either do yarn watch which could be super expensive, as it watches all the packages. Or you can do npx run watch @theia/navigator and npx run watch @theia/filesystem and npx run watch @theia/core in three individual shells. Or you can do the following single-liner:

npx run watch @theia/navigator --include-filtered-dependencies --parallel


Debug the browser example's backend

  • In VS Code: start the debug tab and run the Launch Backend configuration.

Debug the browser example's frontend

  • Start the backend by using yarn run start.
  • In a browser: Open http://localhost:3000/ and use the dev tools for debugging.
  • In VS Code: start the debug tab and run the Launch Frontend configuration.

Debug the browser example's frontend and backend at the same time

  • In VS Code: Start the debug tab and run the Launch Backend configuration.
  • Then run the Launch Frontend configuration.

Debug the Electron example's backend

  • In VS Code: Start the debug tab and run the Launch Electron Backend configuration.

Debug the Electron example's frontend

  • Start the backend by using yarn run start.
  • In Electron: Help -> Toggle Electron Developer Tools.

Debug IPC servers

  • Pass --${server-name}-inspect arg to the backend server.
  • Attach the debugger to the logged port.

In order to look up server-name run the backend server with --log-level=debug flag to enable logging of IPC servers instantiation. You should be able to see message of [${server-name}: ${server-PID}]: IPC started format, like [nsfw-watcher: 37557] IPC started.


See the testing documentation.

Code coverage

yarn run test

By default, this will generate the code coverage for the tests in an HTML format, which can be easily viewed with your browser (Chrome/Firefox/Edge/Safari etc.) by opening packages/<package name>/coverage/index.html.

Building on Windows

Run cmd.exe as an administrator and install choco by copy-pasting the command to your console:

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString(''))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

Install yarn via choco. The yarn installation ensures that you will have Node.js and npm too:

choco install yarn

Install git via choco

choco install git

Install the correct version of yarn (The version is important)

choco install yarn --version 1.7.0 -y

Install Windows-Build-Tools. Run PowerShell as an administrator and copy-paste the below command:

npm --add-python-to-path install --global --production windows-build-tools

Clone, build and run Theia. Using Git Bash as administrator:

git clone && cd theia && yarn && cd examples/browser && yarn run start



The start command will start a watcher on many files in the theia directory. To avoid ENOSPC errors, increase your default inotify watches.

It can be done like so:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p


Theia uses native modules and also requires Python 2.x to be installed on the system when building the application.

  • One can get all the all-in-one packages by running npm install --global windows-build-tools script.

If you are facing with EPERM: operation not permitted or permission denied errors while building, testing or running the application then;

  • You don't have write access to the installation directory.
  • Try to run your command line (PowerShell, GitBash, Cygwin or whatever you are using) as an administrator.
  • The permissions in the NPM cache might get corrupted. Please try to run npm cache clean to fix them.
  • If you experience issues such as Error: EBUSY: resource busy or locked, rename, try to disable (or uninstall) your anti-malware software. See here.
  • Still having issues on Windows? File a bug. We are working on Linux or OS X operating systems. Hence we are more than happy to receive any Windows-related feedbacks, bug reports.

If you have accidentally installed the wrong yarn version, you have to remove it, then reinstall it.

  • Run PowerShell as an administrator.
  • Run: choco uninstall yarn -y
  • Run: choco install yarn --version 1.7.0 -y


You need to have the Xcode command line tools installed in order to build and run Theia. You can install the tools by running

xcode-select --install

If you already have Xcode installed, but you see the xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance error, you need to run the following command to fix it: sudo xcode-select --switch /Library/Developer/CommandLineTools.

The solution is the same if you have updated to 10.14 (Mojave) and you can see the gyp: No Xcode or CLT version detected! error. More details here.

Root privileges errors

When trying to install with root privileges, you might encounter errors such as cannot run in wd.

Several options are available to you:

  • Install without root privileges
  • Use the --unsafe-perm flag: yarn --unsafe-perm