1 | <div align='center'>
|
2 |
|
3 | <br />
|
4 |
|
5 | <img src='https://raw.githubusercontent.com/eclipse-theia/theia/master/logo/theia.svg?sanitize=true' alt='theia-ext-logo' width='100px' />
|
6 |
|
7 | <h2>ECLIPSE THEIA - CORE EXTENSION</h2>
|
8 |
|
9 | <hr />
|
10 |
|
11 | </div>
|
12 |
|
13 | ## Description
|
14 |
|
15 | The `@theia/core` extension is the main extension for all Theia-based applications, and provides the main framework for all dependent extensions.
|
16 | The extension provides the base APIs for all Theia-based applications, including:
|
17 | - Application APIs
|
18 | - Shell APIs
|
19 | - Base Widgets
|
20 | - Contribution Points (ex: commands, menu items, keybindings)
|
21 |
|
22 | ## Theia Extension
|
23 |
|
24 | A Theia extension is a node package declaring `theiaExtensions` property in `package.json`:
|
25 |
|
26 | ```json
|
27 | {
|
28 | "theiaExtensions": [{
|
29 | "frontend": "lib/myExtension/browser/myextension-frontend-module",
|
30 | "backend": "lib/myExtension/node/myextension-backend-module",
|
31 | }, {
|
32 | "frontend": "lib/myExtension2/browser/myextension2-browser-module",
|
33 | "frontendElectron": "lib/myExtension2/electron-browser/myextension2-electron-browser-module",
|
34 | "backend": "lib/myExtension2/node/myextension2-node-module",
|
35 | "backendElectron": "lib/myExtension2/electron-main/myextension2-electron-main-module"
|
36 | }]
|
37 | }
|
38 | ```
|
39 |
|
40 | Each extension can consist of the following modules:
|
41 | - `frontend` is used in the browser env and as well in the electron if `frontendElectron` is not provided
|
42 | - `frontendElectron` is used in the electron env
|
43 | - `backend` is used in the node env and as well in the electron env if `backendElectron` is not provided
|
44 | - `backendElectron` is used in the electron env
|
45 |
|
46 | An extension module should have a default export of `ContainerModule | Promise<ContainerModule>` type.
|
47 |
|
48 | ## Theia Application
|
49 |
|
50 | A Theia application is a node package listing [Theia extensions](#theia-extension) as dependencies and managed with [Theia CLI](../../dev-packages/cli/README.md).
|
51 |
|
52 | ## Re-Exports Mechanism
|
53 |
|
54 | In order to make application builds more stable `@theia/core` re-exports some common dependencies for Theia extensions to re-use. This is especially useful when having to re-use the same dependencies as `@theia/core` does: Since those dependencies will be pulled by Theia, instead of trying to match the same version in your own packages, you can use re-exports to consume it from the framework directly.
|
55 |
|
56 | ### Usage Example
|
57 |
|
58 | Let's take inversify as an example since you will most likely use this package, you can import it by prefixing with `@theia/core/shared/`:
|
59 |
|
60 | ```ts
|
61 | import { injectable } from '@theia/core/shared/inversify';
|
62 |
|
63 | @injectable()
|
64 | export class SomeClass {
|
65 | // ...
|
66 | }
|
67 | ```
|
68 |
|
69 | ## Re-Exports
|
70 |
|
71 | - `@theia/core/electron-shared/...`
|
72 | - `native-keymap` (from [`native-keymap@^2.2.1`](https://www.npmjs.com/package/native-keymap))
|
73 | - `electron` (from [`electron@^23.2.4`](https://www.npmjs.com/package/electron))
|
74 | - `electron-store` (from [`electron-store@^8.0.0`](https://www.npmjs.com/package/electron-store))
|
75 | - `fix-path` (from [`fix-path@^3.0.0`](https://www.npmjs.com/package/fix-path))
|
76 | - `@theia/core/shared/...`
|
77 | - `@phosphor/algorithm` (from [`@phosphor/algorithm@1`](https://www.npmjs.com/package/@phosphor/algorithm))
|
78 | - `@phosphor/commands` (from [`@phosphor/commands@1`](https://www.npmjs.com/package/@phosphor/commands))
|
79 | - `@phosphor/coreutils` (from [`@phosphor/coreutils@1`](https://www.npmjs.com/package/@phosphor/coreutils))
|
80 | - `@phosphor/domutils` (from [`@phosphor/domutils@1`](https://www.npmjs.com/package/@phosphor/domutils))
|
81 | - `@phosphor/dragdrop` (from [`@phosphor/dragdrop@1`](https://www.npmjs.com/package/@phosphor/dragdrop))
|
82 | - `@phosphor/messaging` (from [`@phosphor/messaging@1`](https://www.npmjs.com/package/@phosphor/messaging))
|
83 | - `@phosphor/properties` (from [`@phosphor/properties@1`](https://www.npmjs.com/package/@phosphor/properties))
|
84 | - `@phosphor/signaling` (from [`@phosphor/signaling@1`](https://www.npmjs.com/package/@phosphor/signaling))
|
85 | - `@phosphor/virtualdom` (from [`@phosphor/virtualdom@1`](https://www.npmjs.com/package/@phosphor/virtualdom))
|
86 | - `@phosphor/widgets` (from [`@phosphor/widgets@1`](https://www.npmjs.com/package/@phosphor/widgets))
|
87 | - `@theia/application-package` (from [`@theia/application-package@1.37.2`](https://www.npmjs.com/package/@theia/application-package/v/1.37.2))
|
88 | - `@theia/application-package/lib/api` (from [`@theia/application-package@1.37.2`](https://www.npmjs.com/package/@theia/application-package/v/1.37.2))
|
89 | - `@theia/application-package/lib/environment` (from [`@theia/application-package@1.37.2`](https://www.npmjs.com/package/@theia/application-package/v/1.37.2))
|
90 | - `@theia/request` (from [`@theia/request@1.37.2`](https://www.npmjs.com/package/@theia/request/v/1.37.2))
|
91 | - `@theia/request/lib/proxy` (from [`@theia/request@1.37.2`](https://www.npmjs.com/package/@theia/request/v/1.37.2))
|
92 | - `@theia/request/lib/node-request-service` (from [`@theia/request@1.37.2`](https://www.npmjs.com/package/@theia/request/v/1.37.2))
|
93 | - `fs-extra` (from [`fs-extra@^4.0.2`](https://www.npmjs.com/package/fs-extra))
|
94 | - `fuzzy` (from [`fuzzy@^0.1.3`](https://www.npmjs.com/package/fuzzy))
|
95 | - `inversify` (from [`inversify@^5.1.1`](https://www.npmjs.com/package/inversify))
|
96 | - `react-dom` (from [`react-dom@^18.2.0`](https://www.npmjs.com/package/react-dom))
|
97 | - `react-dom/client` (from [`react-dom@^18.2.0`](https://www.npmjs.com/package/react-dom))
|
98 | - `react-virtuoso` (from [`react-virtuoso@^2.17.0`](https://www.npmjs.com/package/react-virtuoso))
|
99 | - `vscode-languageserver-protocol` (from [`vscode-languageserver-protocol@^3.17.2`](https://www.npmjs.com/package/vscode-languageserver-protocol))
|
100 | - `vscode-uri` (from [`vscode-uri@^2.1.1`](https://www.npmjs.com/package/vscode-uri))
|
101 | - `dompurify` (from [`dompurify@^2.2.9`](https://www.npmjs.com/package/dompurify))
|
102 | - `express` (from [`express@^4.16.3`](https://www.npmjs.com/package/express))
|
103 | - `lodash.debounce` (from [`lodash.debounce@^4.0.8`](https://www.npmjs.com/package/lodash.debounce))
|
104 | - `lodash.throttle` (from [`lodash.throttle@^4.1.1`](https://www.npmjs.com/package/lodash.throttle))
|
105 | - `nsfw` (from [`nsfw@^2.2.4`](https://www.npmjs.com/package/nsfw))
|
106 | - `markdown-it` (from [`markdown-it@^12.3.2`](https://www.npmjs.com/package/markdown-it))
|
107 | - `react` (from [`react@^18.2.0`](https://www.npmjs.com/package/react))
|
108 | - `ws` (from [`ws@^7.1.2`](https://www.npmjs.com/package/ws))
|
109 | - `yargs` (from [`yargs@^15.3.1`](https://www.npmjs.com/package/yargs))
|
110 |
|
111 | ## Logging Configuration
|
112 |
|
113 | It's possible to change the log level for the entire Theia application by
|
114 | passing it the `--log-level={fatal,error,warn,info,debug,trace}` option. For
|
115 | more fine-grained adjustment, it's also possible to set the log level per
|
116 | logger (i.e. per topic). The `root` logger is a special catch-all logger
|
117 | through which go all messages not sent through a particular logger. To change
|
118 | the log level of particular loggers, create a config file such as
|
119 |
|
120 | ```json
|
121 | {
|
122 | "defaultLevel": "info",
|
123 | "levels": {
|
124 | "terminal": "debug",
|
125 | "task": "error"
|
126 | }
|
127 | }
|
128 | ```
|
129 |
|
130 | where `levels` contains the logger-to-log-level mapping. `defaultLevel`
|
131 | contains the log level to use for loggers not specified in `levels`. This file
|
132 | can then be specified using the `--log-config` option. Theia will watch that
|
133 | file for changes, so it's possible to change log levels at runtime by
|
134 | modifying this file.
|
135 |
|
136 | It's unfortunately currently not possible to query Theia for the list of
|
137 | existing loggers. However, each log message specifies from which logger it
|
138 | comes from, which can give an idea, without having to read the code:
|
139 |
|
140 | ```
|
141 | root INFO [nsfw-watcher: 10734] Started watching: /Users/captain.future/git/theia/CONTRIBUTING.md
|
142 | ^^^^ ^^^^ ^^^^^^^^^^^^^^^^^^^
|
143 | ```
|
144 | Where `root` is the name of the logger and `INFO` is the log level. These are optionally followed by the name of a child process and the process ID.
|
145 |
|
146 | ## Environment Variables
|
147 |
|
148 | - `THEIA_HOSTS`
|
149 | - A comma-separated list of hosts expected to resolve to the current application.
|
150 | - e.g: `theia.app.com,some.other.domain:3000`
|
151 | - The port number is important if your application is not hosted on either `80` or `443`.
|
152 | - If possible, you should set this environment variable:
|
153 | - When not set, Theia will allow any origin to access the WebSocket services.
|
154 | - When set, Theia will only allow the origins defined in this environment variable.
|
155 |
|
156 | ## Additional Information
|
157 |
|
158 | - [API documentation for `@theia/core`](https://eclipse-theia.github.io/theia/docs/next/modules/core.html)
|
159 | - [Theia - GitHub](https://github.com/eclipse-theia/theia)
|
160 | - [Theia - Website](https://theia-ide.org/)
|
161 |
|
162 | ## License
|
163 |
|
164 | - [Eclipse Public License 2.0](http://www.eclipse.org/legal/epl-2.0/)
|
165 | - [一 (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception](https://projects.eclipse.org/license/secondary-gpl-2.0-cp)
|
166 |
|
167 | ## Trademark
|
168 | "Theia" is a trademark of the Eclipse Foundation
|
169 | https://www.eclipse.org/theia
|