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.
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.
>= 20 and < 24.
node-gypSome additional tools and libraries are needed depending on your platform:
Linux
sudo apt-get install build-essential
native-keymap native node module dependencies:
keytar native node module dependencies (reference):
sudo apt-get install libsecret-1-devsudo yum install libsecret-develsudo pacman -S libsecretapk add libsecret-devLinux/MacOS
Windows
To build and run the browser example:
git clone https://github.com/eclipse-theia/theia \
&& cd theia \
&& npm install \
&& npm run build:browser \
&& npm run download:plugins \
&& npm run start:browser
Start your browser on http://localhost:3000.
To build and run the Electron example:
git clone https://github.com/eclipse-theia/theia \
&& cd theia \
&& npm install \
&& npm run build:electron \
&& npm run download:plugins \
&& npm run start:electron
You can download plugins to use with the examples applications by running:
npm run download:plugins
To run the browser example using SSL use:
git clone https://github.com/eclipse-theia/theia \
&& cd theia \
&& npm install \
&& npm run download:plugins \
&& npm run build:browser \
&& npm run start:browser --ssl --cert /path/to/cert.crt --certkey /path/to/certkey.key
Start your browser on https://localhost:3000.
Gitpod is a Theia-based IDE for GitHub.
You can start by prefixing any GitHub URL in the Theia repository with gitpod.io/#:
npm run start:browser ../.. --hostname 0.0.0.0
git clone https://github.com/eclipse-theia/theia
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:
THEIA=$PWD/theia
Theia repository has multiple folders:
packages folder contains runtime packages, as the core package and extensions to itdev-packages folder contains devtime packages
examples folder contains example applications, both Electron-based and browser-baseddoc folder provides documentation about how Theia worksscripts folder contains JavaScript scripts used by npm scripts when
installingYou can download dependencies and build TypeScript packages using:
npm install
npm run compile
These commands download dependencies, links and builds all TypeScript packages.
To build the example applications:
npm run build:browser
npm run build:browser-only
npm run build:electron
# build all example applications at once:
npm run build:applications
To learn more and understand precisely what's going on, please look at scripts in package.json.
npm run all
This will install dependencies, link and build TypeScript packages, lint, and build the example applications.
Dependencies must be installed before running this command.
npm run compile
Linting takes a lot of time, this is a limitation from ESLint. We always lint in the GitHub Workflows, but if you want to lint locally you have to do it manually:
npm run lint # lint TypeScript sources
Note that npm run all does linting.
From the root:
npx lerna run compile --scope @theia/core
From the package:
npm run compile
We can start the application from the examples/browser directory with:
npm 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:
npm run rebuild:browser
npm start:electron
Rebuilds everything: TypeScript and example applications.
npm run build
To rebuild everything each time a change is detected run:
npm run watch
To rebuild each time a change is detected in frontend or backend you can run:
# either
npm run watch:browser
# or
npm run watch:electron
You can use npx to watch a single package:
npx lerna run watch --scope @theia/package-name
Once you have built all TypeScript packages once, making a single change and recompiling should be rather quick.
Given this, you can efficiently watch the whole monorepo using TypeScript build mode and have it quickly compiled.
See Watch the core and extension packages.
In this mode, TypeScript only compiles what changed along with its dependents.
run utilityLet 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 npm run 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 lerna run watch --scope @theia/navigator --include-filtered-dependencies --parallel
Launch Browser Backend configuration.npm run start.Launch Browser Frontend configuration.Launch Browser Backend configuration.Launch Browser Frontend configuration.Launch Electron Backend configuration.Launch Electron Backend configurationnpm run start.Attach to Electron Frontend configurationLaunch Electron Backend & Frontend configuration.--${server-name}-inspect arg to the backend server.
--nsfw-watcher-inspect=0 to inspect nsfw watcher processes with dynamic port allocation.--inspect flag are supported: https://nodejs.org/en/docs/inspector/#command-line-options.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.
--hosted-plugin-inspect=9339 arg to the backend server from the command line.
Launch Browser Backend launch configuration which is already pre-configured.Attach to Plugin Host launch configuration.
stopOnEntry flag.The following launch configuration is meant to be used when the Theia project is opened as the main project in VS Code, the following launch configuration is added inside .vscode/launch.json.
${workspaceFolder}/plugins folderLaunch configuration template that will start the backend process, and then attempt to connect on port 9339 to debug the plugin-host sub-process:
{
"name": "Launch VS Code extension as Theia plugin",
"type": "node",
"request": "launch",
"port": 9339,
"timeout": 100000,
"args": [
"${workspaceFolder}/examples/browser/src-gen/backend/main.js",
"${workspaceFolder}",
"--port=3030",
"--hosted-plugin-inspect=9339", // spawn the plugin-host in debug mode
"--plugins=local-dir:${workspaceFolder}/plugins"
],
"stopOnEntry": false,
"sourceMaps": true,
"outFiles": [
"${workspaceFolder}/**/*.js"
],
"internalConsoleOptions": "openOnSessionStart",
"outputCapture": "std"
}
Enable source maps in the plugin's tsconfig.json
{
"compilerOptions": {
"sourceMap": true
}
}
If Webpack is used you should bundle in development mode in the package.json scripts to avoid minification:
webpack --mode development
As well as enabling source map output in the webpack.config.js
module.exports = {
devtool: 'source-map'
}
If you get errors while building like:
(parent folders)/index.d.ts: error TS2300: Duplicate identifier
You can fix it by modifying your tsconfig.json:
{
"compilerOptions": {
"typeRoots": ["./node_modules/@types"]
}
}
How to test section of a pull request description.--inspect arg to the backend server: https://nodejs.org/en/docs/inspector/#command-line-options.--${server-name}-inspect arg to the backend server.
--nsfw-watcher-inspect=0 to inspect nsfw watcher processes with dynamic port allocation.--inspect flag are supported: https://nodejs.org/en/docs/inspector/#command-line-options.--hosted-plugin-inspect arg to the backend server.
--inspect flag are supported: https://nodejs.org/en/docs/inspector/#command-line-options. npm 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.
scoop.nvm with scoop: scoop install nvm.nvm: nvm install lts, then use it: nvm use lts. You can list all available Node.js versions with nvm list available if you want to pick another version.windows-build-tools, see Installing Windows Build Tools.node-gyp documentation offers a useful guide how to install the dependencies manually. The versions required for building Theia are:
Clone, build and run Theia. Using Git Bash as administrator:
git clone https://github.com/eclipse-theia/theia.git \
&& cd theia \
&& npm install \
&& npm run build:browser \
&& npm run start:browser
If you do not have Git Bash installed on your system, get one, or use scoop: scoop install git.
windows-build-tools is required to build Native Nodes modules on Windows. The npm package is now deprecated because NodeJS installer can now install all the required tools that it needs, including Windows Build Tools.PowerShell as Administrator and copy paste the following: npm --add-python-to-path install --global --production windows-build-tools.First make sure that you follow the steps given in the docs correctly.
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
If you see LINK : fatal error LNK1104: cannot open file 'C:\\Users\\path\\to\\node.lib' [C:\path\to\theia\node_modules\drivelist\build\drivelist.vcxproj], then set the Visual Studio version manually with npm config set msvs_version 2017 --global.
If you are facing with EPERM: operation not permitted or permission denied
errors while building, testing or running the application then;
PowerShell, GitBash, Cygwin or whatever
you are using) as an administrator.npm cache clean to fix them.Error: EBUSY: resource busy or locked, rename,
try to disable (or uninstall) your anti-malware software.
See here.If you're still struggling with the build, but you use Windows 10, then you can enable the Windows Subsystem for Linux and you can get a Linux distro for free.
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.
When trying to install with root privileges, you might encounter errors such as
cannot run in wd.
Several options are available to you:
--unsafe-perm flag: npm install --unsafe-perm