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.
>= 18.17.0
and < 21
.
>= 1.7.0
AND < 2.x.x
.node-gyp@8.4.1
Some 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-dev
sudo yum install libsecret-devel
sudo pacman -S libsecret
apk add libsecret-dev
Linux/MacOS
Windows
To build and run the browser example:
git clone https://github.com/eclipse-theia/theia \
&& cd theia \
&& yarn \
&& yarn download:plugins \
&& yarn browser build \
&& yarn browser start
Start your browser on http://localhost:3000.
To build and run the Electron example:
git clone https://github.com/eclipse-theia/theia \
&& cd theia \
&& yarn \
&& yarn download:plugins \
&& yarn electron build \
&& yarn electron start
You can download plugins to use with the examples applications by running:
yarn download:plugins
To run the browser example using SSL use:
git clone https://github.com/eclipse-theia/theia \
&& cd theia \
&& yarn \
&& yarn browser build \
&& yarn download:plugins \
&& yarn browser start --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/#
:
yarn browser start ../.. --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:
yarn
This command downloads dev dependencies, links and builds all TypeScript packages.
To build the example applications:
yarn browser build
yarn electron build
# build both example applications at once:
yarn build:examples
To learn more and understand precisely what's going on, please look at scripts in package.json.
yarn all
This will install dependencies, link and build TypeScript packages, lint, and build the example applications.
Dependencies must be installed before running this command.
yarn 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:
yarn # build TypeScript
yarn lint # lint TypeScript sources
Note that yarn all
does linting.
From the root:
npx run compile @theia/package-name
From the package:
yarn compile
We can start the application from the examples/browser directory with:
yarn 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 browser rebuild
yarn electron start
Rebuilds everything: TypeScript and example applications.
yarn build
To run TypeScript in watch-mode so that TypeScript files are compiled as you modify them:
yarn watch:compile
To rebuild everything each time a change is detected run:
yarn watch:all
To rebuild each time a change is detected in frontend or backend you can run:
# either
yarn browser watch
# or
yarn electron watch
You can use npx
to watch a single package:
npx run watch @theia/the-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 TypeScript 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 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
Launch Browser Backend
configuration.yarn run start
.Launch Browser Frontend
configuration.Launch Browser Backend
configuration.Launch Browser Frontend
configuration.Launch Electron Backend
configuration.Launch Electron Backend
configurationyarn 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.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
.
scoop
.nvm
with scoop: scoop install nvm
.nvm
: nvm install 18.17.0
, then use it: nvm use 18.17.0
. You can list all available Node.js versions with nvm list available
if you want to pick another version.yarn
: scoop install yarn
.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:
npm config set python /path/to/executable/python --global
npm config set msvs_version 2017 --global
Clone, build and run Theia. Using Git Bash as administrator:
git clone https://github.com/eclipse-theia/theia.git \
&& cd theia \
&& yarn \
&& yarn browser build \
&& yarn browser start
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.yarn
, run 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: yarn --unsafe-perm
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。