{"id":9031,"library":"hatch-jupyter-builder","title":"Hatch Jupyter Builder Plugin","description":"Hatch Jupyter Builder is a Hatch plugin designed to streamline the building and packaging of Jupyter-related projects, such as JupyterLab extensions, JupyterLite applications, and kernels. It integrates frontend build steps (e.g., npm/yarn) directly into the Python packaging process, ensuring consistent builds and proper inclusion of static assets. The current version is 0.9.1, with a release cadence of regular patch and minor updates addressing bug fixes and enhancements.","status":"active","version":"0.9.1","language":"en","source_language":"en","source_url":"https://github.com/jupyterlab/hatch-jupyter-builder","tags":["jupyter","hatch","build-system","packaging","plugin","frontend","npm","yarn"],"install":[{"cmd":"pip install hatch hatch-jupyter-builder","lang":"bash","label":"Install Hatch and the plugin"}],"dependencies":[{"reason":"Hatch is the core build tool and ecosystem for which this is a plugin.","package":"hatch","optional":false},{"reason":"Often required for building JavaScript/TypeScript frontends if used with the 'npm' option.","package":"npm","optional":true},{"reason":"Often required for building JavaScript/TypeScript frontends if used with the 'yarn' option.","package":"yarn","optional":true}],"imports":[{"note":"Users enable and configure `hatch-jupyter-builder` by adding it to `build-system.requires` and defining options under `[tool.hatch.build.targets.wheel]` and `[tool.hatch.build.hooks.jupyter]`.","symbol":"Configuration","correct":"This plugin is primarily configured via `pyproject.toml`, not typically imported directly in Python code."}],"quickstart":{"code":"# pyproject.toml\n[build-system]\nrequires = [\"hatchling>=1.5\", \"hatch-jupyter-builder>=0.9.0\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"my-jupyter-pkg\"\nversion = \"0.1.0\"\nrequires-python = \">=3.8\"\ndescription = \"A Jupyter package built with hatch-jupyter-builder.\"\n\n[tool.hatch.build.targets.wheel]\nbuilder = \"jupyter\"\n\n[tool.hatch.build.hooks.jupyter]\n# Directory containing package.json for frontend (relative to pyproject.toml)\nbuild-dir = \"js\"\n# Commands to run for frontend build\nnpm = [\"install\", \"run\", \"build\"]\n# Files that must exist after the frontend build to indicate success\n# ensured-targets = [\n#     \"my_jupyter_pkg/static/main.js\"\n# ]\n","lang":"toml","description":"This `pyproject.toml` snippet demonstrates how to configure `hatch-jupyter-builder` for a project that includes a JavaScript/TypeScript frontend. It enables the 'jupyter' builder for wheel targets and defines a `jupyter` build hook to execute `npm` commands within a specified `build-dir`."},"warnings":[{"fix":"Refer to the `hatch-jupyter-builder` official documentation and examples for the equivalent `pyproject.toml` configuration tailored to your project's specific build requirements.","message":"When migrating from older build systems like `jupyter_packaging` or manual `setup.py` scripts, `hatch-jupyter-builder` requires a complete re-evaluation of your `pyproject.toml` configuration. Direct translation of options is not always straightforward, especially for build hooks and asset inclusion.","severity":"breaking","affected_versions":"all versions"},{"fix":"Carefully review your `pyproject.toml` file, paying close attention to the `[tool.hatch.build.hooks.jupyter]` section. Verify that all paths (e.g., `build-dir`, `ensured-targets`) are correct relative to your `pyproject.toml` and that the specified frontend commands execute successfully in isolation.","message":"If your frontend assets are not being built or included in the final package, ensure that `builder = 'jupyter'` is correctly specified under `[tool.hatch.build.targets.wheel]` (and `sdist` if desired) and that `[tool.hatch.build.hooks.jupyter]` contains the correct `build-dir`, `npm` (or `yarn`) commands, and `ensured-targets` paths.","severity":"gotcha","affected_versions":"all versions"},{"fix":"Upgrade `hatch-jupyter-builder` to version 0.8.0 or newer to utilize `optional-editable-build`. If upgrading is not possible, remove this option from your `pyproject.toml` configuration.","message":"The `optional-editable-build` feature, which can significantly improve local development workflows by avoiding unnecessary frontend rebuilds, was introduced in `hatch-jupyter-builder` version 0.8.0. Projects attempting to use this option with older plugin versions will encounter build failures.","severity":"gotcha","affected_versions":"<0.8.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you have installed the plugin (`pip install hatch-jupyter-builder`) and added `\"hatch-jupyter-builder\"` to `build-system.requires` in your `pyproject.toml`.","cause":"The `hatch-jupyter-builder` plugin is either not installed or not listed in the `build-system.requires` array in your `pyproject.toml`.","error":"ERROR: No such builder: jupyter"},{"fix":"Install Hatch: `pip install hatch`.","cause":"The core `hatch` build tool is not installed in your environment.","error":"ModuleNotFoundError: No module named 'hatch'"},{"fix":"Check the output of your `npm` (or `yarn`) commands for errors. Verify that the `build-dir` and `ensured-targets` paths in your `pyproject.toml` correctly point to the location where the frontend assets are generated relative to the project root.","cause":"A file specified in `ensured-targets` within `[tool.hatch.build.hooks.jupyter]` was not found after the frontend build commands completed. This indicates either the build failed, the file was not generated, or the path in `ensured-targets` is incorrect.","error":"[ERROR] Target 'path/to/expected/file.js' was not found after build."}]}