# 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

_ESBuild_:

In addition to `webpack`, Theia is now also supporting [`ESBuild`](https://esbuild.github.io/) for bundling the application (frontend+backend). We will soon deprecate and then remove the `webpack` bundling option. Adopters can already use the ESBuild based bundler simply by deleting their `webpack.config.js`, which will automatically generate an `esbuild.mjs` file upon the next build.

In case you have added your own bundling instructions to the `webpack.config.js`, these need to be migrated to the ESBuild based bundler.

Note that as a part of this change, the `@theia/native-webpack-plugin` dependency has been renamed to `@theia/bundle-plugin`.

The generated ESBuild configuration includes a `sourceMapPathsPlugin` that rewrites the `sources` field of emitted source maps to absolute `file://` URLs. This makes browser and Node debug launch configurations work without any custom `webRoot` or `sourceMapPathOverrides`: a minimal Chrome launch like

```json
{
    "name": "Launch Browser Frontend",
    "type": "chrome",
    "request": "launch",
    "url": "http://localhost:3000/"
}
```

is sufficient to bind breakpoints in the original sources. If you have a customized `esbuild.mjs` that is not automatically regenerated (because the `gen-esbuild` import was removed), either regenerate it (delete `esbuild.mjs` and rerun `theia build`) or manually add `sourceMapPathsPlugin()` from `@theia/bundle-plugin` to the `plugins` array of each build target. The plugin is a no-op when source maps are disabled (production builds).

_Builtin Extension Pack_:

If you are using the [`eclipse-theia.builtin-extension-pack@1.79.0`](https://open-vsx.org/extension/eclipse-theia/builtin-extension-pack) extension pack you may need to include the [`ms-vscode.js-debug`](https://open-vsx.org/extension/ms-vscode/js-debug) and [`ms-vscode.js-debug-companion`](https://open-vsx.org/extension/ms-vscode/js-debug-companion) plugins for JavaScript debug support.
There was an issue when the publishing of the pack which excluded these necessary builtins.

For example, in your application's `package.json`:

```json
"theiaPlugins": {
  "eclipse-theia.builtin-extension-pack": "https://open-vsx.org/api/eclipse-theia/builtin-extension-pack/1.79.0/file/eclipse-theia.builtin-extension-pack-1.79.0.vsix",
  "ms-vscode.js-debug": "https://open-vsx.org/api/ms-vscode/js-debug/1.78.0/file/ms-vscode.js-debug-1.78.0.vsix",
  "ms-vscode.js-debug-companion": "https://open-vsx.org/api/ms-vscode/js-debug-companion/1.1.2/file/ms-vscode.js-debug-companion-1.1.2.vsix"
}
```

_msgpackr_:

If you're experiencing [`maximum callstack exceeded`](https://github.com/eclipse-theia/theia/issues/12499) errors you may need to downgrade the version of `msgpackr` pulled using a [yarn resolution](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/).

```
rpc-message-encoder.ts:151 Uncaught (in promise) Error: Error during encoding: 'Maximum call stack size exceeded'
    at MsgPackMessageEncoder.encode (rpc-message-encoder.ts:151:23)
    at MsgPackMessageEncoder.request (rpc-message-encoder.ts:137:14)
    at RpcProtocol.sendRequest (rpc-protocol.ts:161:22)
    at proxy-handler.ts:74:45
```

For the best results follow the version used and tested by the framework.

For example:

```json
"resolutions": {
    "**/msgpackr": "1.8.3"
}
```

_socket.io-parser_:

Prior to [`v1.31.1`](https://github.com/eclipse-theia/theia/releases/tag/v1.31.1), a [resolution](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) might be necessary to work-around a recently discovered [critical vulnerability](https://security.snyk.io/vuln/SNYK-JS-SOCKETIOPARSER-3091012) in one of our runtime dependencies [socket.io-parser](https://github.com/socketio/socket.io-parser).

For example:

```json
"resolutions": {
    "**/socket.io": "^4.5.3",
    "**/socket.io-client": "^4.5.3"
}
```

_Terminal Shell Integration Scripts_:

The `@theia/terminal` package now includes shell integration scripts for Bash and Zsh (`packages/terminal/src/node/shell-integrations/`). These scripts are used at runtime by `ShellIntegrationInjector` to inject shell integration into terminal sessions, enabling features such as command history tracking and command separators.

For **browser** applications, the generated webpack configuration automatically copies these scripts to `lib/backend/shell-integrations/` via `CopyWebpackPlugin`.

For **Electron** applications that use custom packaging (e.g. `electron-builder`, `electron-forge`), you must ensure the `shell-integrations` directory is included in your packaged distribution. The scripts must be accessible relative to the compiled `ShellIntegrationInjector` module at `lib/backend/shell-integrations/`. If these files are missing, terminal shell integration will silently fail to activate.

For example, in an `electron-builder` configuration, ensure the `lib/backend/shell-integrations` directory is included via the `files` pattern:

```json
{
  "files": [
    "lib/**/*",
    "src-gen/**/*"
  ]
}
```

The `lib/**/*` glob already covers `lib/backend/shell-integrations/`. If you use a more restrictive `files` pattern, make sure `lib/backend/shell-integrations/**/*` is explicitly included, as `ShellIntegrationInjector` resolves these scripts relative to `__dirname` (i.e. `lib/backend/`).

### v1.74.0

#### Deprecation of @theia/ai-vercel-ai package

The `@theia/ai-vercel-ai` package has been marked as deprecated and is no longer published on npm. It will be removed from the Theia codebase after a deprecation period. The package only wrapped OpenAI and Anthropic models, both of which are already covered by the dedicated `@theia/ai-openai` and `@theia/ai-anthropic` providers with first-class support.

If your application depends on `@theia/ai-vercel-ai`, migrate as follows:

- **OpenAI models**: use `@theia/ai-openai`. Move `ai-features.vercelAi.openaiApiKey` to `ai-features.openAiOfficial.openAiApiKey` and define models in `ai-features.openAiOfficial.officialOpenAiModels`.
- **Anthropic models**: use `@theia/ai-anthropic`. Move `ai-features.vercelAi.anthropicApiKey` to `ai-features.anthropic.AnthropicApiKey` and define models in `ai-features.anthropic.AnthropicModels`.
- **Custom endpoints** (`ai-features.vercelAi.customModels`): split entries by their `provider` field into the matching provider-specific preference:
  - `provider: 'openai'` → `ai-features.openAiCustom.customOpenAiModels`
  - `provider: 'anthropic'` → `ai-features.anthropicCustom.customAnthropicModels`

The dedicated provider preferences offer the same fields plus additional ones (e.g. Azure `apiVersion`/`deployment`, `useResponseApi`, `reasoningSupport` for OpenAI; `useCaching`, `maxRetries` for Anthropic).

#### `AiConfigurationService` for reading/writing AI preferences

A new framework API, `AiConfigurationService` (`@theia/ai-core`), wraps `PreferenceService` for `ai-features.*` preferences and is the intended extension point for reading/writing AI configuration.

**Adopter-facing:**

- Prefer `AiConfigurationService` over `PreferenceService` for `ai-features.*` keys in frontend code. Its `get`/`inspect` are workspace-trust-aware (workspace/folder values are suppressed while the workspace is untrusted); writes (`set`/`update`) are never gated by trust.
- **Behavior change:** the AI terminal's shell-command allowlist/denylist (`ai-features.terminal.shellCommand{Allowlist,Denylist}`) are now read trust-aware via `AiConfigurationService`. Previously they were read with a raw `PreferenceService.get`, so an untrusted workspace could contribute allowlist entries. Now workspace/folder-scoped entries are suppressed until the workspace is trusted (an untrusted workspace can no longer widen the shell allowlist). User- and default-scoped entries are unaffected.

### v1.73.0

#### Custom agents reorganized into per-agent folders [#17523](https://github.com/eclipse-theia/theia/pull/17523)

Custom agents are no longer stored in a single `customAgents.yml` per scope. Each agent now lives in its own folder, `<scope>/agents/<id>/agent.md`, with YAML frontmatter (`name`, `description`, `defaultLLM`, `showInChat`) and the prompt body below it, matching the existing `SKILL.md` pattern (scopes are the workspace `.prompts/` directory and `~/.theia/prompt-templates`).

**End-user-facing:**

- When an existing `customAgents.yml` is found, Theia asks before migrating it to the new layout: a notification offers **Migrate** or **Don't Show Again**. Nothing is written until you choose **Migrate**, which avoids unexpected file changes (for example in a workspace under version control). Declining is safe: legacy `customAgents.yml` files keep being loaded so agents continue to work, and you are asked again next session until you either migrate or dismiss the prompt for good with **Don't Show Again** (remembered in local storage, not a setting). After a successful migration the `customAgents.yml` is renamed to `customAgents.yml.bak` (never deleted); restoring it is a matter of renaming the `.bak` back by hand. The migration can also be triggered at any time from the command palette via `AI: Re-run custom-agent migration`.
- Prompts stored as a YAML _folded_ block scalar (`prompt: >-`) keep their markdown heading structure: the folded scalar would otherwise merge each heading into the following paragraph (e.g. `## Task Your task is ...`), so migration and runtime loading preserve the original line breaks instead. If an earlier Theia version already migrated such an agent with merged headings, the generated `agent.md` is corrected automatically on the next migration, but only when you have not edited it since (the corrected content is rewritten from `customAgents.yml.bak`; user-modified files are left untouched).
- The default prompt-override file created by "Edit prompt" changed from `<agent-name>_prompt.prompttemplate` to `prompt.prompttemplate` inside the agent folder. Existing sibling `<agent-name>_prompt*.prompttemplate` files are moved into the agent folder during migration.

**Adopter-facing:**

- `PromptFragmentCustomizationService` gained the required methods `createCustomAgentFile`, `migrateCustomAgentsYaml` and `hasPendingCustomAgentMigration`. If you implement this interface directly, you must provide them. The `migrateCustomAgentsYaml()` report objects also carry a `corrected` count in addition to the migration counts.
- `PromptFragmentCustomizationService.getCustomAgentsLocations()` now returns `CustomAgentsLocation[]`. Each element gained a required `kind: 'agents-dir' | 'legacy-yaml'` field, and the result interleaves per-agent `agents/` directory entries with legacy `customAgents.yml` entries (one of each per scope). Code that previously iterated the result assuming only `customAgents.yml` files should branch on `kind` instead.

#### Custom agents default to the `.agents` workspace folder

Custom agents are now scanned from both the `.agents/` and `.prompts/` folders of each workspace root, independent of the `ai-features.promptTemplates.WorkspaceTemplateDirectories` preference. `.agents/` is preferred and is the default location for newly created agents (matching the skills convention introduced in [#17553](https://github.com/eclipse-theia/theia/pull/17553)); `.prompts/agents/` continues to be discovered for backward compatibility.

**End-user-facing:**

- New custom agents are created under `.agents/agents/<id>/agent.md` by default. Existing agents under `.prompts/agents/` keep working and are still listed as a creation location.

**Adopter-facing:**

- `PromptFragmentCustomizationProperties` gained an optional `agentDirectoryPaths` field carrying the absolute parent directories scanned for custom agents. The `.agents`/`.prompts` parents are exported as `CUSTOM_AGENT_WORKSPACE_DIRECTORIES`.

### v1.70.0

#### Removal of deprecated @theia/git extension from Theia codebase [#17148](https://github.com/eclipse-theia/theia/pull/17148)

The `@theia/git` extension has been completely removed from the Theia codebase.
This extension was deprecated since v1.58.0 and stopped being published in v1.61.0.

If your application still depends on `@theia/git`, you must migrate to the built-in VS Code Git extension, which provides the same feature set and is actively maintained. Remove any references to `@theia/git` from your application's dependencies and ensure the VS Code Git extension is included in your application, either through the builtin extension pack or by explicitly adding it to your plugins configuration.

### v1.65.0

#### Browser-only Filesystem Improvements [#16187](https://github.com/eclipse-theia/theia/pull/16187)

Browser-only filesystem refactored to use OPFS API with web workers.

Key changes:

- `OPFSFileSystemProvider` completely rewritten - extensions inheriting from old implementation need alignment
- `FileUploadService` moved from `@theia/filesystem/lib/browser/file-upload-service` to `@theia/filesystem/lib/common/upload/file-upload`, now bound with symbol key and separate `FileUploadServiceImpl`
- `FileDownloadService` moved from `file-download-data.ts` to `file-download.ts`, now bound with symbol key and separate `FileDownloadServiceImpl`
- `NodeFileUploadService` moved from `src/node/node-file-upload-service.ts` to `src/node/upload/node-file-upload-service.ts`
- `OPFSInitialization.getRootDirectory()` returns `Promise<string> | string` instead of `Promise<FileSystemDirectoryHandle>` - Just return the root of your filesystem as a string instead of the directory handle

#### Make Preferences available in the backend [#16017](https://github.com/eclipse-theia/theia/pull/16017)

The PR makes preferences support available in the backend. Only default and user preferences can be accessed in the backend. The API has changed in the following ways:
- Many files have been moved from the "browser" folder to the "common" folder. Imports will have to be adapted
- `PreferenceSchemaProvider` has been replaced by two separate `PreferenceSchemaServiceImpl` (and corresponding interface) and `DefaultsPreferenceProvider` classes.
- Preference schema typing has been simplified: a preference schema is no longer extending IJSONSchema and typing has been adapted to strictly
use Theia types (for example for scopes) and a straight-forward extension of standard IJSONSchema for properties. This means schemas from VS Code (contributed) must be converted to Theia format.
- PrefenceSchemaService separates between adding a schema and registering a default override for a property. Also, the service uses explicit override identifiers instead of encoding the override in the preference key. The service strictly distinguishes between preference schema and the derived JSON Schema for preference files. `JSONValue` is used instead of `any` where applicable. Schema properties must be added before overrides are registered.
`PreferenceSchemaService` now has the concept of`validScopes`. In the backend, only`Default` and `User` can be used. As a consequence, a preference provider for a particular preference scope might not be bound. Do not inject a preference provider with `@inject(PreferenceProvider) @named(<preference scope>)`, inject and use `PreferenceProviderProvider` instead.
- `PreferenceContribution` now has a `initSchema()` method in addition to the declarative Schema contribution. It is used to register overrides.  

### v1.62.0

#### Refactor menu nodes [#14676](https://github.com/eclipse-theia/theia/pull/14676)

This PR makes menu nodes and tab toolbar items into active object instead of pure data descriptors. This means they can polymorphically handle concerns like enablement, visibility, command execution and rendering. This keeps concerns like conversion of parameters out of the general tool bar and menu handling code. In this way, we could get rid of the MenuCommandExecutor and MenuCommandAdapter infrastructure.
If you are simply registering toolbar items and menus, little will change for you as a Theia adopter. Mainly, some of the paremeter types have changed in menu-model-registry.ts. Menu registration has been simplified in that an independent submenu is simply a menu that is registered under a path that does not start with the MAIN_MENU_BAR prefix.
If you override any of the toolbar or menu related implementations in your product, the biggest change will be that some functionality is now delegated to the menu and too bar item implementations. If this breaks your use case, please let us know.

### v1.38.0

#### Inversify 6.0

With Inversify 6, the library has introduced a strict split between sync and async dependency injection contexts.
Theia uses the sync dependency injection context, and therefore no async dependencies cannot be used as dependencies in Theia.

This might require a few changes in your Theia extensions, if you've been using async dependencies before. These include:

1. Injecting promises directly into services
2. Classes with `@postConstruct` methods which return a `Promise` instance.

In order to work around 1., you can just wrap the promise inside of a function:

```diff
const PromiseSymbol = Symbol();
const promise = startLongRunningOperation();

-bind(PromiseSymbol).toConstantValue(promise);
+bind(PromiseSymbol).toConstantValue(() => promise);
```

The newly bound function needs to be handled appropriately at the injection side.

For 2., `@postConstruct` methods can be refactored into a sync and an async method:

```diff
-@postConstruct()
-protected async init(): Promise<void> {
-  await longRunningOperation();
-}
+@postConstruct()
+protected init(): void {
+  this.doInit();
+}
+
+protected async doInit(): Promise<void> {
+  await longRunningOperation();
+}
```

Note that this release includes a few breaking changes that also perform this refactoring on our own classes.
If you've been overriding some of these `init()` methods, it might make sense to override `doInit()` instead.

### v1.37.0

#### Disabled node integration and added context isolation flag in Electron renderer

This also means that `electron-remote` can no longer be used in components in `electron-frontend` or `electron-common`. In order to use electron-related functionality from the browser, you need to expose an API via a preload script (see <https://www.electronjs.org/docs/latest/tutorial/context-isolation>). To achieve this from a Theia extension, you need to follow these steps:

1. Define the API interface and declare an API variable on the global `window` variable. See `packages/filesystem/electron-common/electron-api.ts` for an example
2. Write a preload script module that implements the API on the renderer ("browser") side and exposes the API via `exposeInMainWorld`. You'll need to expose the API in an exported function called `preload()`. See `packages/filesystem/electron-browser/preload.ts` for an example.
3. Declare a `theiaExtensions` entry pointing to the preload script like so:

```
"theiaExtensions": [
    {
      "preload": "lib/electron-browser/preload",
```

See `/packages/filesystem/package.json` for an example

1. Implement the API on the electron-main side by contributing a `ElectronMainApplicationContribution`. See `packages/filesystem/electron-main/electron-api-main.ts` for an example. If you don't have a module contributing to the electron-main application, you may have to declare it in your package.json.

```
"theiaExtensions": [
  {
    "preload": "lib/electron-browser/preload",
    "electronMain": "lib/electron-main/electron-main-module"
  }
```

If you are using NodeJS API in your electron browser-side code you will also have to move the code outside of the renderer process, for example
by setting up an API like described above, or, for example, by using a back-end service.

### v1.35.0

#### Drop support for `Node 14`

The framework no longer supports `Node 14` in order to better support plugins targeting the default supported VS Code API of `1.68.1`.
It is always possible to build using the `yarn --ignore-engines` workaround, but we advise against it.

### v1.32.0

#### Removal of `CircularDependencyPlugin`

We no longer enforce usage of the `CircularDependencyPlugin` in the generated webpack configuration. This plugin previously informed users of any non-fatal circular dependencies in their JavaScript imports.
Note that Theia adopters can enable the plugin again by manually adding `circular-dependency-plugin` as a dev dependency and adding the following snippet to their `webpack.config.js` file.

```js
config[0].module.plugins.push(new CircularDependencyPlugin({
    exclude: /(node_modules)[\\\\|\/]./,
    failOnError: false
}));
```

### v1.30.0

#### lerna 5.5.4

The `lerna` dev-dependency was upgraded one major versions, to v5.5.4. This removes a few high and severe known vulnerabilities from our development environment. See the [PR](https://github.com/eclipse-theia/theia/pull/11738) for more details.

The upgrade was smooth in this repo, but it's possible that Theia developers/extenders, that are potentially using `lerna` differently, might need to do some adaptations.

### v1.29.0

#### React 18 update

The `react` and `react-dom` dependencies were upgraded to version 18. Some relevant changes include:

- `ReactDOM.render` is now deprecated and is replaced by `createRoot` from `react-dom/client`
- the new API no longer supports render callbacks
- updates in promises, setTimeout, event handlers are automatically batched
- the dependency `react-virtualized` has been removed in favor of `react-virtuoso`

### 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](https://github.com/eclipse-theia/theia/pull/10736/files#diff-b4677f3ff57d8b952eeefc10493ed3600d2737f9b5c9b0630b172472acb9c3a2)
- 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](https://github.com/eclipse-theia/theia/pull/10947/files)
- 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](https://github.com/eclipse-theia/theia/pull/10736) 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`](https://github.com/eclipse-theia/theia/pull/10736/files#diff-99d13bb12b3c33ada58d66291db38b8b9f61883822b08b228f0ebf30b457a85d).
- 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](https://github.com/eclipse-theia/theia/pull/10736) 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](https://socket.io/docs/v4/using-multiple-nodes/#enabling-sticky-session).

### v1.22.0

#### Resolutions

Due to a [colors.js](https://github.com/Marak/colors.js) issue, a [resolution](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) may be necessary for your application in order to work around the problem:

For example:

```json
"resolutions": {
    "**/colors": "<=1.4.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](https://github.com/electron/electron/tree/15-x-y/docs).

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](../packages/core/README.md#re-exports).

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:

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

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

```json
      "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 `inversify@5.1.1`. 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](https://github.com/eclipse-theia/theia/releases/tag/v1.16.0)

- N/A.

### v1.15.0

[Release](https://github.com/eclipse-theia/theia/releases/tag/v1.15.0)

#### Keytar

- [`keytar`](https://github.com/atom/node-keytar) was added as a dependency for the secrets API. It 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):

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

- `keytar` uses [`prebuild-install`](https://github.com/prebuild/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`:

  ```sh
  # 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:

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