0
# Frontend Plugins
1

2
The frontend plugin system provides JupyterLab extensions that enhance the notebook interface with notebook-specific functionality. These TypeScript/JavaScript plugins integrate with the JupyterLab frontend architecture to provide features like checkpoint indicators, kernel status, output scrolling, and UI enhancements.
3

4
## Capabilities
5

6
### Core Application Framework
7

8
The frontend application framework provides the main application class and shell interface for the notebook frontend.
9

10
```typescript { .api }
11
class NotebookApp extends JupyterFrontEnd<INotebookShell> {
12
    /**
13
     * Main frontend application class for Jupyter Notebook.
14
     * 
15
     * Extends JupyterFrontEnd to provide notebook-specific functionality
16
     * while maintaining compatibility with the JupyterLab ecosystem.
17
     */
18
    constructor(options?: NotebookApp.IOptions);
19
    readonly name: string = 'Jupyter Notebook';
20
    readonly namespace: string;
21
    readonly version: string;
22
    readonly restored: Promise<void>;
23
    get info(): JupyterLab.IInfo;
24
    get paths(): JupyterFrontEnd.IPaths;
25
    registerPluginModule(mod: NotebookApp.IPluginModule): void;
26
    registerPluginModules(mods: NotebookApp.IPluginModule[]): void;
27
}
28

29
interface INotebookShell {
30
    /**
31
     * Shell interface for notebook application.
32
     * 
33
     * Defines the structure and behavior of the notebook UI shell,
34
     * managing layout, widgets, and user interface components.
35
     */
36
}
37

38
class NotebookShell implements INotebookShell {
39
    /**
40
     * Default shell implementation for notebook interface.
41
     * 
42
     * Provides the concrete implementation of the notebook shell
43
     * with specific layout and widget management for notebooks.
44
     */
45
}
46
```
47

48
### Path and File Management
49

50
Interface and services for opening files and managing navigation within the notebook application.
51

52
```typescript { .api }
53
interface INotebookPathOpener {
54
    /**
55
     * Service for opening paths in the notebook application.
56
     * 
57
     * Provides functionality to open files, directories, and notebooks
58
     * with customizable options for window targeting and parameters.
59
     */
60
    open(options: INotebookPathOpener.IOpenOptions): WindowProxy | null;
61
}
62

63
namespace INotebookPathOpener {
64
    interface IOpenOptions {
65
        /**
66
         * Options for opening paths in the application.
67
         */
68
        prefix: string;          // URL prefix including base URL
69
        path?: string;           // Path to open (e.g., 'setup.py', 'notebooks/example.ipynb')
70
        searchParams?: URLSearchParams;  // Extra search parameters for URL
71
        target?: string;         // Browsing context name for window.open
72
        features?: string;       // Features parameter for window.open
73
    }
74
}
75

76
const INotebookPathOpener: Token<INotebookPathOpener>;
77
/**
78
 * Dependency injection token for path opener service.
79
 * 
80
 * Used to register and inject the path opener service throughout
81
 * the application for consistent file and directory opening behavior.
82
 */
83
```
84

85
### Core Plugin Collection
86

87
The main collection of JupyterLab plugins that provide notebook-specific functionality.
88

89
```typescript { .api }
90
const plugins: JupyterFrontEndPlugin<any>[];
91
/**
92
 * Array of all notebook-specific frontend plugins.
93
 * 
94
 * This default export contains all the plugins that should be
95
 * registered with the JupyterLab application to provide full
96
 * notebook functionality.
97
 */
98
```
99

100
### Lab Extension Plugins
101

102
Main lab extension plugins that provide notebook-specific functionality in JupyterLab.
103

104
```typescript { .api }
105
// Interface Switcher Plugin
106
const interfaceSwitcher: JupyterFrontEndPlugin<void>;
107
/**
108
 * Plugin to add custom toolbar items to the notebook page.
109
 * 
110
 * Provides interface switching functionality between Notebook, JupyterLab,
111
 * and NbClassic when available. Adds commands and toolbar buttons for
112
 * opening current notebook in different interfaces.
113
 */
114

115
// Launch Tree Plugin
116
const launchNotebookTree: JupyterFrontEndPlugin<void>;
117
/**
118
 * Plugin to add a command to open the Jupyter Notebook Tree.
119
 * 
120
 * Adds a command to launch the file browser in a new tab,
121
 * providing navigation from notebook to file browser interface.
122
 */
123
```
124

125
### Command Namespace
126

127
```typescript { .api }
128
namespace CommandIDs {
129
    const launchNotebookTree: string;  // 'jupyter-notebook:launch-tree'
130
    const openNotebook: string;        // 'jupyter-notebook:open-notebook'
131
    const openLab: string;             // 'jupyter-notebook:open-lab'
132
    const openNbClassic: string;       // 'jupyter-notebook:open-nbclassic'
133
}
134
```
135

