0
# Application Framework
1

2
Core application management providing the main JupyterLab class, abstract base classes, and plugin system for building extensible notebook applications.
3

4
## Capabilities
5

6
### JupyterLab Class
7

8
Main application class that extends JupyterFrontEnd and provides the complete JupyterLab environment with plugin management and application lifecycle.
9

10
```typescript { .api }
11
/**
12
 * JupyterLab is the main application class that provides the complete JupyterLab environment
13
 */
14
class JupyterLab extends JupyterFrontEnd<ILabShell> {
15
  constructor(options?: JupyterLab.IOptions);
16
  
17
  /** The name of the application from PageConfig */
18
  readonly name: string;
19
  
20
  /** The namespace/prefix for plugins */
21
  readonly namespace: string;
22
  
23
  /** The version of the application from PageConfig */
24
  readonly version: string;
25
  
26
  /** Application status manager for busy/dirty states */
27
  readonly status: LabStatus;
28
  
29
  /** Application information including dev mode and connection status */
30
  readonly info: JupyterLab.IInfo;
31
  
32
  /** Application paths configuration for URLs and directories */
33
  readonly paths: JupyterFrontEnd.IPaths;
34
  
35
  /** Promise that resolves when all plugins are activated */
36
  readonly allPluginsActivated: Promise<void>;
37
  
38
  /** @deprecated Plugin registration errors (will be removed) */
39
  readonly registerPluginErrors: Array<Error>;
40
  
41
  /** @deprecated Register a plugin module (use Application.registerPlugin instead) */
42
  registerPluginModule(mod: JupyterLab.IPluginModule): void;
43
  
44
  /** @deprecated Register multiple plugin modules (use Application.registerPlugins instead) */
45
  registerPluginModules(mods: JupyterLab.IPluginModule[]): void;
46
}
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
import { JupyterLab, LabShell } from "@jupyterlab/application";
53

54
// Basic JupyterLab creation
55
const lab = new JupyterLab();
56

57
// With custom options
58
const customLab = new JupyterLab({
59
  shell: new LabShell(),
60
  disabled: { patterns: ['*unwanted*'] },
61
  deferred: { patterns: ['*heavy-plugin*'] }
62
});
63

64
// Wait for all plugins to be activated
65
await customLab.allPluginsActivated;
66
console.log('All plugins are ready!');
67

68
// Check application status
69
console.log('App name:', customLab.name);
70
console.log('Version:', customLab.version);
71
console.log('Is dev mode:', customLab.info.devMode);
72
```
73

74
### JupyterFrontEnd Abstract Base Class
75

76
Abstract base class providing the foundation for JupyterLab-like applications with plugin support and common application services.
77

78
```typescript { .api }
79
/**
80
 * Base Jupyter front-end application class that provides plugin support and common services
81
 * @template T - The shell type (defaults to JupyterFrontEnd.IShell)
82
 * @template U - Supported format names (defaults to 'desktop' | 'mobile')
83
 */
84
abstract class JupyterFrontEnd<
85
  T extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell,
86
  U extends string = 'desktop' | 'mobile'
87
> extends Application<T> {
88
  constructor(options: JupyterFrontEnd.IOptions<T>);
89
  
90
  /** The name of this Jupyter front-end application */
91
  abstract readonly name: string;
92
  
93
  /** A namespace/prefix plugins may use to denote their provenance */
94
  abstract readonly namespace: string;
95
  
96
  /** The version of this Jupyter front-end application */
97
  abstract readonly version: string;
98
  
99
  /** The command linker used by the application */
100
  readonly commandLinker: CommandLinker;
101
  
102
  /** The application context menu */
103
  readonly contextMenu: ContextMenuSvg;
104
  
105
  /** The document registry instance */
106
  readonly docRegistry: DocumentRegistry;
107
  
108
  /** A promise that resolves when the application is restored */
109
  readonly restored: Promise<void>;
110
  
111
  /** The service manager instance */
112
  readonly serviceManager: ServiceManager.IManager;
113
  
114
  /** The application form factor (desktop, mobile, etc.) */
115
  format: U;
116
  
117
  /** A signal emitted when the format changes */
118
  readonly formatChanged: ISignal<this, U>;
119
  
120
  /** 
121
   * Test whether the application is in a specific context menu hit test 
122
   * @param fn - Function to test DOM nodes
123
   * @returns The matching element or undefined
124
   */
125
  contextMenuHitTest(fn: (node: HTMLElement) => boolean): HTMLElement | undefined;
126
}
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { JupyterFrontEnd, LabShell } from "@jupyterlab/application";
133

134
// Extending JupyterFrontEnd for a custom application
135
class MyNotebookApp extends JupyterFrontEnd<LabShell> {
136
  readonly name = 'My Notebook App';
137
  readonly namespace = 'myapp';
138
  readonly version = '1.0.0';
139
}
140

141
// Using the format system
142
const app = new MyNotebookApp({ shell: new LabShell() });
143
console.log('Current format:', app.format); // 'desktop'
144

145
app.format = 'mobile';
146
app.formatChanged.connect((sender, format) => {
147
  console.log('Format changed to:', format);
148
});
149

150
// Using context menu hit testing
151
const hitElement = app.contextMenuHitTest((node) => 
152
  node.classList.contains('my-special-element')
153
);
154
```
155

