0
# Extension Configuration
1
2
Automated webpack configuration generation for JupyterLab extensions with module federation, shared dependencies, asset processing, and development/production optimizations.
3
4
## Capabilities
5
6
### Configuration Generation
7
8
Generates complete webpack configurations for building JupyterLab extensions with module federation and shared dependency management.
9
10
```typescript { .api }
11
/**
12
* Generates webpack configuration for JupyterLab extension building
13
* @param options - Configuration options for the build
14
* @returns Array of webpack configuration objects
15
*/
16
function generateConfig(options?: IOptions): webpack.Configuration[];
17
18
interface IOptions {
19
/** Path to extension package directory */
20
packagePath?: string;
21
/** Path to core JupyterLab package directory */
22
corePath?: string;
23
/** URL for build assets if hosted outside the built extension */
24
staticUrl?: string;
25
/** Build mode: development or production */
26
mode?: 'development' | 'production';
27
/** Source map configuration */
28
devtool?: string;
29
/** Whether in watch mode */
30
watchMode?: boolean;
31
}
32
```
33
34
The configuration generator provides:
35
36
1. **Module Federation Setup**: Configures webpack's Module Federation Plugin for extension isolation
37
2. **Shared Dependencies**: Manages shared packages between extensions and core JupyterLab
38
3. **Asset Processing**: Handles schemas, themes, and static assets
39
4. **Development Optimizations**: Source maps, build logging, and watch mode support
40
5. **Production Optimizations**: License reporting, minification, and content hashing
41
42
**Usage Example:**
43
44
```typescript
45
import generateConfig from "@jupyterlab/builder/lib/extensionConfig";
46
import * as webpack from "webpack";
47
48
// Generate configuration for an extension
49
const configs = generateConfig({
50
packagePath: "/path/to/my-extension",
51
corePath: "/path/to/@jupyterlab/application",
52
mode: "production",
53
staticUrl: "https://cdn.example.com/static"
54
});
55
56
// Compile with webpack
57
const compiler = webpack(configs);
58
compiler.run((err, stats) => {
59
if (err) console.error(err);
60
console.log(stats.toString());
61
});
62
```
63
64
## Configuration Features
65
66
### Module Federation Integration
67
68
The generator creates Module Federation configurations that:
69
70
- **Expose Extension Points**: Automatically exposes `./extension` and `./mimeExtension` based on package.json
71
- **Share Dependencies**: Configures shared packages with version constraints
72
- **Singleton Management**: Ensures core packages are singletons to prevent conflicts
73
- **Dynamic Loading**: Enables runtime loading with `remoteEntry.[contenthash].js`
74
75
### Shared Dependency Management
76
77
The system intelligently manages shared dependencies by:
78
79
1. **Core Package Analysis**: Reads dependencies from core JupyterLab packages
80
2. **Version Compatibility**: Converts `~` to `^` for forward compatibility
81
3. **Singleton Configuration**: Marks critical packages as singletons
82
4. **Bundle Optimization**: Allows extensions to specify bundling preferences
83
84
```typescript
85
// Example shared dependency configuration
86
const shared = {
87
"@jupyterlab/application": {
88
requiredVersion: "^4.4.7",
89
singleton: true,
90
import: false // Don't bundle, use shared instance
91
},
92
"react": {
93
requiredVersion: "^18.0.0",
94
singleton: true
95
}
96
};
97
```
98
99
### Asset Processing Pipeline
100
101
The configuration includes comprehensive asset handling:
102
103
1. **Schema Processing**: Copies and validates JSON schemas
104
2. **Theme Assets**: Processes CSS and theme files through webpack
105
3. **Static Assets**: Handles fonts, images, and other static resources
106
4. **Style Integration**: Generates consolidated style imports
107
108
### Development vs Production Modes
109
110
#### Development Mode Features:
111
- Source map generation for debugging
112
- Build logging with detailed configuration output
113
- Watch mode optimizations
114
- Unminified output for easier debugging
115
116
#### Production Mode Features:
117
- Content hashing for cache busting
118
- License report generation
119
- Code minification and optimization
120
- Versioned static assets
121
122
**Mode-Specific Configuration:**
123
124
```typescript
125
// Development configuration
126
const devConfig = generateConfig({
127
packagePath: "./",
128
mode: "development",
129
devtool: "source-map",
130
watchMode: true
131
});
132
133
// Production configuration
134
const prodConfig = generateConfig({
135
packagePath: "./",
136
mode: "production",
137
staticUrl: "https://cdn.example.com"
138
});
139
```
140
141
## Advanced Configuration Options
142
143
### Custom Webpack Configuration
144
145
Extensions can provide custom webpack configurations that are merged with the generated configuration:
146
147
```typescript
148
// In package.json
149
{
150
"jupyterlab": {
151
"webpackConfig": "./webpack.config.js"
152
}
153
}
154
```
155
156
The custom configuration is merged using `webpack-merge` after the base configuration is generated.
157
158
### Shared Package Customization
159
160
Extensions can customize shared package behavior:
161
162
```typescript
163
// In package.json
164
{
165
"jupyterlab": {
166
"sharedPackages": {
167
"lodash": {
168
"bundled": false, // Don't bundle, use shared
169
"singleton": true
170
},
171
"moment": false // Exclude from sharing entirely
172
}
173
}
174
}
175
```
176
177
### Output Directory Control
178
179
The system respects the `outputDir` setting in package.json:
180
181
```typescript
182
// In package.json
183
{
184
"jupyterlab": {
185
"outputDir": "dist"
186
}
187
}
188
```
189
190
## Integration with Build Pipeline
191
192
The extension configuration integrates with the broader build system:
193
194
1. **Asset Coordination**: Works with `Build.ensureAssets()` for asset management
195
2. **Plugin Integration**: Includes custom webpack plugins for JupyterLab-specific tasks
196
3. **Metadata Validation**: Uses JSON schema validation for extension metadata
197
4. **Cleanup Management**: Handles old asset cleanup and metadata updates
198
199
The generated configurations return an array that can be concatenated with theme configurations from the build utilities for a complete build pipeline.