- Description
- Getting Started
- Configure
- Building
- Rebuilding Native Modules
- Running
- Debugging
- Testing
- Downloading Plugins
- Autogenerated Application
The @theia/cli
package provides helpful scripts and commands for extension and application development.
The contributed theia
, is a command line tool to manage Theia-based applications.
Install @theia/cli
as a dev dependency in your application.
With yarn:
yarn add @theia/cli@next --dev
With npm:
npm install @theia/cli@next --save-dev
A Theia-based application can be configured via the theia
property as described in the application's package.json
.
It is possible Application Properties
for a given application.
For example, an application can define it's applicationName
using the following syntax:
"theia": {
"frontend": {
"config": {
"applicationName": "Custom Application Name",
}
}
},
If required, an application can define for a given preference, the default value.
For example, an application can update the preference value for files.enableTrash
based on it's requirements:
"theia": {
"frontend": {
"config": {
"preferences": {
"files.enableTrash": false
}
}
}
},
Default color and icon themes can be configured in theia.frontend.config
section:
"theia": {
"frontend": {
"config": {
"defaultTheme": "light",
"defaultIconTheme": "vs-seti"
}
}
},
The following targets are supported: browser
and electron
. By default browser
target is used.
The target can be configured in the package.json
via theia/target
property, e.g:
{
"theia": {
"target": "electron"
},
"dependencies": {
"@theia/electron": "latest"
}
}
For electron
target applications, is it mandatory to include Electron runtime dependencies. The @theia/electron
package is the easiest way to install the necessary dependencies.
The electron
frontend application configuration provides configuration options for the electron
target.
The currently supported configurations are:
disallowReloadKeybinding
: if set totrue
, reloading the current browser window won't be possible with the Ctrl/Cmd + r keybinding. It isfalse
by default. Has no effect if not in an electron environment.windowOptions
: override or add properties to the electronwindowOptions
.
{
"theia": {
"target": "electron",
"frontend": {
"config": {
"electron": {
"disallowReloadKeybinding": true,
"windowOptions": {
"titleBarStyle": "hidden",
"webPreferences": {
"webSecurity": false,
"nodeIntegration": true,
"webviewTag": true
}
}
}
}
}
}
}
If you set next
in your theia config, then Theia will prefer next
over latest
as the latest tag.
{
"theia": {
"next": "true"
}
}
The following command can be used to build the application:
Development
theia build --mode development
Production
theia build
The following command can be used to rebuild the application on each change:
theia build --watch --mode development
The following command can be used to clean up the build result:
In order to clean up the build result:
theia clean
Arguments are passed directly to webpack. Use --help
to learn which options are supported.
In order to run Electron targets, one should rebuild native node modules for an electron version:
theia rebuild
To rollback native modules, change the target to browser
and run the command again.
To run the backend server:
theia start
For the browser target a server is started on http://localhost:3000 by default.
For the electron target a server is started on localhost
host with the dynamically allocated port by default.
Arguments are passed directly to a server, use --help
to learn which options are supported.
To debug the backend server:
theia start --inspect
Theia CLI accepts --inspect
node flag: https://nodejs.org/en/docs/inspector/#command-line-options.
First enable expose-loader
in webpack.config.js
to expose modules from bundled code to tests
by un-commenting:
/**
* Expose bundled modules on window.theia.moduleName namespace, e.g.
* window['theia']['@theia/core/lib/common/uri'].
* Such syntax can be used by external code, for instance, for testing.
config.module.rules.push({
test: /\.js$/,
loader: require.resolve('@theia/application-manager/lib/expose-loader')
}); */
After that run theia build
again to expose modules in generated bundle files.
See API Integration Testing docs.
To start the backend server and run API tests against it:
theia test
After running test this command terminates. It accepts the same arguments as start
command,
but as well additional arguments to specify test files, enable inspection or generate test coverage.
To specify test files:
theia test . --test-spec=./test/*.spec.js --plugins=./plugins
This command starts the application with a current directory as a workspace,
load VS Code extensions from ./plugins
and run test files matching ./test/*.spec.js
glob.
Use theia test --help
to learn more options. Test specific options start with --test-
.
To inspect tests:
theia test . --test-spec=./test/*.spec.js --test-inspect --inspect
This command starts the application server in the debug mode as well as open the Chrome devtools to debug frontend code and test files. One can reload/rerun code and tests by simply reloading the page.
Important! Since tests are relying on focus, while running tests keep the page focused.
To report test coverage:
theia test . --test-spec=./test/*.spec.js --test-coverage
This command executes tests and generate test coverage files consumable by Istanbul.
The @theia/cli
package provides a utility for applications to define and download a list of plugins it requires as part of their application using the command:
theia download:plugins
This utility works by declaring in the package.json
a location to store downloaded plugins, as well defining each plugin the application wishes to download.
The property theiaPluginsDir
describes the location of which to download plugins (relative to the package.json
), for example:
"theiaPluginsDir": "plugins",
The property theiaPlugins
describes the list of plugins to download, for example:
"theiaPlugins": {
"vscode-builtin-bat": "https://github.com/theia-ide/vscode-builtin-extensions/releases/download/v1.39.1-prel/bat-1.39.1-prel.vsix",
"vscode-builtin-clojure": "https://github.com/theia-ide/vscode-builtin-extensions/releases/download/v1.39.1-prel/clojure-1.39.1-prel.vsix",
}
This package can auto-generate application code for both the backend and frontend, as well as webpack configuration files.
When targeting Electron, the electron-main.js
script will spawn the backend process in a Node.js sub-process, where Electron's API won't be available. To prevent the generated application from forking the backend, you can pass a --no-cluster
flag. This flag is mostly useful/used for debugging.
# when developing a Theia application with @theia/cli:
yarn theia start --no-cluster
# when starting a bundled application made using @theia/cli:
bundled-application.exe --no-cluster
- Eclipse Public License 2.0
- 一 (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception
"Theia" is a trademark of the Eclipse Foundation https://www.eclipse.org/theia