0
# CLI Tool
1
2
Command-line interface for building JupyterLab extensions with development and production modes, watch functionality, and source map generation.
3
4
## Usage
5
6
```bash
7
build-labextension [options] <extensionPath>
8
```
9
10
The `build-labextension` command provides a complete command-line interface for building JupyterLab extensions without requiring custom webpack configuration.
11
12
## Command Options
13
14
```bash { .api }
15
build-labextension [options] <extensionPath>
16
17
Options:
18
--development build in development mode (implies --source-map)
19
--source-map generate source maps
20
--core-path <path> the core package directory (required)
21
--static-url <url> url for build assets, if hosted outside the built extension
22
--watch enable watch mode for continuous building
23
-h, --help display help for command
24
```
25
26
### Required Arguments
27
28
- `<extensionPath>` - Path to the extension package directory to build
29
30
### Required Options
31
32
- `--core-path <path>` - Path to the core JupyterLab package directory (typically `@jupyterlab/application`)
33
34
### Optional Flags
35
36
- `--development` - Build in development mode with unminified output and source maps
37
- `--source-map` - Generate source maps for debugging (automatically enabled in development mode)
38
- `--watch` - Enable watch mode for continuous rebuilding on file changes
39
- `--static-url <url>` - Specify URL for build assets when hosted outside the extension
40
41
## Usage Examples
42
43
### Basic Production Build
44
45
```bash
46
build-labextension ./my-extension --core-path ./node_modules/@jupyterlab/application
47
```
48
49
### Development Build with Watch Mode
50
51
```bash
52
build-labextension ./my-extension \
53
--core-path ./node_modules/@jupyterlab/application \
54
--development \
55
--watch
56
```
57
58
### Build with Custom Static URL
59
60
```bash
61
build-labextension ./my-extension \
62
--core-path ./node_modules/@jupyterlab/application \
63
--static-url https://cdn.example.com/static
64
```
65
66
### Source Maps in Production
67
68
```bash
69
build-labextension ./my-extension \
70
--core-path ./node_modules/@jupyterlab/application \
71
--source-map
72
```
73
74
## Build Process
75
76
The CLI tool performs the following build steps:
77
78
1. **Path Resolution**: Resolves extension and core package paths to absolute paths
79
2. **Configuration Generation**: Uses the extension configuration generator with provided options
80
3. **Webpack Compilation**: Runs webpack with the generated configuration
81
4. **Asset Processing**: Handles schemas, themes, and static assets through the build pipeline
82
5. **Output Management**: Manages build artifacts and cleanup
83
84
## Build Modes
85
86
### Production Mode (Default)
87
88
Production builds include:
89
- Code minification and optimization
90
- Content hashing for cache busting
91
- License report generation
92
- Optimized asset processing
93
- Clean output directories
94
95
### Development Mode
96
97
Development builds provide:
98
- Unminified code for easier debugging
99
- Source map generation
100
- Detailed build logging
101
- Faster compilation times
102
- Build configuration logging to `build_log.json`
103
104
## Watch Mode
105
106
When `--watch` is enabled, the CLI provides:
107
108
- **Continuous Rebuilding**: Automatically rebuilds on file changes
109
- **Incremental Compilation**: Only rebuilds changed modules
110
- **Build Status**: Shows compilation start/finish notifications
111
- **Error Handling**: Continues watching even after build errors
112
- **Performance Optimization**: Uses efficient file watching strategies
113
114
**Watch Mode Output:**
115
116
```bash
117
webpack is watching the files…
118
119
Watch Compilation starting…
120
121
asset remoteEntry.abc123.js 245 KiB [emitted] [immutable] (name: main)
122
asset package.json 2.1 KiB [emitted]
123
124
Watch Compilation finished
125
```
126
127
## Error Handling
128
129
The CLI provides comprehensive error handling:
130
131
1. **Compilation Errors**: Displays webpack compilation errors with stack traces
132
2. **Configuration Errors**: Shows detailed information about configuration issues
133
3. **Exit Codes**: Returns appropriate exit codes for scripting (0 for success, 2 for errors)
134
4. **Watch Mode Resilience**: Continues watching after errors in watch mode
135
136
## Integration with Build Systems
137
138
### Package.json Scripts
139
140
```json
141
{
142
"scripts": {
143
"build": "build-labextension . --core-path ../application",
144
"build:dev": "build-labextension . --core-path ../application --development",
145
"watch": "build-labextension . --core-path ../application --watch"
146
}
147
}
148
```
149
150
### CI/CD Integration
151
152
The CLI is designed to work well in continuous integration environments:
153
154
```bash
155
# Install dependencies
156
npm install
157
158
# Build extension for production
159
build-labextension ./packages/my-extension \
160
--core-path ./packages/application
161
162
# Check exit code
163
if [ $? -eq 0 ]; then
164
echo "Build successful"
165
else
166
echo "Build failed"
167
exit 1
168
fi
169
```
170
171
### Monorepo Usage
172
173
For monorepo setups with multiple extensions:
174
175
```bash
176
# Build multiple extensions
177
for ext in packages/*; do
178
if [ -f "$ext/package.json" ]; then
179
build-labextension "$ext" --core-path packages/application
180
fi
181
done
182
```
183
184
## Output Structure
185
186
The CLI generates the following output structure:
187
188
```
189
extension-package/
190
├── lib/ # Compiled TypeScript output
191
├── [outputDir]/ # Build output (default: lib)
192
│ ├── static/ # Static assets
193
│ │ ├── remoteEntry.[hash].js
194
│ │ └── [other assets]
195
│ ├── schemas/ # JSON schemas
196
│ ├── themes/ # Theme CSS files
197
│ ├── package.json # Updated with build metadata
198
│ └── build_log.json # Development mode only
199
```
200
201
The `package.json` in the output directory is updated with build metadata including the generated `remoteEntry` file path and exposed module information.