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

Build Utilities

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

Core build functionality for managing JupyterLab extension assets, including schema copying, theme processing, CSS import generation, and extension metadata normalization.

Capabilities

Asset Management

Ensures that extension packages have their assets (schemas, themes, styles) properly copied and configured for the build process.

/**
 * Ensures that the assets of plugin packages are populated for a build
 * @param options - Configuration options for asset management
 * @returns Array of webpack configuration objects for theme processing
 */
function Build.ensureAssets(options: Build.IEnsureOptions): webpack.Configuration[];

interface Build.IEnsureOptions {
  /** The output directory where the build assets should reside */
  output: string;
  /** The directory for the schema directory, defaults to the output directory */
  schemaOutput?: string;
  /** The directory for the theme directory, defaults to the output directory */
  themeOutput?: string;
  /** The names of the packages to ensure */
  packageNames: ReadonlyArray<string>;
  /** The package paths to ensure */
  packagePaths?: ReadonlyArray<string>;
}

The ensureAssets function performs several key operations:

Schema Processing: Copies schema files from extension packages to the designated schema output directory
Theme Configuration: Creates webpack configurations for theme CSS processing and extraction
Style Import Generation: Generates a consolidated style.js file with imports for all extension stylesheets
Asset Resolution: Resolves package paths and validates package metadata

Usage Example:

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

// Ensure assets for multiple extensions
const themeConfigs = Build.ensureAssets({
  output: "./build",
  schemaOutput: "./build/schemas", 
  themeOutput: "./build/themes",
  packageNames: [
    "@jupyterlab/notebook",
    "@jupyterlab/fileeditor",
    "@my-org/custom-extension"
  ]
});

// The returned configurations can be used with webpack
import * as webpack from "webpack";
const compiler = webpack(themeConfigs);

Extension Metadata Normalization

Extracts and normalizes JupyterLab extension metadata from package.json files.

/**
 * Returns JupyterLab extension metadata from a module
 * @param module - Module definition containing package.json data
 * @returns Normalized extension metadata
 * @throws Error if module does not contain JupyterLab metadata
 */
function Build.normalizeExtension(module: Build.IModule): Build.ILabExtension;

interface Build.IModule {
  /** The JupyterLab metadata */
  jupyterlab?: Build.ILabExtension;
  /** The main entry point in a module */
  main?: string;
  /** The name of a module */
  name: string;
}

interface Build.ILabExtension {
  /** 
   * Indicates whether the extension is a standalone extension.
   * If true, uses the main export. If string, uses that path as entry point.
   */
  readonly extension?: boolean | string;
  /** 
   * Indicates whether the extension is a MIME renderer extension.
   * If true, uses the main export. If string, uses that path as entry point.
   */
  readonly mimeExtension?: boolean | string;
  /** The local schema file path in the extension package */
  readonly schemaDir?: string;
  /** The local theme file path in the extension package */
  readonly themePath?: string;
}

The normalizeExtension function:

Entry Point Resolution: Resolves extension and mimeExtension entry points to actual file paths
Validation: Ensures extension and mimeExtension don't point to the same export
Default Handling: Uses main field as default when extension/mimeExtension is true
Error Handling: Throws descriptive errors for invalid configurations

Usage Example:

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

// Normalize extension metadata from package.json
const moduleData = {
  name: "@my-org/my-extension",
  main: "lib/index.js",
  jupyterlab: {
    extension: true,
    schemaDir: "schema",
    themePath: "style/index.css"
  }
};

const normalized = Build.normalizeExtension(moduleData);
// Result: {
//   extension: "lib/index.js",
//   mimeExtension: undefined,
//   schemaDir: "schema", 
//   themePath: "style/index.css"
// }