tessl/npm-jupyterlab--builder

JupyterLab extension builder providing webpack-based compilation and build tools for JupyterLab extensions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Webpack Plugins

Name: tessl/npm-jupyterlab--builder
Author: tessl

Custom webpack plugins designed specifically for JupyterLab extension building, including asset copying, license reporting, duplicate package detection, and watch mode optimizations.

Capabilities

Frontend Asset Plugin

Copies build assets from a build directory to a static directory, ensuring clean output on first run.

/**
 * A WebPack Plugin that copies the assets to the static directory
 */
class WPPlugin.FrontEndPlugin {
  constructor(buildDir: string, staticDir: string);
  apply(compiler: webpack.Compiler): void;
  
  readonly buildDir: string;
  readonly staticDir: string;
}

The FrontEndPlugin provides:

Clean Static Directory: Removes existing static directory on first emit
Asset Copying: Synchronously copies all assets from build to static directory
Incremental Updates: Only cleans on first run, preserves assets on subsequent builds

Usage Example:

import { WPPlugin } from "@jupyterlab/builder";
import * as webpack from "webpack";

const config = {
  plugins: [
    new WPPlugin.FrontEndPlugin("./dist", "./static")
  ]
};

const compiler = webpack(config);

JSON License Reporting Plugin

Creates comprehensive, machine-readable license reports for all bundled modules in SPDX-like format.

/**
 * A plugin that creates a predictable, machine-readable report of licenses for
 * all modules included in this build
 */
class WPPlugin.JSONLicenseWebpackPlugin extends LicenseWebpackPlugin {
  constructor(pluginOptions?: PluginOptions);
  renderLicensesJSON(modules: LicenseIdentifiedModule[]): string;
}

const WPPlugin.DEFAULT_LICENSE_REPORT_FILENAME: "third-party-licenses.json";

interface WPPlugin.ILicenseReport {
  packages: WPPlugin.IPackageLicenseInfo[];
}

interface WPPlugin.IPackageLicenseInfo {
  /** the name of the package as it appears in node_modules */
  name: string;
  /** the version of the package, or an empty string if unknown */
  versionInfo: string;
  /** an SPDX license or LicenseRef, or an empty string if unknown */
  licenseId: string;
  /** the verbatim extracted text of the license, or an empty string if unknown */
  extractedText: string;
}

The license plugin:

Comprehensive Reporting: Captures all bundled modules with license information
SPDX-Compatible: Uses SPDX-like format for license identification
Predictable Output: Always outputs to third-party-licenses.json
Sorted Results: Alphabetically sorts packages by name for consistency

Usage Example:

import { WPPlugin } from "@jupyterlab/builder";

const config = {
  plugins: [
    new WPPlugin.JSONLicenseWebpackPlugin({
      excludedPackageTest: packageName => packageName === "my-package"
    })
  ]
};

Watch Mode File Filtering Plugin

Ignores specific files during webpack watch mode based on a filter function, optimizing build performance.

/**
 * A WebPack Plugin that ignores files that are filtered
 * by a callback during a `--watch` build
 */
class WPPlugin.FilterWatchIgnorePlugin {
  constructor(ignored: (path: string) => boolean);
  apply(compiler: webpack.Compiler): void;
  
  readonly ignored: (path: string) => boolean;
}

The filter plugin provides:

Custom Filtering: Uses callback function to determine ignored files
Watch Optimization: Only affects watch mode, not regular builds
Path-Based Logic: Receives full file paths for filtering decisions

Usage Example:

import { WPPlugin } from "@jupyterlab/builder";

const config = {
  plugins: [
    new WPPlugin.FilterWatchIgnorePlugin(
      path => path.includes("node_modules") || path.endsWith(".test.js")
    )
  ]
};

Duplicate Package Checker Plugin

Extended version of the duplicate package checker plugin that only runs during non-watch builds to avoid performance issues.

/**
 * Extended duplicate package checker that only runs in non-watch mode
 */
class WPPlugin.NowatchDuplicatePackageCheckerPlugin extends DuplicatePackageCheckerPlugin {
  constructor(options: DuplicatePackageCheckerPlugin.Options);
  apply(compiler: webpack.Compiler): void;
  options: DuplicatePackageCheckerPlugin.Options;
}

This plugin addresses performance concerns by:

Watch Mode Skipping: Only runs during regular builds, not watch mode
Duplicate Detection: Identifies packages with multiple versions in the bundle
Build-Time Optimization: Prevents watch mode slowdowns from duplicate checking

Usage Example:

import { WPPlugin } from "@jupyterlab/builder";

const config = {
  plugins: [
    new WPPlugin.NowatchDuplicatePackageCheckerPlugin({
      verbose: true,
      emitError: false,
      showHelp: true
    })  
  ]
};

Plugin Integration Patterns

Production Build Configuration

For production builds, combine plugins for optimal output:

import { WPPlugin } from "@jupyterlab/builder";

const productionPlugins = [
  new WPPlugin.FrontEndPlugin("./build", "./static"),
  new WPPlugin.JSONLicenseWebpackPlugin({
    excludedPackageTest: packageName => packageName === myPackageName
  }),
  new WPPlugin.NowatchDuplicatePackageCheckerPlugin({
    emitError: true,
    strict: true
  })
];

Development Build Configuration

For development builds, focus on performance:

import { WPPlugin } from "@jupyterlab/builder";

const developmentPlugins = [
  new WPPlugin.FrontEndPlugin("./build", "./static"),
  new WPPlugin.FilterWatchIgnorePlugin(
    path => path.includes("node_modules") && !path.includes("@jupyterlab")
  )
];

License Report Format

The JSON license plugin generates reports in this structure:

{
  "packages": [
    {
      "name": "@jupyterlab/application",
      "versionInfo": "4.4.7",
      "licenseId": "BSD-3-Clause",
      "extractedText": "Copyright (c) 2015-2022, Jupyter Development Team..."
    }
  ]
}

This format is consumed by jupyterlab_server for license compliance and can be processed by other tools in the JupyterLab ecosystem.