156
### Plugin Type System
157

158
Type definitions for creating plugins that work with JupyterFrontEnd applications.
159

160
```typescript { .api }
161
/**
162
 * The type for all JupyterFrontEnd application plugins
163
 * @template T - The type that the plugin provides upon being activated
164
 * @template U - The type of the application shell
165
 * @template V - The type that defines the application formats
166
 */
167
type JupyterFrontEndPlugin<
168
  T,
169
  U extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell,
170
  V extends string = 'desktop' | 'mobile'
171
> = IPlugin<JupyterFrontEnd<U, V>, T>;
172
```
173

174
### Application Information Interface
175

176
Provides runtime information about the JupyterLab application environment.
177

178
```typescript { .api }
179
/**
180
 * Application information service for runtime configuration data
181
 */
182
interface JupyterLab.IInfo {
183
  /** Whether the application is running in development mode */
184
  readonly devMode: boolean;
185
  
186
  /** Whether the application is connected to the server */
187
  readonly isConnected: boolean;
188
  
189
  /** Deferred plugin configuration, if any */
190
  readonly deferred: { patterns?: string[]; matches?: string[] } | null;
191
  
192
  /** Disabled plugin configuration, if any */
193
  readonly disabled: { patterns?: string[]; matches?: string[] } | null;
194
}
195

196
/**
197
 * Service token for accessing application information
198
 */
199
const IInfo: Token<JupyterLab.IInfo>;
200
```
201

202
### Application Paths Interface
203

204
Configuration for URL routing and directory paths used throughout the application.
205

206
```typescript { .api }
207
/**
208
 * Interface defining URL and directory paths for the application
209
 */
210
interface JupyterFrontEnd.IPaths {
211
  readonly urls: {
212
    readonly base: string;
213
    readonly notFound?: string;
214
    readonly app: string;
215
    readonly static: string;
216
    readonly settings: string;
217
    readonly themes: string;
218
    readonly doc: string;
219
    readonly translations: string;
220
    readonly hubHost?: string;
221
    readonly hubPrefix?: string;
222
    readonly hubUser?: string;
223
    readonly hubServerName?: string;
224
  };
225
  readonly directories: {
226
    readonly appDir: string;
227
    readonly themesDir: string;
228
    readonly userSettingsDir: string;
229
    readonly schemasDir: string;
230
    readonly workspacesDir: string;
231
  };
232
}
233

234
/**
235
 * Service token for accessing application paths
236
 */
237
const IPaths: Token<JupyterFrontEnd.IPaths>;
238
```
239

240
### Tree Resolver Interface
241

242
Interface for resolving tree paths in the application routing system.
243

