0
# Application Framework
1

2
Theia's application framework provides frontend and backend application infrastructure with lifecycle management, contribution points, and cross-platform support for building extensible IDE applications.
3

4
## Capabilities
5

6
### Frontend Application
7

8
Main frontend application class managing client-side application lifecycle and shell integration.
9

10
```typescript { .api }
11
/**
12
 * Main frontend application managing browser/electron client
13
 */
14
class FrontendApplication {
15
    /** Application shell containing widget layout */
16
    readonly shell: ApplicationShell;
17
    
18
    /**
19
     * Start the frontend application
20
     * @returns Promise that resolves when application starts
21
     */
22
    start(): Promise<void>;
23
    
24
    /**
25
     * Stop the frontend application
26
     */
27
    stop(): void;
28
    
29
    /**
30
     * Configure the application before starting
31
     */
32
    configure(): void;
33
}
34

35
/**
36
 * Service token for FrontendApplication
37
 */
38
const FrontendApplication: symbol;
39
```
40

41
### Frontend Application Contribution
42

43
Extension point for participating in frontend application lifecycle.
44

45
```typescript { .api }
46
/**
47
 * Extension point for frontend application lifecycle
48
 */
49
interface FrontendApplicationContribution {
50
    /**
51
     * Initialize the contribution before application configuration
52
     */
53
    initialize?(): void;
54
    
55
    /**
56
     * Configure the application during startup
57
     * @param app - Frontend application instance
58
     */
59
    configure?(app: FrontendApplication): void;
60
    
61
    /**
62
     * Called when application starts
63
     * @param app - Frontend application instance
64
     */
65
    onStart?(app: FrontendApplication): void;
66
    
67
    /**
68
     * Called when application stops
69
     * @param app - Frontend application instance  
70
     */
71
    onStop?(app: FrontendApplication): void;
72
    
73
    /**
74
     * Called when application state changes
75
     * @param state - New application state
76
     */
77
    onStateChanged?(state: FrontendApplicationState): void;
78
}
79

80
/**
81
 * Frontend application state
82
 */
83
interface FrontendApplicationState {
84
    readonly state: 'init' | 'starting' | 'started' | 'stopping' | 'stopped';
85
}
86

87
/**
88
 * Service token for FrontendApplicationContribution
89
 */
90
const FrontendApplicationContribution: symbol;
91
```
92

93
**Usage Example:**
94

95
```typescript
96
import { injectable } from "@theia/core";
97
import { FrontendApplication, FrontendApplicationContribution } from "@theia/core/lib/browser";
98

99
@injectable()
100
export class MyFrontendContribution implements FrontendApplicationContribution {
101
    
102
    initialize(): void {
103
        console.log('Initializing my extension');
104
    }
105
    
106
    configure(app: FrontendApplication): void {
107
        console.log('Configuring frontend application');
108
    }
109
    
110
    onStart(app: FrontendApplication): void {
111
        console.log('Frontend application started');
112
        // Add initial widgets, register handlers, etc.
113
    }
114
    
115
    onStop(app: FrontendApplication): void {
116
        console.log('Frontend application stopping');
117
        // Cleanup resources
118
    }
119
    
120
    onStateChanged(state: FrontendApplicationState): void {
121
        console.log(`Application state: ${state.state}`);
122
    }
123
}
124
```
125

126
### Backend Application
127

128
Main backend application class managing server-side application lifecycle and HTTP server.
129

130
```typescript { .api }
131
/**
132
 * Main backend application managing Node.js server
133
 */
134
class BackendApplication {
135
    /**
136
     * Use Express middleware
137
     * @param handlers - Express middleware handlers
138
     */
139
    use(...handlers: express.Handler[]): void;
140
    
141
    /**
142
     * Start the backend server
143
     * @param port - Optional port number
144
     * @returns Promise that resolves when server starts
145
     */
146
    start(port?: number): Promise<void>;
147
    
148
    /**
149
     * Stop the backend server
150
     */
151
    stop(): void;
152
    
153
    /**
154
     * Configure the server
155
     */
156
    configure(): void;
157
}
158

159
/**
160
 * Service token for BackendApplication
161
 */
162
const BackendApplication: symbol;
163
```
164

165
### Backend Application Server
166

167
Server interface for backend applications with configuration options.
168