136
### Plugin Configuration Interface
137

138
```typescript { .api }
139
interface ISwitcherChoice {
140
    command: string;
141
    commandLabel: string;
142
    commandDescription: string;
143
    buttonLabel: string;
144
    urlPrefix: string;
145
}
146
```
147

148
## Plugin Architecture
149

150
### Plugin Registration
151

152
```typescript
153
// Plugins are typically registered by importing and adding to JupyterLab
154
import { JupyterFrontEnd, JupyterFrontEndPlugin } from '@jupyterlab/application';
155
import plugins from '@jupyter-notebook/notebook-extension';
156

157
// Register all notebook plugins
158
const app = new JupyterFrontEnd();
159
plugins.forEach(plugin => {
160
    app.registerPlugin(plugin);
161
});
162
```
163

164
### Command System Integration
165

166
```typescript
167
// Plugins integrate with JupyterLab's command system
168
const app: JupyterFrontEnd = /* ... */;
169

170
// Commands added by plugins are accessible through the app
171
await app.commands.execute('notebook:toggle-full-width');
172
await app.commands.execute('notebook:close-and-halt');
173
await app.commands.execute('notebook:open-tree-tab');
174
await app.commands.execute('notebook:edit-metadata');
175
```
176

177
### Service Dependencies
178

179
```typescript
180
// Plugins declare dependencies on JupyterLab services
181
const examplePlugin: JupyterFrontEndPlugin<void> = {
182
    id: 'example-plugin',
183
    autoStart: true,
184
    requires: [INotebookTracker, ITranslator],
185
    optional: [ICommandPalette, ISettingRegistry],
186
    activate: (
187
        app: JupyterFrontEnd,
188
        tracker: INotebookTracker,
189
        translator: ITranslator,
190
        palette?: ICommandPalette,
191
        settings?: ISettingRegistry
192
    ) => {
193
        // Plugin implementation using injected services
194
    }
195
};
196
```
197

198
## Usage Examples
199

200
### Using the Path Opener Service
201

202
```typescript
203
import { INotebookPathOpener } from '@jupyter-notebook/application';
204

205
// Inject the path opener service
206
class MyWidget extends Widget {
207
    constructor(private pathOpener: INotebookPathOpener) {
208
        super();
209
    }
210
    
211
    openNotebook(path: string) {
212
        // Open a notebook in a new tab
213
        this.pathOpener.open({
214
            prefix: '/notebooks',
215
            path: path,
216
            target: '_blank'
217
        });
218
    }
219
    
220
    openDirectory(path: string) {
221
        // Open file browser for a directory
222
        this.pathOpener.open({
223
            prefix: '/tree',
224
            path: path,
225
            searchParams: new URLSearchParams({ view: 'tree' })
226
        });
227
    }
228
}
229
```
230

231
### Creating Custom Plugins
232

233
```typescript
234
import { JupyterFrontEnd, JupyterFrontEndPlugin } from '@jupyterlab/application';
235
import { INotebookShell } from '@jupyter-notebook/application';
236

237
const customPlugin: JupyterFrontEndPlugin<void> = {
238
    id: 'my-custom-notebook-plugin',
239
    description: 'Custom notebook functionality',
240
    autoStart: true,
241
    requires: [INotebookShell],
242
    activate: (app: JupyterFrontEnd, shell: INotebookShell) => {
243
        console.log('Custom notebook plugin loaded');
244
        
245
        // Add custom functionality
246
        app.commands.addCommand('custom:my-command', {
247
            label: 'My Custom Command',
248
            execute: () => {
249
                console.log('Custom command executed');
250
            }
251
        });
252
        
253
        // React to shell changes
254
        shell.currentChanged.connect(() => {
255
            console.log('Current widget changed');
256
        });
257
    }
258
};
259

260
export default customPlugin;
261
```
262

263
### Accessing Plugin Services
264

265
```typescript
266
// Access services provided by notebook plugins
267
import { JupyterFrontEnd } from '@jupyterlab/application';
268
import { INotebookTracker } from '@jupyterlab/notebook';
269

270
class NotebookManager {
271
    constructor(private app: JupyterFrontEnd) {}
272
    
273
    getCurrentNotebook() {
274
        // Access the current notebook through the tracker
275
        const tracker = this.app.serviceManager.get('notebook-tracker') as INotebookTracker;
276
        return tracker.currentWidget;
277
    }
278
    
279
    async executeCommand(command: string) {
280
        // Execute notebook-specific commands
281
        return await this.app.commands.execute(command);
282
    }
283
    
284
    isFullWidth(): boolean {
285
        // Check if full-width mode is enabled
286
        return this.app.commands.isToggled('notebook:toggle-full-width');
287
    }
288
}