CLI Tool

Command-line interface for building JupyterLab extensions with development and production modes, watch functionality, and source map generation.

Usage

build-labextension [options] <extensionPath>

The build-labextension command provides a complete command-line interface for building JupyterLab extensions without requiring custom webpack configuration.

Command Options

build-labextension [options] <extensionPath>

Options:
  --development              build in development mode (implies --source-map)
  --source-map              generate source maps
  --core-path <path>        the core package directory (required)
  --static-url <url>        url for build assets, if hosted outside the built extension
  --watch                   enable watch mode for continuous building
  -h, --help               display help for command

Required Arguments

• <extensionPath> - Path to the extension package directory to build

Required Options

• --core-path <path> - Path to the core JupyterLab package directory (typically @jupyterlab/application)

Optional Flags

• --development - Build in development mode with unminified output and source maps
• --source-map - Generate source maps for debugging (automatically enabled in development mode)
• --watch - Enable watch mode for continuous rebuilding on file changes
• --static-url <url> - Specify URL for build assets when hosted outside the extension

Usage Examples

Basic Production Build

build-labextension ./my-extension --core-path ./node_modules/@jupyterlab/application

Development Build with Watch Mode

build-labextension ./my-extension \
  --core-path ./node_modules/@jupyterlab/application \
  --development \
  --watch

Build with Custom Static URL

build-labextension ./my-extension \
  --core-path ./node_modules/@jupyterlab/application \
  --static-url https://cdn.example.com/static

Source Maps in Production

build-labextension ./my-extension \
  --core-path ./node_modules/@jupyterlab/application \
  --source-map

Build Process

The CLI tool performs the following build steps:

1. Path Resolution: Resolves extension and core package paths to absolute paths
2. Configuration Generation: Uses the extension configuration generator with provided options
3. Webpack Compilation: Runs webpack with the generated configuration
4. Asset Processing: Handles schemas, themes, and static assets through the build pipeline
5. Output Management: Manages build artifacts and cleanup

Build Modes

Production Mode (Default)

Production builds include:

• Code minification and optimization
• Content hashing for cache busting
• License report generation
• Optimized asset processing
• Clean output directories

Development Mode

Development builds provide:

• Unminified code for easier debugging
• Source map generation
• Detailed build logging
• Faster compilation times
• Build configuration logging to build_log.json

Watch Mode

When --watch is enabled, the CLI provides:

• Continuous Rebuilding: Automatically rebuilds on file changes
• Incremental Compilation: Only rebuilds changed modules
• Build Status: Shows compilation start/finish notifications
• Error Handling: Continues watching even after build errors
• Performance Optimization: Uses efficient file watching strategies

Watch Mode Output:

webpack is watching the files…

Watch Compilation starting…

asset remoteEntry.abc123.js 245 KiB [emitted] [immutable] (name: main)
asset package.json 2.1 KiB [emitted]

Watch Compilation finished

Error Handling

The CLI provides comprehensive error handling:

1. Compilation Errors: Displays webpack compilation errors with stack traces
2. Configuration Errors: Shows detailed information about configuration issues
3. Exit Codes: Returns appropriate exit codes for scripting (0 for success, 2 for errors)
4. Watch Mode Resilience: Continues watching after errors in watch mode

Integration with Build Systems

Package.json Scripts

{
  "scripts": {
    "build": "build-labextension . --core-path ../application",
    "build:dev": "build-labextension . --core-path ../application --development",
    "watch": "build-labextension . --core-path ../application --watch"
  }
}

CI/CD Integration

The CLI is designed to work well in continuous integration environments:

# Install dependencies
npm install

# Build extension for production
build-labextension ./packages/my-extension \
  --core-path ./packages/application

# Check exit code
if [ $? -eq 0 ]; then
  echo "Build successful"
else
  echo "Build failed"
  exit 1
fi

Monorepo Usage

For monorepo setups with multiple extensions:

# Build multiple extensions
for ext in packages/*; do
  if [ -f "$ext/package.json" ]; then
    build-labextension "$ext" --core-path packages/application
  fi
done

Output Structure

The CLI generates the following output structure:

extension-package/
├── lib/              # Compiled TypeScript output
├── [outputDir]/      # Build output (default: lib)
│   ├── static/       # Static assets
│   │   ├── remoteEntry.[hash].js
│   │   └── [other assets]
│   ├── schemas/      # JSON schemas
│   ├── themes/       # Theme CSS files
│   ├── package.json  # Updated with build metadata
│   └── build_log.json # Development mode only

The package.json in the output directory is updated with build metadata including the generated remoteEntry file path and exposed module information.