Extension Configuration

Automated webpack configuration generation for JupyterLab extensions with module federation, shared dependencies, asset processing, and development/production optimizations.

Capabilities

Configuration Generation

Generates complete webpack configurations for building JupyterLab extensions with module federation and shared dependency management.

/**
 * Generates webpack configuration for JupyterLab extension building
 * @param options - Configuration options for the build
 * @returns Array of webpack configuration objects
 */
function generateConfig(options?: IOptions): webpack.Configuration[];

interface IOptions {
  /** Path to extension package directory */
  packagePath?: string;
  /** Path to core JupyterLab package directory */
  corePath?: string;
  /** URL for build assets if hosted outside the built extension */
  staticUrl?: string;
  /** Build mode: development or production */
  mode?: 'development' | 'production';
  /** Source map configuration */
  devtool?: string;
  /** Whether in watch mode */
  watchMode?: boolean;
}

The configuration generator provides:

1. Module Federation Setup: Configures webpack's Module Federation Plugin for extension isolation
2. Shared Dependencies: Manages shared packages between extensions and core JupyterLab
3. Asset Processing: Handles schemas, themes, and static assets
4. Development Optimizations: Source maps, build logging, and watch mode support
5. Production Optimizations: License reporting, minification, and content hashing

Usage Example:

import generateConfig from "@jupyterlab/builder/lib/extensionConfig";
import * as webpack from "webpack";

// Generate configuration for an extension
const configs = generateConfig({
  packagePath: "/path/to/my-extension",
  corePath: "/path/to/@jupyterlab/application",
  mode: "production",
  staticUrl: "https://cdn.example.com/static"
});

// Compile with webpack
const compiler = webpack(configs);
compiler.run((err, stats) => {
  if (err) console.error(err);
  console.log(stats.toString());
});

Configuration Features

Module Federation Integration

The generator creates Module Federation configurations that:

• Expose Extension Points: Automatically exposes ./extension and ./mimeExtension based on package.json
• Share Dependencies: Configures shared packages with version constraints
• Singleton Management: Ensures core packages are singletons to prevent conflicts
• Dynamic Loading: Enables runtime loading with remoteEntry.[contenthash].js

Shared Dependency Management

The system intelligently manages shared dependencies by:

1. Core Package Analysis: Reads dependencies from core JupyterLab packages
2. Version Compatibility: Converts ~ to ^ for forward compatibility
3. Singleton Configuration: Marks critical packages as singletons
4. Bundle Optimization: Allows extensions to specify bundling preferences

// Example shared dependency configuration
const shared = {
  "@jupyterlab/application": {
    requiredVersion: "^4.4.7",
    singleton: true,
    import: false  // Don't bundle, use shared instance
  },
  "react": {
    requiredVersion: "^18.0.0",
    singleton: true
  }
};

Asset Processing Pipeline

The configuration includes comprehensive asset handling:

1. Schema Processing: Copies and validates JSON schemas
2. Theme Assets: Processes CSS and theme files through webpack
3. Static Assets: Handles fonts, images, and other static resources
4. Style Integration: Generates consolidated style imports

Development vs Production Modes

Development Mode Features:

• Source map generation for debugging
• Build logging with detailed configuration output
• Watch mode optimizations
• Unminified output for easier debugging

Production Mode Features:

• Content hashing for cache busting
• License report generation
• Code minification and optimization
• Versioned static assets

Mode-Specific Configuration:

// Development configuration
const devConfig = generateConfig({
  packagePath: "./",
  mode: "development",
  devtool: "source-map",
  watchMode: true
});

// Production configuration  
const prodConfig = generateConfig({
  packagePath: "./",
  mode: "production",
  staticUrl: "https://cdn.example.com"
});

Advanced Configuration Options

Custom Webpack Configuration

Extensions can provide custom webpack configurations that are merged with the generated configuration:

// In package.json
{
  "jupyterlab": {
    "webpackConfig": "./webpack.config.js"
  }
}

The custom configuration is merged using webpack-merge after the base configuration is generated.

Shared Package Customization

Extensions can customize shared package behavior:

// In package.json
{
  "jupyterlab": {
    "sharedPackages": {
      "lodash": {
        "bundled": false,  // Don't bundle, use shared
        "singleton": true
      },
      "moment": false  // Exclude from sharing entirely
    }
  }
}

Output Directory Control

The system respects the outputDir setting in package.json:

// In package.json
{
  "jupyterlab": {
    "outputDir": "dist"
  }
}

Integration with Build Pipeline

The extension configuration integrates with the broader build system:

1. Asset Coordination: Works with Build.ensureAssets() for asset management
2. Plugin Integration: Includes custom webpack plugins for JupyterLab-specific tasks
3. Metadata Validation: Uses JSON schema validation for extension metadata
4. Cleanup Management: Handles old asset cleanup and metadata updates

The generated configurations return an array that can be concatenated with theme configurations from the build utilities for a complete build pipeline.