Skip to content

Latest commit

 

History

History
194 lines (131 loc) · 8.68 KB

Migration.md

File metadata and controls

194 lines (131 loc) · 8.68 KB
Raw

Migration Guide

Description

The following guide highlights potential migration steps necessary during theia upgrades discovered when adopting the framework. Please see the latest version (master) for the most up-to-date information. Please contribute any issues you experienced when upgrading to a newer version of Theia to this document, even for previous releases.

Guide

General

Due to a colors.js issue, a resolution may be necessary for your application in order to workaround the problem:

For example:

"resolutions": {
    "**/colors": "<=1.4.0"
}

v1.24.0

node-gyp 8.4.1

The electron-rebuild dependency was upgraded which in turn upgraded node-gyp to v8.4.1. This version of node-gyp does not support Python2 (which is EOL) so Python3 is necessary during the build.

From WebSocket to Socket.io

This is a very important change to how Theia sends and receives messages with its backend.

This new Socket.io protocol will try to establish a WebSocket connection whenever possible, but it may also setup HTTP polling. It may even try to connect through HTTP before attempting WebSocket.

Make sure your network configurations support both WebSockets and/or HTTP polling.

Monaco 1.65.2

This version updates the Monaco code used in Theia to the state of VSCode 1.65.2, and it changes the way that code is consumed from ASM modules loaded and put on the window.monaco object to ESM modules built into the bundle using Webpack.

ASM to ESM

Two kinds of changes may be required to consume Monaco using ESM modules.

  • If your application uses its own Webpack config rather than that generated by the @theia/dev-packages, you will need to update that config to remove the CopyWebpackPlugin formerly used to place Monaco code in the build folder and to build a separate entrypoint for the editor.worker. See the changes here
  • If your application uses its own frontend generator, you should modify the code that generates the index.html to load the script containing the bundle into the body element rather than the head. See changes here
  • References to the window.monaco object should be replaced with imports from @theia/monaco-editor-core. In most cases, simply adding an import import * as monaco from '@theia/monaco-editor-core' will suffice. More complex use cases may require imports from specific parts of Monaco. Please see the PR for details, and please post any questions or problems there.

Using ESM modules, it is now possible to follow imports to definitions and to the Monaco source code. This should aid in tracking down issues related to changes in Monaco discussed below.

Changes to Monaco

The Monaco API has changed in significant ways since the last uplift. One of the most significant is the handling of overrides to services instantiated by Monaco.

  • The style of service access monaco.StaticServices.<ServiceName>.get() is no longer available. Instead, use StaticServices.get(<ServiceIdentifier>) with a service identifier imported from @theia/monaco-editor-core.
  • Any service overrides that should be used for all instantiations in Monaco should be passed to the first call of StaticServices.initialize. The first call is used to set the services for all subsequent calls. Overrides passed to subsequent calls to StaticServices.initialize will be ignored. To change the overrides used, please override MonacoFrontendApplicationContribution.initialize.
  • Services that should be used for a particular instantiation must be passed to a child of the global IInstantiationService. See MonacoEditor.getInstantiationWithOverrides for an example.

Other changes include a number of changes of name from mode -> language and changes of interface. Please consult the PR or the Monaco source code included with @theia/monaco-editor-core.

Breaking changes in Theia

Please see the CHANGELOG for details of changes to Theia interfaces.

v1.23.0

TypeScript 4.5.5

If you are using TypeScript <= 4.5.5 and you encounter issues when building your Theia application because your compiler fails to parse our type definitions, then you should upgrade to TypeScript >= 4.5.5.

Socket.io

If you are deploying multiple Theia nodes behind a load balancer, you will have to enable sticky-sessions, as it is now required by the new WebSocket implementation using Socket.io protocol.

For more details, see the socket.io documentation about using multiple nodes.

v1.22.0

Electron Update

Electron got updated from 9 to 15, this might involve some modifications in your code based on the new APIs.

See Electron's documentation.

Most notably the electron.remote API got deprecated and replaced with a @electron/remote package.

Theia makes use of that package and re-exports it as @theia/core/electron-shared/@electron/remote.

See @theia/core re-exports documentation.

Lastly, Electron must now be defined in your application's package.json under devDependencies.

theia build will automatically add the entry and prompt you to re-install your dependencies when out of sync.

v1.21.0

Frontend Source Maps

The frontend's source map naming changed. If you had something like the following in your debug configurations:

      "sourceMapPathOverrides": {
        "webpack://@theia/example-electron/*": "${workspaceFolder}/examples/electron/*"
      }

You can delete this whole block and replace it by the following:

      "webRoot": "${workspaceFolder}/examples/electron"

v1.17.0

ES2017

  • Theia was updated to ES2017
    • es5 VS Code extensions and Theia plugins are still supported
    • If you require an es5 codebase you should be able to transpile back to es5 using webpack
    • The following code transpiles back to an es2015 codebase: 
      config.module.rules.push({
    test: /\.js$/,
    use: {
        loader: 'babel-loader',
        options: {
            presets: [['@babel/preset-env', { targets: { chrome: '58', ie: '11' } }]],
        }
    }
});
    • Replace the targets with the ones that are needed for your use case
    • Make sure to use [email protected]. Theia requires inversify@^5.0.1 which means that 5.1.1 is compatible, but your lockfile might reference an older version.

v1.16.0

Release

  • N/A.

v1.15.0

Release

Keytar:

  • keytar was added as a dependency for the secrets API. and may require libsecret in your particular distribution to be functional:

    • Debian/Ubuntu: sudo apt-get install libsecret-1-dev
    • Red Hat-based: sudo yum install libsecret-devel
    • Arch Linux: sudo pacman -S libsecret
    • Alpine: apk add libsecret-dev

  • It is possible that a yarn resolution is necessary for keytar to work on older distributions (the fix was added in 1.16.0 by downgrading the dependency version):

    "resolutions": {
  "**/keytar": "7.6.0",
}

  • keytar uses prebuild-install to download prebuilt binaries. If you are experiencing issues where some shared libraries are missing from the system it was originally built upon, you can tell prebuild-install to build the native extension locally by setting the environment variable before performing yarn:

    # either:
export npm_config_build_from_source=true
yarn
# or:
npm_config_build_from_source=true yarn

Webpack

  • The version of webpack was upgraded from 4 to 5 and may require additional shims to work properly given an application's particular setup.

  • The webpack dependency may need to be updated if there are errors when performing a production build of the application due to a bogus webpack-sources dependency. The valid webpack version includes ^5.36.2 <5.47.0. If necessary, you can use a yarn resolution to fix the issue:

    "resolutions": {
  "**/webpack": "5.46.0",
}