0
# Lumino Application
1

2
Lumino Application provides a pluggable application framework for building extensible desktop-like web applications. It serves as the foundation for creating complex UI applications with plugin architecture support, enabling safe extension by third-party code via a comprehensive plugin system.
3

4
## Package Information
5

6
- **Package Name**: @lumino/application
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @lumino/application`
10

11
## Core Imports
12

13
```typescript
14
import { Application, type IPlugin } from "@lumino/application";
15
import { type Token } from "@lumino/coreutils";
16
import { Widget } from "@lumino/widgets";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { Application } = require("@lumino/application");
23
const { Widget } = require("@lumino/widgets");
24
```
25

26
## Basic Usage
27

28
```typescript
29
import { Application } from "@lumino/application";
30
import { Widget } from "@lumino/widgets";
31

32
// Create a shell widget for the application
33
const shell = new Widget();
34

35
// Create the application
36
const app = new Application({ shell });
37

38
// Register a simple plugin
39
app.registerPlugin({
40
  id: 'my-plugin',
41
  description: 'A simple plugin',
42
  activate: () => {
43
    console.log('Plugin activated!');
44
  }
45
});
46

47
// Start the application
48
await app.start({
49
  hostID: 'app-container'
50
});
51
```
52

53
## Architecture
54

55
Lumino Application is built around several key components:
56

57
- **Application Class**: The main application orchestrator that manages plugins, commands, and the shell
58
- **Plugin System**: Based on @lumino/coreutils PluginRegistry for registration, activation, and dependency management
59
- **Command Registry**: Integrated command system from @lumino/commands for keyboard shortcuts and actions
60
- **Context Menu**: Application-wide context menu system from @lumino/widgets
61
- **Shell Widget**: The root container widget that hosts the entire application UI
62
- **Service Resolution**: Dependency injection system for plugin services
63

64
## Capabilities
65

66
### Application Core
67

68
The main Application class that orchestrates the entire pluggable application framework. Provides plugin management, service resolution, and application lifecycle control.
69

70
```typescript { .api }
71
class Application<T extends Widget = Widget> {
72
  constructor(options: Application.IOptions<T>);
73
  readonly commands: CommandRegistry;
74
  readonly contextMenu: ContextMenu;
75
  readonly shell: T;
76
  readonly deferredPlugins: string[];
77
  readonly started: Promise<void>;
78
}
79

80
interface Application.IOptions<T extends Widget> extends PluginRegistry.IOptions {
81
  shell: T;
82
  contextMenuRenderer?: Menu.IRenderer;
83
  pluginRegistry?: PluginRegistry;
84
}
85

86
interface PluginRegistry.IOptions {
87
  /** Validate that a plugin is allowed to be registered. Default is () => true. */
88
  validatePlugin?: (plugin: IPlugin<any, any>) => boolean;
89
}
90
```
91

92
[Application Core](./application-core.md)
93

94
### Plugin Management
95

96
Complete plugin lifecycle management including registration, activation, deactivation, and service resolution. Supports both automatic startup plugins and deferred loading.
97

98
```typescript { .api }
99
// Plugin registration
100
registerPlugin(plugin: IPlugin<this, any>): void;
101
registerPlugins(plugins: IPlugin<this, any>[]): void;
102

103
// Plugin activation/deactivation
104
activatePlugin(id: string): Promise<void>;
105
deactivatePlugin(id: string): Promise<string[]>;
106
activateDeferredPlugins(): Promise<void>;
107

108
// Plugin introspection
109
hasPlugin(id: string): boolean;
110
isPluginActivated(id: string): boolean;
111
listPlugins(): string[];
112
getPluginDescription(id: string): string;
113
```
114

115
[Plugin Management](./plugin-management.md)
116

117
### Service Resolution
118

119
Dependency injection system for resolving plugin services with support for both required and optional dependencies.
120

121
```typescript { .api }
122
resolveRequiredService<U>(token: Token<U>): Promise<U>;
123
resolveOptionalService<U>(token: Token<U>): Promise<U | null>;
124
```
125

126
[Service Resolution](./service-resolution.md)
127

128
### Application Lifecycle
129

130
Application startup process and event handling for managing the complete application lifecycle from initialization to shutdown.
131

132
```typescript { .api }
133
start(options?: Application.IStartOptions): Promise<void>;
134
handleEvent(event: Event): void;
135

136
interface Application.IStartOptions {
137
  hostID?: string;
138
  startPlugins?: string[];
139
  ignorePlugins?: string[];
140
  bubblingKeydown?: boolean;
141
}
142
```
143

144
[Application Lifecycle](./application-lifecycle.md)
145

146
## Types
147

148
```typescript { .api }
149
// Re-exported from @lumino/coreutils (deprecated)
150
interface IPlugin<T = any, U = any> {
151
  id: string;
152
  description?: string;
153
  activate: (application: T, ...args: any[]) => U | Promise<U>;
154
  deactivate?: (application: T, ...args: any[]) => void | Promise<void>;
155
  autoStart?: boolean | 'defer';
156
  provides?: Token<U>;
157
  requires?: Token<any>[];
158
  optional?: Token<any>[];
159
}
160

161
// From @lumino/coreutils
162
interface Token<T> {
163
  readonly name: string;
164
}
165

166
// From @lumino/commands
167
class CommandRegistry {
168
  processKeydownEvent(event: KeyboardEvent): void;
169
  processKeyupEvent(event: KeyboardEvent): void;
170
}
171

172
// From @lumino/widgets
173
class ContextMenu {
174
  open(event: PointerEvent): boolean;
175
}
176

177
class Widget {
178
  static attach(widget: Widget, host: Element): void;
179
  update(): void;
180
}
181

182
interface Menu.IRenderer {
183
  // Context menu renderer interface
184
}
185
```