jl-forge 0.4.0

Package version: 0.4.0

Build steps for JupyterLite sites — turn a Python project and its notebooks into version-matched, pruned and fully offline xeus-python or Pyodide sites, sized for GitHub or GitLab Pages.

Quick Start

jl-forge runs on the build machine (macOS or Linux), from a project's own build script. Pick a kernel, and install jl-forge in the build environment, next to jupyterlite-core and the kernel, not with pipx or uv tool: pyodide-dist reads the Pyodide version from the installed kernel, and the xeus commands import jupyterlite-xeus and empack. In a uv project, uv add --dev does it.

Pyodide site: project wheel via piplite, bundled wheels, self-hosted and pruned Pyodide.

pip install jl-forge jupyterlite-core jupyterlite-pyodide-kernel

jl-forge clean workspace                          # rm -rf, refused outside the cwd
jl-forge notebooks workspace/content --strip      # clear code cell outputs
jl-forge pyodide-install --pyproject pyproject.toml --package-name mypkg --wheel-dir workspace/content
jl-forge notebooks workspace/content --pyodide-install
jl-forge pyodide-wheels --pyproject pyproject.toml --out-dir workspace/lite/pypi
jupyter lite build --contents workspace/content --output-dir workspace/public --lite-dir workspace/lite \
  --pyodide "$(jl-forge pyodide-dist --pyproject pyproject.toml --out workspace/pyodide.tar.bz2)"

xeus-python site: cached conda environment, packed without build-only files, project mounted from source. Also needs micromamba.

pip install 'jl-forge[xeus]' jupyterlite-core     # the extra adds jupyterlite-xeus

jl-forge clean workspace
jl-forge notebooks workspace/content --strip
PREFIX=$(jl-forge xeus-env --micromamba --cache-dir ~/.cache/jl-forge/xeus --pyproject pyproject.toml)
jupyter lite build --contents workspace/content --output-dir workspace/public \
  --XeusAddon.prefix="$PREFIX" \
  --XeusAddon.empack_config="$(jl-forge xeus-pack-config --out workspace/empack.yml)" \
  --XeusAddon.mounts="$(jl-forge xeus-mount src/mypkg --prefix "$PREFIX")"

After either build: no request to other hosts, shared files stored once, within Pages limits.

jl-forge self-host workspace/public
jl-forge dedup workspace/public
jl-forge size workspace/public --max 1G
jl-forge urls workspace/public                    # serve command and notebook URLs

Building both sites needs one environment per kernel, as examples/demo/build.sh does: jupyter lite build copies every installed labextension.

Features

• Either kernel: xeus-python (conda prefix, source mount) or Pyodide (wheel + piplite install.py)
• One dependency list: kernel packages come from [project.dependencies] and extras in pyproject.toml
• Correct dependency handling: names normalized, duplicate constraints intersected, markers evaluated for emscripten
• Notebook preparation: strip outputs of code cells only; idempotent install line for Pyodide
• No hard-coded Python version: xeus mount paths follow the Python installed in the prefix
• Voici dashboards: demo and docs for either kernel; jl-forge urls lists the dashboard pages
• Self-hosting: Pyodide pruned to the packages the site uses (pyodide-dist, 23 MB instead of 340 MB), the wheels piplite installs (pyodide-wheels), and the files xeus and Voici fetch from other hosts (self-host): no request leaves the site
• Pages size limits: dedup hardlinks the files sites share, size fails the build above a limit
• Smaller, faster xeus builds: environments packed without build-only files (half the size) and reused between builds
• Safe workspace reset: clean refuses directories outside the project or that look like a project

What is jl-forge?

jl-forge is a small library and CLI extracted from the JupyterLite builds of several projects. It automates the steps around jupyter lite build that JupyterLite's offline guide leaves manual, and that each project used to script by hand:

• Version matching: the self-hosted Pyodide is the release the installed kernel loads.
• Pruning: Pyodide's 340 MB distribution cut to the packages the site uses, with their dependencies; xeus environments packed without build-only files.
• A complete wheel set: the PyPI packages piplite would fetch, with their dependencies, bundled into the site.
• No external requests: also the files xeus and Voici load from other hosts, which the guide doesn't mention; the demo's browser smoke test shows how to verify it.
• Either kernel, with cached xeus environments and size checks for GitHub or GitLab Pages.

A Python API (jl_forge.dependencies, notebooks, xeus, pyodide, wheels, selfhost, artifact) sits behind the CLI.

jl-forge is not a replacement for JupyterLite's build system. Your build script still calls jupyter lite build, chooses the apps, and handles application-specific assets.

Related projects

Best suited for: projects publishing a Python package with notebooks as a static JupyterLite site.

Note: jl-forge runs on the build machine (macOS or Linux). It installs nothing in the browser itself; see docs/RUNTIME.md.

Feedback and Contributions

jl-forge is an early-stage project. Feedback is particularly welcome on:

• Build steps worth sharing that are still scripted per project.
• JupyterLite, jupyterlite-xeus or Pyodide kernel changes that break the build.
• Support for other apps (Voici, Notebook) and hosting targets.

Please share suggestions, bug reports, and use cases through GitHub Issues.

AI-Assisted Development

Parts of this project were developed with the assistance of generative AI tools. The maintainer is responsible for the architecture, review, testing, and published code.

AI-assisted contributions are welcome, provided contributors understand, review, and test their changes and take responsibility for their submissions.

Documentation

• Getting Started - Development setup, testing, demo build and release
• Usage Guide - CLI reference, Python API, compatibility guarantees and a complete build script
• Apps, Kernels & Version Constraints - Lab, Notebook and Voici on xeus-python and Pyodide: what works, pinned versions and why
• Runtime & Integration - What runs where, and integration boundaries

Example Output

The demo site below is not the tool: it is what jl-forge builds. CI runs examples/demo/build.sh on one notebook and deploys both sites to GitHub Pages. They load nothing from other hosts, the Pyodide site ships a 23 MB pruned distribution, and the notebook reports which kernel runs it.

• xeus-python site — jl_forge_demo mounted from source into the conda prefix.
• Pyodide site — jl_forge_demo installed from its wheel by the generated install.py.
• Voici dashboards — the same notebook as an app: xeus-python, Pyodide.

How It Works

┌───────────────────────────────────────────┐
│ pyproject.toml          notebooks/*.ipynb │
└──────┬──────────────────────────┬─────────┘
       │ jl-forge                 │ jl-forge notebooks
┌──────▼────────────────┐ ┌───────▼──────────────────┐
│ xeus-env / xeus-mount │ │ pyodide-install          │
│ conda prefix (wasm)   │ │ wheel + install.py       │
└──────┬────────────────┘ └───────┬──────────────────┘
       │ jupyter lite build       │ jupyter lite build
┌──────▼────────────────┐ ┌───────▼──────────────────┐
│ public/xeus/          │ │ public/pyodide/          │
└───────────────────────┘ └──────────────────────────┘
               static site → GitHub Pages

License

Apache License 2.0. See LICENSE and NOTICE for details.

Citation

@software{jlforge2026,
  author = {Decitre, Emmanuel},
  title = {jl-forge: Build tooling for JupyterLite sites},
  year = {2026},
  url = {https://github.com/decitre/jl-forge}
}

Acknowledgements

jl-forge builds on several open-source projects:

• JupyterLite — the browser-based Jupyter environment.
• xeus-python, jupyterlite-xeus and emscripten-forge — Python kernels and packages for the browser.
• Pyodide and jupyterlite-pyodide-kernel.