0
# JupyterLab Builder
1

2
JupyterLab Builder is a comprehensive build toolchain specifically designed for compiling and building JupyterLab extensions. It provides webpack-based build infrastructure with TypeScript compilation, asset processing, module federation, and custom plugins for the JupyterLab ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @jupyterlab/builder
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @jupyterlab/builder`
10
- **Environment**: Node.js only (not browser-compatible)
11

12
## Core Imports
13

14
```typescript
15
import { Build, WPPlugin } from "@jupyterlab/builder";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { Build, WPPlugin } = require("@jupyterlab/builder");
22
```
23

24
For extension configuration:
25

26
```typescript
27
import generateConfig from "@jupyterlab/builder/lib/extensionConfig";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { Build, WPPlugin } from "@jupyterlab/builder";
34
import * as webpack from "webpack";
35

36
// Ensure extension assets are available
37
const themeConfigs = Build.ensureAssets({
38
  output: "./build",
39
  packageNames: ["@my-org/my-extension"],
40
  schemaOutput: "./schemas",
41
  themeOutput: "./themes"
42
});
43

44
// Use custom webpack plugins
45
const plugins = [
46
  new WPPlugin.FrontEndPlugin("./build", "./static"),
47
  new WPPlugin.JSONLicenseWebpackPlugin()
48
];
49

50
// Create webpack configuration
51
const compiler = webpack(themeConfigs.concat({
52
  plugins,
53
  // ... other webpack config
54
}));
55
```
56

57
## Architecture
58

59
JupyterLab Builder is built around several key components:
60

61
- **Build Utilities** (`Build` namespace): Core functions for asset management and extension metadata handling
62
- **Webpack Plugins** (`WPPlugin` namespace): Custom webpack plugins for JupyterLab-specific build tasks
63
- **Extension Configuration**: Automated webpack configuration generation for extensions
64
- **CLI Tool**: Command-line interface for building extensions from the command line
65
- **Module Federation**: Integration with webpack's module federation for extension isolation
66

67
The build system leverages webpack 5's module federation to ensure extensions can be loaded dynamically while sharing common dependencies with the core JupyterLab application.
68

69
## Capabilities
70

71
### Build Utilities
72

73
Core build functionality for managing JupyterLab extension assets, including schema copying, theme processing, and extension metadata normalization.
74

75
```typescript { .api }
76
namespace Build {
77
  function ensureAssets(options: IEnsureOptions): webpack.Configuration[];
78
  function normalizeExtension(module: IModule): ILabExtension;
79
  
80
  interface IEnsureOptions {
81
    output: string;
82
    schemaOutput?: string;
83
    themeOutput?: string;
84
    packageNames: ReadonlyArray<string>;
85
    packagePaths?: ReadonlyArray<string>;
86
  }
87
  
88
  interface ILabExtension {
89
    readonly extension?: boolean | string;
90
    readonly mimeExtension?: boolean | string;
91
    readonly schemaDir?: string;
92
    readonly themePath?: string;
93
  }
94
  
95
  interface IModule {
96
    jupyterlab?: ILabExtension;
97
    main?: string;
98
    name: string;
99
  }
100
}
101
```
102

103
[Build Utilities](./build-utilities.md)
104

105
### Webpack Plugins
106

107
Custom webpack plugins designed for JupyterLab extension building, including asset copying, license reporting, and build optimization.
108

109
```typescript { .api }
110
namespace WPPlugin {
111
  class FrontEndPlugin {
112
    constructor(buildDir: string, staticDir: string);
113
    apply(compiler: webpack.Compiler): void;
114
  }
115
  
116
  class JSONLicenseWebpackPlugin extends LicenseWebpackPlugin {
117
    constructor(pluginOptions?: PluginOptions);
118
    renderLicensesJSON(modules: LicenseIdentifiedModule[]): string;
119
  }
120
  
121
  class FilterWatchIgnorePlugin {
122
    constructor(ignored: (path: string) => boolean);
123
    apply(compiler: webpack.Compiler): void;
124
  }
125
  
126
  class NowatchDuplicatePackageCheckerPlugin extends DuplicatePackageCheckerPlugin {
127
    constructor(options: DuplicatePackageCheckerPlugin.Options);
128
    apply(compiler: webpack.Compiler): void;
129
  }
130
  
131
  const DEFAULT_LICENSE_REPORT_FILENAME: "third-party-licenses.json";
132
}
133
```
134

135
[Webpack Plugins](./webpack-plugins.md)
136

137
### Extension Configuration
138

139
Automated webpack configuration generation for JupyterLab extensions with module federation, shared dependencies, and asset processing.
140

141
```typescript { .api }
142
interface IOptions {
143
  packagePath?: string;
144
  corePath?: string;
145
  staticUrl?: string;
146
  mode?: 'development' | 'production';
147
  devtool?: string;
148
  watchMode?: boolean;
149
}
150

151
function generateConfig(options?: IOptions): webpack.Configuration[];
152
```
153

154
[Extension Configuration](./extension-configuration.md)
155

156
### Command Line Interface
157

158
Command-line tool for building JupyterLab extensions with development and production modes.
159

160
```bash
161
build-labextension [options] <extensionPath>
162
```
163

164
[CLI Tool](./cli-tool.md)