jl-forge

Package version: 0.2.0

Build steps for JupyterLite sites — turn a Python project and its notebooks into xeus-python and Pyodide sites, ready for GitHub Pages.

Quick Start

Try the demo online (no installation required):

• Launch with xeus-python
• Launch with Pyodide

Basic usage, from a project's own build script:

jl-forge clean workspace                      # rm -rf, refused outside the cwd
jl-forge notebooks workspace/content --strip  # clear code cell outputs

# xeus-python kernel (needs micromamba)
jl-forge xeus-env --micromamba --root-prefix workspace/xeus --pyproject pyproject.toml
jupyter lite build --contents workspace/content \
  --XeusAddon.prefix=workspace/xeus/envs/xeus-kernels \
  --XeusAddon.mounts="$(jl-forge xeus-mount src/mypkg --prefix workspace/xeus/envs/xeus-kernels)"

# Pyodide kernel: install the project wheel via piplite
jl-forge pyodide-install --pyproject pyproject.toml --package-name mypkg --wheel-dir workspace/content
jl-forge notebooks workspace/content --pyodide-install

# after jupyter lite build: serve command and notebook URLs
jl-forge urls workspace/public

Features

• Both kernels: xeus-python (conda prefix, source mount) and 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 both kernels; jl-forge urls lists the dashboard pages
• 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 provides:

• The steps around jupyter lite build that each project used to script by hand
• A Python API (jl_forge.dependencies, notebooks, xeus, pyodide) 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.

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 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
• Glossary - Key concepts and terminology

Interactive Notebooks

The demo builds one notebook into both sites; it reports which kernel runs it.

• xeus-python demo — jl_forge_demo mounted from source into the conda prefix.
• Pyodide demo — 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.