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