244
```typescript { .api }
245
/**
246
 * Interface for resolving tree paths in routing
247
 */
248
interface JupyterFrontEnd.ITreeResolver {
249
  /** Resolve a tree path and return path information */
250
  resolve(path: string): Promise<JupyterFrontEnd.ITreeResolver.Paths | null>;
251
}
252

253
namespace JupyterFrontEnd.ITreeResolver {
254
  /** Result of tree path resolution */
255
  type Paths = {
256
    file: string;
257
    workspace: string;
258
  };
259
}
260

261
/**
262
 * Service token for tree path resolution
263
 */
264
const ITreeResolver: Token<JupyterFrontEnd.ITreeResolver>;
265

266
/**
267
 * Utility function to detect if application is in document mode
268
 * @param path - The current path
269
 * @param paths - Application paths configuration
270
 * @returns True if in document mode
271
 */
272
function inDocMode(path: string, paths: JupyterFrontEnd.IPaths): boolean;
273
```
274

275
## Types
276

277
### Constructor Options
278

279
```typescript { .api }
280
namespace JupyterLab {
281
  interface IOptions {
282
    /** Custom shell instance (defaults to new LabShell()) */
283
    shell?: ILabShell;
284
    
285
    /** Service manager instance */
286
    serviceManager?: ServiceManager.IManager;
287
    
288
    /** Custom paths configuration */
289
    paths?: Partial<JupyterFrontEnd.IPaths>;
290
    
291
    /** Plugin patterns to disable */
292
    disabled?: { patterns?: string[]; matches?: string[] };
293
    
294
    /** Plugin patterns to defer loading */
295
    deferred?: { patterns?: string[]; matches?: string[] };
296
    
297
    /** MIME renderer extensions */
298
    mimeExtensions?: IRenderMime.IExtensionModule[];
299
    
300
    /** Link handler for external links */
301
    linkHandler?: ILinkHandler;
302
  }
303
}
304

305
namespace JupyterFrontEnd {
306
  interface IOptions<T extends IShell> {
307
    /** Shell instance (required) */
308
    shell: T;
309
    
310
    /** Command linker instance */
311
    commandLinker?: CommandLinker;
312
    
313
    /** Document registry instance */
314
    docRegistry?: DocumentRegistry;
315
    
316
    /** Application restored promise */
317
    restored?: Promise<void>;
318
    
319
    /** Service manager instance */
320
    serviceManager?: ServiceManager.IManager;
321
    
322
    /** Context menu renderer */
323
    contextMenuRenderer?: IRenderer;
324
  }
325
}
326
```
327

328
### Shell Interface Requirements
329

330
```typescript { .api }
331
/**
332
 * Minimal shell interface that applications must implement
333
 */
334
interface JupyterFrontEnd.IShell {
335
  /** Signal emitted when the active widget changes */
336
  readonly activeChanged: ISignal<this, IChangedArgs>;
337
  
338
  /** Signal emitted when the current widget changes */
339
  readonly currentChanged: ISignal<this, IChangedArgs>;
340
  
341
  /** The currently active widget */
342
  readonly activeWidget: Widget | null;
343
  
344
  /** The current widget in focus */
345
  readonly currentWidget: Widget | null;
346
  
347
  /**
348
   * Activate a widget by its ID
349
   * @param id - Widget ID to activate
350
   */
351
  activateById(id: string): void;
352
  
353
  /**
354
   * Add a widget to the shell
355
   * @param widget - Widget to add
356
   * @param area - Area to add the widget to
357
   * @param options - Additional options
358
   */
359
  add(widget: Widget, area?: string, options?: any): void;
360
  
361
  /**
362
   * Iterate over widgets in a specific area
363
   * @param area - Area to iterate over (optional)
364
   * @returns Iterator of widgets
365
   */
366
  widgets(area?: string): IterableIterator<Widget>;
367
}
368

369
interface IChangedArgs {
370
  /** Previous widget value */
371
  readonly oldValue: Widget | null;
372
  
373
  /** New widget value */
374
  readonly newValue: Widget | null;
375
}
376
```