0
# JupyterLab Application
1

2
JupyterLab Application provides the core application framework for JupyterLab, serving as the architectural foundation for building extensible, plugin-based notebook environments. It includes the main application class, shell management system, layout restoration capabilities, URL routing, and a comprehensive plugin infrastructure that enables the modular JupyterLab ecosystem.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { 
15
  JupyterLab, 
16
  JupyterFrontEnd, 
17
  LabShell, 
18
  ILabShell,
19
  LayoutRestorer,
20
  ILayoutRestorer,
21
  Router,
22
  IRouter
23
} from "@jupyterlab/application";
24
```
25

26
For CommonJS:
27

28
```javascript
29
const { 
30
  JupyterLab, 
31
  JupyterFrontEnd, 
32
  LabShell,
33
  LayoutRestorer,
34
  Router 
35
} = require("@jupyterlab/application");
36
```
37

38
## Basic Usage
39

40
```typescript
41
import { JupyterLab, LabShell } from "@jupyterlab/application";
42

43
// Create a JupyterLab application
44
const lab = new JupyterLab({
45
  shell: new LabShell()
46
});
47

48
// Register plugins
49
lab.registerPlugin({
50
  id: 'my-plugin',
51
  autoStart: true,
52
  activate: (app) => {
53
    console.log('Plugin activated!');
54
  }
55
});
56

57
// Start the application
58
lab.start().then(() => {
59
  console.log('JupyterLab started successfully');
60
});
61
```
62

63
## Architecture
64

65
The JupyterLab Application framework is built around several key architectural components:
66

67
- **Application Layer**: `JupyterLab` class extends the abstract `JupyterFrontEnd` base class, providing plugin management and application lifecycle
68
- **Shell System**: `LabShell` implements the `ILabShell` interface, managing UI layout with multiple areas (main, left, right, top, bottom, header, menu, down)
69
- **Plugin System**: Service token-based dependency injection with `JupyterFrontEndPlugin` type for extensibility
70
- **Layout Management**: `LayoutRestorer` provides persistent layout state across application sessions
71
- **Routing System**: `Router` handles URL-based navigation and command routing
72
- **Status Management**: `LabStatus` tracks application busy/dirty states with reactive signals
73
- **Service Architecture**: Token-based services enable loose coupling and testability
74

75
## Capabilities
76

77
### Application Framework
78

79
Core application management including the main JupyterLab class, abstract base classes, and plugin system for building extensible notebook applications.
80

81
```typescript { .api }
82
class JupyterLab extends JupyterFrontEnd<ILabShell> {
83
  constructor(options?: JupyterLab.IOptions);
84
  readonly name: string;
85
  readonly namespace: string;
86
  readonly version: string;
87
  readonly status: LabStatus;
88
  readonly info: JupyterLab.IInfo;
89
  readonly paths: JupyterFrontEnd.IPaths;
90
  readonly allPluginsActivated: Promise<void>;
91
}
92

93
abstract class JupyterFrontEnd<T extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell, U extends string = 'desktop' | 'mobile'> extends Application<T> {
94
  constructor(options: JupyterFrontEnd.IOptions<T>);
95
  abstract readonly name: string;
96
  abstract readonly namespace: string;
97
  abstract readonly version: string;
98
  readonly commandLinker: CommandLinker;
99
  readonly contextMenu: ContextMenuSvg;
100
  readonly docRegistry: DocumentRegistry;
101
  readonly restored: Promise<void>;
102
  readonly serviceManager: ServiceManager.IManager;
103
  format: U;
104
  readonly formatChanged: ISignal<this, U>;
105
}
106

107
type JupyterFrontEndPlugin<T, U extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell, V extends string = 'desktop' | 'mobile'> = IPlugin<JupyterFrontEnd<U, V>, T>;
108
```
109

110
[Application Framework](./application-framework.md)
111

112
### Shell Management
113

114
UI shell system providing multi-area layout management, widget placement, tab navigation, and responsive design with collapsible sidebars.
115

116
```typescript { .api }
117
interface ILabShell extends LabShell {
118
  // Implemented by LabShell class
119
}
120

121
class LabShell extends Widget implements JupyterFrontEnd.IShell {
122
  constructor(options?: ILabShell.IOptions);
123
  readonly activeChanged: ISignal<this, ILabShell.IChangedArgs>;
124
  readonly currentChanged: ISignal<this, ILabShell.IChangedArgs>;
125
  readonly layoutModified: ISignal<this, void>;
126
  readonly activeWidget: Widget | null;
127
  readonly currentWidget: Widget | null;
128
  add(widget: Widget, area?: ILabShell.Area, options?: DocumentRegistry.IOpenOptions): void;
129
  activateById(id: string): void;
130
  collapseLeft(): void;
131
  collapseRight(): void;
132
  saveLayout(): ILabShell.ILayout;
133
}
134