169
```typescript { .api }
170
/**
171
 * Backend application server configuration
172
 */
173
interface BackendApplicationServer {
174
    /**
175
     * Start server with configuration
176
     * @param config - Server configuration
177
     * @returns Promise that resolves when server starts
178
     */
179
    start(config?: BackendApplicationConfiguration): Promise<void>;
180
    
181
    /**
182
     * Stop the server
183
     */
184
    stop(): void;
185
}
186

187
/**
188
 * Backend server configuration options
189
 */
190
interface BackendApplicationConfiguration {
191
    /** Server port */
192
    port?: number;
193
    
194
    /** Server hostname */
195
    hostname?: string;
196
    
197
    /** SSL certificate */
198
    ssl?: {
199
        key: string;
200
        cert: string;
201
    };
202
    
203
    /** Request timeout in milliseconds */
204
    requestTimeout?: number;
205
    
206
    /** Maximum request size */
207
    maxRequestSize?: string;
208
}
209

210
/**
211
 * Service token for BackendApplicationServer
212
 */
213
const BackendApplicationServer: symbol;
214
```
215

216
**Usage Example:**
217

218
```typescript
219
import { BackendApplication } from "@theia/core/lib/node";
220
import express from "express";
221

222
// Create backend application
223
const app = new BackendApplication();
224

225
// Add middleware
226
app.use(express.json());
227
app.use(express.static('public'));
228

229
// Add custom routes
230
app.use('/api', (req, res) => {
231
    res.json({ message: 'Hello from Theia backend!' });
232
});
233

234
// Start server
235
app.start(3000).then(() => {
236
    console.log('Backend server started on port 3000');
237
});
238
```
239

240
### CLI System
241

242
Command-line interface support for backend applications.
243

244
```typescript { .api }
245
/**
246
 * CLI contribution interface for adding command-line options
247
 */
248
interface CliContribution {
249
    /**
250
     * Configure CLI options
251
     * @param yargs - Yargs instance for configuration
252
     */
253
    configure(yargs: any): void;
254
    
255
    /**
256
     * Set default values for CLI arguments
257
     * @param argv - Parsed CLI arguments
258
     * @returns Modified arguments
259
     */
260
    setArguments?(argv: any): any;
261
}
262

263
/**
264
 * CLI manager for handling command-line arguments
265
 */
266
interface CliManager {
267
    /**
268
     * Parse command-line arguments
269
     * @param args - Raw command-line arguments
270
     * @returns Parsed arguments
271
     */
272
    parseArgs(args: string[]): Promise<any>;
273
    
274
    /**
275
     * Get parsed CLI arguments
276
     * @returns Current CLI arguments
277
     */
278
    getArgs(): any;
279
}
280

281
/**
282
 * Service tokens
283
 */
284
const CliContribution: symbol;
285
const CliManager: symbol;
286
```
287

288
**Usage Example:**
289

290
```typescript
291
import { injectable } from "@theia/core";
292
import { CliContribution } from "@theia/core/lib/node";
293

294
@injectable()
295
export class MyCliContribution implements CliContribution {
296
    
297
    configure(yargs: any): void {
298
        yargs.option('my-option', {
299
            description: 'My custom CLI option',
300
            type: 'string',
301
            default: 'default-value'
302
        });
303
        
304
        yargs.option('verbose', {
305
            alias: 'v',
306
            description: 'Enable verbose logging',
307
            type: 'boolean'
308
        });
309
    }
310
    
311
    setArguments(argv: any): any {
312
        // Process and validate arguments
313
        if (argv.verbose) {
314
            process.env.LOG_LEVEL = 'debug';
315
        }
316
        
317
        return argv;
318
    }
319
}
320
```
321

322
### Extension Modules
323

324
Theia extension module system for organizing and loading functionality.
325

