0
# Theia Core
1
2
Theia Core is the foundational framework for building cloud and desktop IDE applications using modern web technologies. It provides comprehensive APIs for application structure, dependency injection, widget systems, command handling, and cross-platform development with TypeScript.
3
4
## Package Information
5
6
- **Package Name**: @theia/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @theia/core`
10
11
## Core Imports
12
13
```typescript
14
// Main entry point (cross-platform APIs)
15
import { inject, injectable, Command, CommandRegistry, interfaces } from "@theia/core";
16
17
// Browser-specific APIs
18
import { FrontendApplication, Widget, ReactWidget } from "@theia/core/lib/browser";
19
20
// Node-specific APIs
21
import { BackendApplication, CliContribution } from "@theia/core/lib/node";
22
23
// React for widget development
24
import * as React from "react";
25
```
26
27
For CommonJS:
28
29
```javascript
30
const { inject, injectable } = require("@theia/core");
31
const { FrontendApplication } = require("@theia/core/lib/browser");
32
```
33
34
## Basic Usage
35
36
```typescript
37
import { injectable, inject } from "@theia/core";
38
import { CommandContribution, CommandRegistry, Command } from "@theia/core";
39
import { FrontendApplication, ReactWidget } from "@theia/core/lib/browser";
40
import * as React from "react";
41
42
// Define a command
43
const MY_COMMAND: Command = {
44
id: 'my-extension.hello',
45
label: 'Say Hello'
46
};
47
48
// Create a command contribution
49
@injectable()
50
export class HelloWorldContribution implements CommandContribution {
51
52
registerCommands(registry: CommandRegistry): void {
53
registry.registerCommand(MY_COMMAND, {
54
execute: () => {
55
console.log('Hello from Theia!');
56
}
57
});
58
}
59
}
60
61
// Create a widget
62
@injectable()
63
export class HelloWidget extends ReactWidget {
64
65
constructor() {
66
super();
67
this.id = 'hello-widget';
68
this.title.label = 'Hello';
69
}
70
71
protected render(): React.ReactNode {
72
return <div>Hello World Widget</div>;
73
}
74
}
75
```
76
77
## Architecture
78
79
Theia Core is built around several key architectural patterns:
80
81
- **Dependency Injection**: Uses InversifyJS for comprehensive dependency injection with Symbol-based tokens
82
- **Contribution Pattern**: Extensible architecture where extensions contribute commands, menus, widgets, etc.
83
- **Event-Driven System**: Comprehensive event system with typed emitters and disposable subscriptions
84
- **Multi-Platform Support**: Separate entry points for browser, Node.js, and Electron environments
85
- **Widget-Based UI**: Built on Phosphor/Lumino widgets with React integration for modern components
86
- **Resource Management**: Unified abstraction for files, URIs, and virtual resources
87
88
## Capabilities
89
90
### Dependency Injection System
91
92
Core dependency injection infrastructure using InversifyJS with Symbol-based service tokens and contribution patterns.
93
94
```typescript { .api }
95
function inject(serviceIdentifier: interfaces.ServiceIdentifier): ParameterDecorator;
96
function injectable<T>(target: interfaces.Newable<T>): interfaces.Newable<T>;
97
98
interface ContributionProvider<T> {
99
getContributions(): T[];
100
}
101
```
102
103
[Dependency Injection](./dependency-injection.md)
104
105
### Command System
106
107
Centralized command registry with handler prioritization, context awareness, and event-driven lifecycle.
108
109
```typescript { .api }
110
interface Command {
111
id: string;
112
label?: string;
113
iconClass?: string;
114
category?: string;
115
}
116
117
interface CommandHandler {
118
execute(...args: any[]): any;
119
isEnabled?(...args: any[]): boolean;
120
isVisible?(...args: any[]): boolean;
121
}
122
123
interface CommandRegistry {
124
registerCommand(command: Command, handler?: CommandHandler): Disposable;
125
executeCommand<T>(id: string, ...args: any[]): Promise<T | undefined>;
126
}
127
```
128
129
[Commands](./commands.md)
130
131
### Event System
132
133
Type-safe event system with emitters, async event handling, cancellation support, and disposable subscriptions.
134
135
```typescript { .api }
136
interface Event<T> {
137
(listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable;
138
}
139
140
class Emitter<T> {
141
readonly event: Event<T>;
142
fire(event: T): void;
143
dispose(): void;
144
}
145
146
interface CancellationToken {
147
readonly isCancellationRequested: boolean;
148
readonly onCancellationRequested: Event<any>;
149
}
150
```
151
152
[Events and Messaging](./events-messaging.md)
153
154
### Widget System
155
156
Comprehensive widget system built on Phosphor/Lumino with React integration, layout management, and extensible widget types.
157
158
```typescript { .api }
159
class Widget {
160
readonly id: string;
161
readonly title: Title<Widget>;
162
readonly parent: Widget | null;
163
show(): void;
164
hide(): void;
165
close(): void;
166
}
167
168
class ReactWidget extends Widget {
169
protected render(): React.ReactNode;
170
protected onAfterAttach(): void;
171
protected onBeforeDetach(): void;
172
}
173
```
174
175
[Widgets and UI](./widgets-ui.md)
176
177
### Application Framework
178
179
Frontend and backend application frameworks with lifecycle management, contribution points, and cross-platform support.
180
181
```typescript { .api }
182
class FrontendApplication {
183
readonly shell: ApplicationShell;
184
start(): Promise<void>;
185
stop(): void;
186
}
187
188
class BackendApplication {
189
use(...handlers: express.Handler[]): void;
190
start(port?: number): Promise<void>;
191
stop(): void;
192
}
193
194
interface FrontendApplicationContribution {
195
initialize?(): void;
196
configure?(app: FrontendApplication): void;
197
onStart?(app: FrontendApplication): void;
198
onStop?(app: FrontendApplication): void;
199
}
200
```
201
202
[Application Framework](./application-framework.md)
203
204
### Resource Management
205
206
Unified resource abstraction for files, URIs, and virtual resources with versioning, encoding support, and multiple resolvers.
207
208
```typescript { .api }
209
interface Resource {
210
readonly uri: URI;
211
readonly version?: ResourceVersion;
212
readContents(options?: ResourceReadOptions): Promise<string>;
213
saveContents?(content: string, options?: ResourceSaveOptions): Promise<void>;
214
}
215
216
interface ResourceProvider {
217
get(uri: URI): Promise<Resource>;
218
}
219
220
class URI {
221
readonly scheme: string;
222
readonly path: string;
223
static file(path: string): URI;
224
static parse(value: string): URI;
225
toString(): string;
226
}
227
```
228
229
[Resources and Files](./resources-files.md)
230
231
### Preferences System
232
233
Type-safe preference management with schema definition, providers, and runtime configuration changes.
234
235
```typescript { .api }
236
interface PreferenceService {
237
get<T>(preferenceName: string, defaultValue?: T): T | undefined;
238
set(preferenceName: string, value: any): Promise<void>;
239
onPreferenceChanged: Event<PreferenceChangeEvent<any>>;
240
}
241
242
interface PreferenceSchema {
243
[name: string]: PreferenceSchemaProperty;
244
}
245
```
246
247
[Preferences and Configuration](./preferences-configuration.md)
248
249
### Keybinding System
250
251
Comprehensive keybinding system with context awareness, command integration, and platform-specific key handling.
252
253
```typescript { .api }
254
interface Keybinding {
255
keybinding: string;
256
command: string;
257
context?: string;
258
args?: any[];
259
}
260
261
interface KeybindingRegistry {
262
registerKeybinding(binding: Keybinding): Disposable;
263
getKeybindingsForCommand(commandId: string): Keybinding[];
264
}
265
```
266
267
[Keybindings](./keybindings.md)
268
269
### Menu System
270
271
Hierarchical menu system with dynamic contributions, context menus, and integration with commands.
272
273
```typescript { .api }
274
interface MenuNode {
275
readonly id: string;
276
readonly label?: string;
277
readonly icon?: string;
278
readonly sortString?: string;
279
}
280
281
interface MenuModelRegistry {
282
registerMenuAction(menuPath: MenuPath, item: MenuAction): Disposable;
283
registerSubmenu(menuPath: MenuPath, label: string): MenuPath;
284
}
285
```
286
287
[Menus](./menus.md)
288
289
## Types
290
291
### Core Types
292
293
```typescript { .api }
294
type Disposable = {
295
dispose(): void;
296
};
297
298
interface DisposableCollection extends Disposable {
299
push(disposable: Disposable): Disposable;
300
pushAll(disposables: Disposable[]): Disposable[];
301
}
302
303
type MaybePromise<T> = T | Promise<T>;
304
type MaybeArray<T> = T | T[];
305
306
interface URI {
307
readonly scheme: string;
308
readonly authority: string;
309
readonly path: string;
310
readonly query: string;
311
readonly fragment: string;
312
}
313
314
interface ApplicationError<C = number, D = any> extends Error {
315
readonly code: C;
316
readonly data: D;
317
}
318
```
319
320
### Event Types
321
322
```typescript { .api }
323
interface EmitterOptions {
324
onFirstListenerAdd?: Function;
325
onLastListenerRemove?: Function;
326
leakWarningThreshold?: number;
327
}
328
329
interface WaitUntilEvent {
330
waitUntil(thenable: Promise<any>): void;
331
}
332
333
type EventListener<T> = (e: T) => any;
334
```
335
336
### InversifyJS Types
337
338
```typescript { .api }
339
// InversifyJS interfaces namespace
340
namespace interfaces {
341
interface ServiceIdentifier<T = any> {
342
// Service identifier for dependency injection
343
}
344
345
interface Bind {
346
// Container binding interface
347
}
348
349
interface Container {
350
// InversifyJS container interface
351
get<T>(serviceIdentifier: ServiceIdentifier<T>): T;
352
}
353
354
interface Newable<T> {
355
new (...args: any[]): T;
356
}
357
}
358
```
359
360
### Service Tokens
361
362
```typescript { .api }
363
// Core service symbols for dependency injection
364
const CommandService: symbol;
365
const CommandRegistry: symbol;
366
const LoggerFactory: symbol;
367
const ILogger: symbol;
368
const PreferenceService: symbol;
369
const ResourceProvider: symbol;
370
const KeybindingRegistry: symbol;
371
const MenuModelRegistry: symbol;
372
```