135
type ILabShell.Area = 'main' | 'header' | 'top' | 'menu' | 'left' | 'right' | 'bottom' | 'down';
136
```
137

138
[Shell Management](./shell-management.md)
139

140
### Layout Restoration
141

142
Persistent layout state management for saving and restoring widget arrangements, positions, and application state across sessions.
143

144
```typescript { .api }
145
interface ILayoutRestorer extends IRestorer {
146
  readonly restored: Promise<void>;
147
  add(widget: Widget, name: string): void;
148
  restore<T extends Widget>(tracker: WidgetTracker<T>, options: IRestorer.IOptions<T>): Promise<any>;
149
}
150

151
class LayoutRestorer implements ILayoutRestorer {
152
  constructor(options: LayoutRestorer.IOptions);
153
  readonly isDeferred: boolean;
154
  readonly restored: Promise<void>;
155
  add(widget: Widget, name: string): void;
156
  fetch(): Promise<ILabShell.ILayout>;
157
  restore(tracker: WidgetTracker, options: IRestorer.IOptions<Widget>): Promise<any>;
158
  save(layout: ILabShell.ILayout): Promise<void>;
159
}
160
```
161

162
[Layout Restoration](./layout-restoration.md)
163

164
### URL Routing
165

166
URL-based navigation system with pattern matching, command mapping, and programmatic route handling for single-page application behavior.
167

168
```typescript { .api }
169
interface IRouter {
170
  readonly base: string;
171
  readonly commands: CommandRegistry;
172
  readonly current: IRouter.ILocation;
173
  readonly routed: ISignal<IRouter, IRouter.ILocation>;
174
  readonly stop: Token<void>;
175
  navigate(path: string, options?: IRouter.INavOptions): void;
176
  register(options: IRouter.IRegisterOptions): IDisposable;
177
  reload(): void;
178
  route(): Promise<void>;
179
}
180

181
class Router implements IRouter {
182
  constructor(options: Router.IOptions);
183
  readonly base: string;
184
  readonly commands: CommandRegistry;
185
  navigate(path: string, options?: IRouter.INavOptions): void;
186
  register(options: IRouter.IRegisterOptions): IDisposable;
187
  reload(): void;
188
  route(): Promise<void>;
189
}
190
```
191

192
[URL Routing](./url-routing.md)
193

194
### Service Tokens
195

196
Dependency injection tokens for service-based architecture, enabling loose coupling and extensibility in the plugin system.
197

198
```typescript { .api }
199
const IConnectionLost: Token<IConnectionLost>;
200
const ILabStatus: Token<ILabStatus>;
201
const IRouter: Token<IRouter>;
202
const ILayoutRestorer: Token<ILayoutRestorer>;
203
const IMimeDocumentTracker: Token<IMimeDocumentTracker>;
204
const ITreePathUpdater: Token<ITreePathUpdater>;
205

206
type IConnectionLost = (
207
  manager: ServiceManager.IManager,
208
  err: ServerConnection.NetworkError,
209
  translator?: ITranslator
210
) => Promise<void>;
211

212
interface ILabStatus {
213
  readonly busySignal: ISignal<JupyterFrontEnd<any, any>, boolean>;
214
  readonly dirtySignal: ISignal<JupyterFrontEnd<any, any>, boolean>;
215
  readonly isBusy: boolean;
216
  readonly isDirty: boolean;
217
  setBusy(): IDisposable;
218
  setDirty(): IDisposable;
219
}
220
```
221

222
[Service Tokens](./service-tokens.md)
223

224
### Status Management
225

226
Application state tracking for busy and dirty states with reactive signals, supporting UI feedback for long-running operations and unsaved changes.
227

228
```typescript { .api }
229
class LabStatus implements ILabStatus {
230
  constructor(app: JupyterFrontEnd<any, any>);
231
  readonly busySignal: ISignal<JupyterFrontEnd, boolean>;
232
  readonly dirtySignal: ISignal<JupyterFrontEnd, boolean>;
233
  readonly isBusy: boolean;
234
  readonly isDirty: boolean;
235
  setBusy(): IDisposable;
236
  setDirty(): IDisposable;
237
}
238
```
239

240
[Status Management](./status-management.md)
241

242
### MIME Rendering
243

244
Plugin creation utilities for MIME type rendering extensions, enabling support for custom content types and document formats.
245

246
```typescript { .api }
247
interface IMimeDocumentTracker extends IWidgetTracker<MimeDocument> {}
248

249
function createRendermimePlugins(
250
  extensions: IRenderMime.IExtensionModule[]
251
): JupyterFrontEndPlugin<void | IMimeDocumentTracker, any, any>[];
252

253
function createRendermimePlugin(
254
  tracker: WidgetTracker<MimeDocument>,
255
  item: IRenderMime.IExtension
256
): JupyterFrontEndPlugin<void>;
257
```
258

259
[MIME Rendering](./mime-rendering.md)
260

261
### Utility Functions
262

263
Helper functions for semantic command management, connection lost handling, and tree path updates for enhanced application functionality.
264

265
```typescript { .api }
266
function addSemanticCommand(options: ISemanticCommandOptions): void;
267