326
```typescript { .api }
327
/**
328
 * Extension module configuration in package.json
329
 */
330
interface TheiaExtension {
331
    /** Frontend module path */
332
    frontend?: string;
333
    
334
    /** Frontend-only module path (browser only) */
335
    frontendOnly?: string;
336
    
337
    /** Electron frontend module path */
338
    frontendElectron?: string;
339
    
340
    /** Backend module path */
341
    backend?: string;
342
    
343
    /** Backend-only module path (Node.js only) */
344
    backendOnly?: string;
345
    
346
    /** Electron backend module path */
347
    backendElectron?: string;
348
    
349
    /** Preload module path */
350
    preload?: string;
351
    
352
    /** Frontend preload module path */
353
    frontendPreload?: string;
354
    
355
    /** Frontend-only preload module path */
356
    frontendOnlyPreload?: string;
357
}
358

359
/**
360
 * Extension package.json configuration
361
 */
362
interface ExtensionPackage {
363
    /** Extension modules */
364
    theiaExtensions: TheiaExtension[];
365
    
366
    /** Re-exported dependencies */
367
    theiaReExports?: {
368
        [env: string]: {
369
            [type: string]: string[];
370
        };
371
    };
372
}
373
```
374

375
### Application State Management
376

377
Application state tracking and lifecycle management.
378

379
```typescript { .api }
380
/**
381
 * Application state enumeration
382
 */
383
enum ApplicationState {
384
    init = 'init',
385
    starting = 'starting', 
386
    started = 'started',
387
    stopping = 'stopping',
388
    stopped = 'stopped'
389
}
390

391
/**
392
 * Application state change event
393
 */
394
interface ApplicationStateChangeEvent {
395
    /** Previous state */
396
    readonly previousState: ApplicationState;
397
    
398
    /** New current state */
399
    readonly newState: ApplicationState;
400
}
401

402
/**
403
 * Application state service
404
 */
405
interface ApplicationStateService {
406
    /** Current application state */
407
    readonly state: ApplicationState;
408
    
409
    /** Event fired when state changes */
410
    readonly onStateChanged: Event<ApplicationStateChangeEvent>;
411
    
412
    /** True if application has reached started state */
413
    readonly reachedState: {
414
        started: Promise<void>;
415
        stopped: Promise<void>;
416
    };
417
}
418
```
419

420
## Environment-Specific Features
421

422
### Browser Environment
423

424
Browser-specific application features and utilities.
425

426
```typescript { .api }
427
namespace environment {
428
    /** True if running in browser */
429
    const isBrowser: boolean;
430
    
431
    /** True if running in Electron */
432
    const isElectron: boolean;
433
    
434
    /** Browser user agent detection */
435
    function isChrome(): boolean;
436
    function isFirefox(): boolean;
437
    function isSafari(): boolean;
438
    
439
    /** Feature detection */
440
    function isBasicWasmSupported(): boolean;
441
}
442
```
443

444
### Electron Environment
445

446
Electron-specific application features and integration.
447

448
```typescript { .api }
449
/**
450
 * Electron-specific application extensions
451
 */
452
interface ElectronApplication extends FrontendApplication {
453
    /** True if running in Electron */
454
    readonly isElectron: boolean;
455
    
456
    /** Access to Electron APIs */
457
    readonly electron: any;
458
}
459
```
460

461
## Types
462

463
```typescript { .api }
464
/**
465
 * Express-related types
466
 */
467
namespace express {
468
    interface Request {
469
        // Express request object
470
        params: any;
471
        query: any;
472
        body: any;
473
        headers: any;
474
    }
475
    
476
    interface Response {
477
        // Express response object
478
        json(obj: any): Response;
479
        send(body: any): Response;
480
        status(code: number): Response;
481
    }
482
    
483
    interface NextFunction {
484
        // Express next function
485
        (err?: any): void;
486
    }
487
    
488
    interface Handler {
489
        // Express middleware handler
490
        (req: Request, res: Response, next: NextFunction): void;
491
    }
492
}
493

494
/**
495
 * Express handler type for middleware
496
 */
497
type ExpressHandler = express.Handler;
498

499
/**
500
 * Application configuration
501
 */
502
interface ApplicationConfiguration {
503
    /** Application name */
504
    applicationName: string;
505
    
506
    /** Default theme */
507
    defaultTheme?: string;
508
    
509
    /** Default icon theme */
510
    defaultIconTheme?: string;
511
    
512
    /** Additional preferences */
513
    preferences?: { [key: string]: any };
514
}
515

516
/**
517
 * Application info interface
518
 */
519
interface ApplicationInfo {
520
    /** Application name */
521
    readonly name: string;
522
    
523
    /** Application version */
524
    readonly version: string;
525
    
526
    /** Build timestamp */
527
    readonly buildTimestamp: string;
528
}
529
```