Jupyter Builder

Build tools for JupyterLab extensions — extracted from the core JupyterLab codebase to be maintained and used independently.

Installation

pip install jupyter_builder

CLI

build

Compile the extension JavaScript assets for consumption by a Jupyter app.

jupyter-builder build <path/to/extension>

develop

Install extension assets in development mode (analogous to pip install -e). Uses a symlink by default.

jupyter-builder develop <path/to/extension>

watch

Automatically rebuild development assets when source files change.

jupyter-builder watch <path/to/extension>

For advanced configuration, see the Advanced section for available flags.

jlpm

jupyter-builder ships jlpm, a Jupyter-aware Node.js package manager wrapper:

jlpm install
jlpm build

Advanced

CLI flags

build

Flag	Description
--development	Build in development mode (default: False)
--source-map	Generate source maps (default: False)
--static-url=<url>	Set the URL for static assets
--core-version=<version>	JupyterLab core version to build against
--core-package-file=<path>	Path to a core application package.json (overrides --core-version)

develop

Flag	Description
--overwrite	Overwrite existing files
--user	Install to the user's directory
--sys-prefix	Install under sys.prefix (default: True)
--labextensions-dir=<path>	Install to a custom labextensions directory

watch

Flag	Description
--development	Build in development mode (default: True)
--source-map	Generate source maps (default: False)
--core-version=<version>	JupyterLab core version to build against
--core-package-file=<path>	Path to a core application package.json (overrides --core-version)

Python API

from jupyter_builder.federated_extensions import (
    build_labextension,
    develop_labextension_py,
    watch_labextension,
)

build_labextension(
    "/path/to/extension",
    development=False,
    source_map=False,
    static_url=None,
    core_version=None,
    core_package_file=None,
)

develop_labextension_py(
    "/path/to/extension",
    overwrite=True,
    symlink=True,
    user=False,
    sys_prefix=True,
)

watch_labextension(
    "/path/to/extension",
    labextensions_path=[...],
    development=True,
    source_map=False,
)

Environment variables

jupyter-builder supports the following environment variables to override network URLs — for example, to point at an internal mirror or a local proxy. A warning is emitted at startup whenever a variable is set.

Variable	Default	Purpose
JPBLD_NPM_URL	https://registry.npmjs.org	npm registry used to resolve and download @jupyterlab/core-meta
JPBLD_RAW_GITHUB_URL	https://raw.githubusercontent.com	Raw GitHub content URL used as a fallback when npm is unavailable

Example — redirect to a corporate npm mirror:

export JPBLD_NPM_URL=https://npm.internal.example.com
jupyter-builder build /path/to/extension

Core metadata resolution order

When no explicit --core-version is given, jupyter-builder looks for @jupyterlab/core-meta in the extension's node_modules first (no network required). If the package is not found there a warning is printed and the metadata is fetched from the npm registry, falling back to raw GitHub if npm is unreachable.

Uninstall

pip uninstall jupyter_builder

Credits

This package was initially created during GSoC 2024 by @cronan03, mentored by @fcollonval.