268
interface ISemanticCommandOptions {
269
  id: string;
270
  commands: CommandRegistry;
271
  shell: JupyterFrontEnd.IShell;
272
  semanticCommands: SemanticCommand | SemanticCommand[];
273
  default?: ISemanticCommandDefault;
274
  overrides?: Omit<CommandRegistry.ICommandOptions, 'execute'>;
275
  trans?: TranslationBundle;
276
}
277

278
function ConnectionLost(
279
  manager: ServiceManager.IManager,
280
  err: ServerConnection.NetworkError,
281
  translator?: ITranslator
282
): Promise<void>;
283

284
type ITreePathUpdater = (treePath: string) => void;
285
```
286

287
[Utility Functions](./utility-functions.md)
288

289
## Types
290

291
### Core Application Types
292

293
```typescript { .api }
294
namespace JupyterLab {
295
  interface IOptions {
296
    shell?: ILabShell;
297
    serviceManager?: ServiceManager.IManager;
298
    paths?: Partial<JupyterFrontEnd.IPaths>;
299
    disabled?: { patterns?: string[]; matches?: string[] };
300
    deferred?: { patterns?: string[]; matches?: string[] };
301
    mimeExtensions?: IRenderMime.IExtensionModule[];
302
    linkHandler?: ILinkHandler;
303
  }
304

305
  interface IInfo {
306
    readonly devMode: boolean;
307
    readonly isConnected: boolean;
308
    readonly deferred: { patterns?: string[]; matches?: string[] } | null;
309
    readonly disabled: { patterns?: string[]; matches?: string[] } | null;
310
  }
311
}
312

313
namespace JupyterFrontEnd {
314
  interface IOptions<T extends IShell> {
315
    shell: T;
316
    commandLinker?: CommandLinker;
317
    docRegistry?: DocumentRegistry;
318
    restored?: Promise<void>;
319
    serviceManager?: ServiceManager.IManager;
320
    contextMenuRenderer?: IRenderer;
321
  }
322

323
  interface IShell {
324
    readonly activeChanged: ISignal<this, IChangedArgs>;
325
    readonly currentChanged: ISignal<this, IChangedArgs>;
326
    readonly activeWidget: Widget | null;
327
    readonly currentWidget: Widget | null;
328
    activateById(id: string): void;
329
    add(widget: Widget, area?: string, options?: any): void;
330
    widgets(area?: string): IterableIterator<Widget>;
331
  }
332

333
  interface IPaths {
334
    readonly urls: {
335
      readonly base: string;
336
      readonly notFound?: string;
337
      readonly app: string;
338
      readonly static: string;
339
      readonly settings: string;
340
      readonly themes: string;
341
      readonly doc: string;
342
      readonly translations: string;
343
      readonly hubHost?: string;
344
      readonly hubPrefix?: string;
345
      readonly hubUser?: string;
346
      readonly hubServerName?: string;
347
    };
348
    readonly directories: {
349
      readonly appDir: string;
350
      readonly themesDir: string;
351
      readonly userSettingsDir: string;
352
      readonly schemasDir: string;
353
      readonly workspacesDir: string;
354
    };
355
  }
356
}
357
```
358

359
### Shell Layout Types
360

361
```typescript { .api }
362
namespace ILabShell {
363
  interface IOptions {
364
    hiddenMode?: DockPanel.Mode;
365
    waitForRestore?: boolean;
366
  }
367

368
  interface ILayout {
369
    readonly fresh?: boolean;
370
    readonly mainArea: IMainArea | null;
371
    readonly downArea: IDownArea | null;
372
    readonly leftArea: ISideArea | null;
373
    readonly rightArea: ISideArea | null;
374
    readonly topArea: ITopArea | null;
375
    readonly relativeSizes: number[] | null;
376
    mode?: DockPanel.Mode;
377
    leftCollapsed: boolean;
378
    rightCollapsed: boolean;
379
  }
380

381
  interface IChangedArgs {
382
    readonly oldValue: Widget | null;
383
    readonly newValue: Widget | null;
384
  }
385

386
  interface ICurrentPathChangedArgs {
387
    readonly oldValue: string;
388
    readonly newValue: string;
389
  }
390
}
391
```
392

393
### Router Types
394

395
```typescript { .api }
396
namespace IRouter {
397
  interface ILocation extends ReadonlyPartialJSONObject {
398
    hash: string;
399
    path: string;
400
    request: string;
401
    search?: string;
402
  }
403

404
  interface INavOptions {
405
    hard?: boolean;
406
    skipRouting?: boolean;
407
  }
408

409
  interface IRegisterOptions {
410
    command: string;
411
    pattern: RegExp;
412
    rank?: number;
413
  }
414
}
415
```