Skip to content

Latest commit

 

History

History
370 lines (255 loc) · 11 KB

README.md

File metadata and controls

370 lines (255 loc) · 11 KB
Raw

theia-ext-logo

ECLIPSE THEIA - CLI

Outline

Description

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.

Getting Started

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

Configure

A Theia-based application can be configured via the theia property as described in the application's package.json.

Application Properties

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",
      }
    }
  },

Default Preferences

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 Theme

Default color and icon themes can be configured in theia.frontend.config section:

"theia": {
    "frontend": {
      "config": {
        "defaultTheme": "light",
        "defaultIconTheme": "vs-seti"
      }
    }
  },

Build Target

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.

Electron Frontend Application Config

The electron frontend application configuration provides configuration options for the electron target.
The currently supported configurations are:

  • disallowReloadKeybinding: if set to true, reloading the current browser window won't be possible with the Ctrl/Cmd + r keybinding. It is false by default. Has no effect if not in an electron environment.
  • windowOptions: override or add properties to the electron windowOptions.
{
    "theia": {
        "target": "electron",
        "frontend": {
            "config": {
                "electron": {
                    "disallowReloadKeybinding": true,
                    "windowOptions": {
                        "titleBarStyle": "hidden",
                        "webPreferences": {
                            "webSecurity": false,
                            "nodeIntegration": true,
                            "webviewTag": true
                        }
                    }
                }
            }
        }
    }
}

Using Latest Builds

If you set next in your theia config, then Theia will prefer next over latest as the latest tag.

{
    "theia": {
        "next": "true"
    }
}

Building

Build

The following command can be used to build the application:

Development

theia build --mode development

Production

theia build

Watch

The following command can be used to rebuild the application on each change:

theia build --watch --mode development

Clean

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.

Rebuilding Native Modules

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.

Running

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.

Debugging

To debug the backend server:

theia start --inspect

Theia CLI accepts --inspect node flag: https://nodejs.org/en/docs/inspector/#command-line-options.

Testing

Enabling Tests

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.

Writing Tests

See API Integration Testing docs.

Running Tests

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.

Configuring Tests

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-.

Inspecting Tests

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.

Reporting Test Coverage

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.

Downloading Plugins

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 as 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.theme-defaults": "https://open-vsx.org/api/vscode/theme-defaults/1.62.3/file/vscode.theme-defaults-1.62.3.vsix",
    "vscode-builtin-extension-pack": "https://open-vsx.org/api/eclipse-theia/builtin-extension-pack/1.50.0/file/eclipse-theia.builtin-extension-pack-1.50.0.vsix",
    "vscode-editorconfig": "https://open-vsx.org/api/EditorConfig/EditorConfig/0.14.4/file/EditorConfig.EditorConfig-0.14.4.vsix",
    "vscode-eslint": "https://open-vsx.org/api/dbaeumer/vscode-eslint/2.1.1/file/dbaeumer.vscode-eslint-2.1.1.vsix",
    "rust-analyzer": "https://open-vsx.org/api/rust-lang/rust-analyzer/${targetPlatform}/0.4.1473/file/rust-lang.rust-analyzer-0.4.1473@${targetPlatform}.vsix"
}

As seen in the rust-analyzer entry we can use placeholders in the URLs. Supported placeholders are:

  • The ${targetPlatform} Placeholder, which resolves to a string like win32-x64 describing the local system and architecture. This is useful for adding non-universal plugins.

Please note that in order to use extensionPacks properly you should use namespace.name as the id you give extensions so that when resolving the pack we do not re-download an existing plugin under a different name.

The property theiaPluginsExcludeIds can be used to declare the list of plugin ids to exclude when using extension-packs. The ids referenced by the property will not be downloaded when resolving extension-packs, and can be used to omit extensions which are problematic or unwanted. The format of the property is as follows:

"theiaPluginsExcludeIds": [
  "vscode.cpp"
]

Autogenerated Application

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

Additional Information

License

Trademark

"Theia" is a trademark of the Eclipse Foundation https://www.eclipse.org/theia