0
# Plugin Management
1

2
Complete plugin lifecycle management including registration, activation, deactivation, and service resolution. The Application class provides comprehensive plugin management capabilities through its integrated PluginRegistry.
3

4
## Capabilities
5

6
### Plugin Registration
7

8
Register individual plugins or multiple plugins with the application.
9

10
```typescript { .api }
11
/**
12
 * Register a plugin with the application.
13
 * @param plugin - The plugin to register
14
 * @throws Error if a plugin with the same ID is already registered or has circular dependencies
15
 */
16
registerPlugin(plugin: IPlugin<this, any>): void;
17

18
/**
19
 * Register multiple plugins with the application.
20
 * @param plugins - The plugins to register
21
 */
22
registerPlugins(plugins: IPlugin<this, any>[]): void;
23
```
24

25
**Usage Examples:**
26

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

31
const app = new Application({ shell: new Widget() });
32

33
// Register a simple plugin
34
app.registerPlugin({
35
  id: 'logger',
36
  description: 'Logging functionality',
37
  activate: () => {
38
    console.log('Logger plugin activated');
39
    return { log: (msg: string) => console.log(msg) };
40
  }
41
});
42

43
// Register multiple plugins at once
44
app.registerPlugins([
45
  {
46
    id: 'plugin-a',
47
    activate: () => console.log('Plugin A activated')
48
  },
49
  {
50
    id: 'plugin-b', 
51
    activate: () => console.log('Plugin B activated')
52
  }
53
]);
54
```
55

56
### Plugin Activation
57

58
Control when and how plugins are activated within the application.
59

60
```typescript { .api }
61
/**
62
 * Activate the plugin with the given ID.
63
 * @param id - The ID of the plugin of interest
64
 * @returns A promise which resolves when the plugin is activated or rejects if it cannot be activated
65
 */
66
activatePlugin(id: string): Promise<void>;
67

68
/**
69
 * Activate all the deferred plugins.
70
 * @returns A promise which resolves when each plugin is activated or rejects if one cannot be activated
71
 */
72
activateDeferredPlugins(): Promise<void>;
73
```
74

75
**Usage Examples:**
76

77
```typescript
78
// Activate a specific plugin
79
try {
80
  await app.activatePlugin('my-plugin');
81
  console.log('Plugin activated successfully');
82
} catch (error) {
83
  console.error('Failed to activate plugin:', error);
84
}
85

86
// Activate all deferred plugins
87
await app.activateDeferredPlugins();
88
console.log('All deferred plugins activated');
89
```
90

91
### Plugin Deactivation
92

93
Deactivate plugins and their dependents when they support deactivation.
94

95
```typescript { .api }
96
/**
97
 * Deactivate the plugin and its downstream dependents if and only if the
98
 * plugin and its dependents all support deactivate.
99
 * @param id - The ID of the plugin of interest
100
 * @returns A list of IDs of downstream plugins deactivated with this one
101
 */
102
deactivatePlugin(id: string): Promise<string[]>;
103

104
/**
105
 * Deregister a plugin with the application.
106
 * @param id - The ID of the plugin of interest
107
 * @param force - Whether to deregister the plugin even if it is active
108
 */
109
deregisterPlugin(id: string, force?: boolean): void;
110
```
111

112
**Usage Example:**
113

114
```typescript
115
// Deactivate a plugin and its dependents
116
const deactivatedPlugins = await app.deactivatePlugin('my-plugin');
117
console.log('Deactivated plugins:', deactivatedPlugins);
118

119
// Deregister a plugin
120
app.deregisterPlugin('old-plugin', true); // Force deregistration even if active
121
```
122

123
### Plugin Introspection
124

125
Query the state and properties of registered plugins.
126

127
```typescript { .api }
128
/**
129
 * Test whether a plugin is registered with the application.
130
 * @param id - The ID of the plugin of interest
131
 * @returns true if the plugin is registered, false otherwise
132
 */
133
hasPlugin(id: string): boolean;
134

135
/**
136
 * Test whether a plugin is activated with the application.
137
 * @param id - The ID of the plugin of interest  
138
 * @returns true if the plugin is activated, false otherwise
139
 */
140
isPluginActivated(id: string): boolean;
141

142
/**
143
 * List the IDs of the plugins registered with the application.
144
 * @returns A new array of the registered plugin IDs
145
 */
146
listPlugins(): string[];
147

148
/**
149
 * Get a plugin description.
150
 * @param id - The ID of the plugin of interest
151
 * @returns The plugin description or empty string if not found
152
 */
153
getPluginDescription(id: string): string;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
// Check if a plugin exists
160
if (app.hasPlugin('my-plugin')) {
161
  console.log('Plugin is registered');
162
}
163

164
// Check if a plugin is active
165
if (app.isPluginActivated('my-plugin')) {
166
  console.log('Plugin is currently active');
167
}
168

169
// Get all registered plugins
170
const pluginIds = app.listPlugins();
171
console.log('Registered plugins:', pluginIds);
172

173
// Get plugin description
174
const description = app.getPluginDescription('my-plugin');
175
console.log('Plugin description:', description);
176
```
177

178
### Plugin Interface
179

180
The IPlugin interface defines the structure for all plugins registered with the application.
181

182
```typescript { .api }
183
interface IPlugin<T = any, U = any> {
184
  /** Unique identifier for the plugin */
185
  id: string;
186
  /** Optional description of the plugin */
187
  description?: string;
188
  /** Function called when the plugin is activated */
189
  activate: (application: T, ...args: any[]) => U | Promise<U>;
190
  /** Optional function called when the plugin is deactivated */
191
  deactivate?: (application: T, ...args: any[]) => void | Promise<void>;
192
  /** Whether the plugin should be activated automatically on startup */
193
  autoStart?: boolean | 'defer';
194
  /** Token for the service this plugin provides */
195
  provides?: Token<U>;
196
  /** Array of tokens for services this plugin requires */
197
  requires?: Token<any>[];
198
  /** Array of tokens for services this plugin optionally uses */
199
  optional?: Token<any>[];
200
}
201
```
202

203
**Plugin Configuration Examples:**
204

205
```typescript
206
import { Token } from "@lumino/coreutils";
207

208
// Service tokens
209
const ILoggerService = new Token<ILoggerService>('ILoggerService');
210
const IConfigService = new Token<IConfigService>('IConfigService');
211

212
// Plugin providing a service
213
const loggerPlugin: IPlugin<Application> = {
214
  id: 'logger',
215
  description: 'Application logging service',
216
  provides: ILoggerService,
217
  activate: (app: Application) => {
218
    return {
219
      log: (message: string) => console.log(`[LOG] ${message}`),
220
      error: (message: string) => console.error(`[ERROR] ${message}`)
221
    };
222
  }
223
};
224

225
// Plugin requiring services
226
const featurePlugin: IPlugin<Application> = {
227
  id: 'feature',
228
  description: 'Feature that uses logging',
229
  requires: [ILoggerService],
230
  optional: [IConfigService],
231
  activate: (app: Application, logger: any, config?: any) => {
232
    logger.log('Feature plugin activated');
233
    if (config) {
234
      logger.log('Configuration available');
235
    }
236
    return {};
237
  }
238
};
239

240
// Deferred plugin (activated later)
241
const deferredPlugin: IPlugin<Application> = {
242
  id: 'deferred-feature',
243
  autoStart: 'defer',
244
  activate: (app: Application) => {
245
    console.log('Deferred plugin activated');
246
    return {};
247
  }
248
};
249
```