Hatch Node.js Version Plugin

Common errors

• Plugin 'nodejs' not found for version source

  cause The `hatch-nodejs-version` plugin was not correctly installed or declared in `pyproject.toml`'s `build-system.requires` section, or Hatch itself is not installed/accessible.
  fix Verify that `pip install hatch-nodejs-version` has been run and that `"hatch-nodejs-version"` is included in `build-system.requires` in your `pyproject.toml`.

• No 'package.json' file found at expected path: './package.json'

  cause The `package.json` file is either missing from the project root or the `path` option in `[tool.hatch.version]` (or `[tool.hatch.metadata.hooks.nodejs]`) in `pyproject.toml` is incorrect.
  fix Ensure `package.json` exists in your project, or set the correct `path` (e.g., `path = "./frontend/package.json"`) in your `pyproject.toml` configuration.

• The version string in package.json does not conform to PEP 440 compatible format.

  cause The version in your `package.json` includes unsupported elements according to PEP 440, such as build metadata (e.g., `+build123`).
  fix Modify the `version` field in `package.json` to adhere to the major.minor.patch.pre-release.dev-release format, removing any build metadata. For example, change `1.0.0+build.1` to `1.0.0` or `1.0.0-beta.1`.

Warnings

• gotcha The plugin enforces a specific subset of Semantic Versioning (major.minor.patch.pre-release.dev-release) to ensure compatibility between Node.js and PEP 440. Build metadata (e.g., `1.0.0+build123`) in `package.json` is not accepted and will cause errors during version synchronization due to PEP 440's stricter format.
  Fix: Ensure your `package.json` version string adheres to major.minor.patch[-pre-release][.dev-release] format, avoiding build metadata. For example, use `1.2.3-rc.0` instead of `1.2.3+build.1`.
• breaking The `hatch-nodejs-version` package must be explicitly listed in the `build-system.requires` section of your `pyproject.toml` file. Failing to do so will result in Hatch not being able to find or utilize the plugin for versioning or metadata hooks.
  Fix: Add `"hatch-nodejs-version"` to the `requires` array under `[build-system]` in your `pyproject.toml`.
• gotcha Versions prior to `0.3.2` had a bug that could lead to missing trailing newlines in `package.json` when the plugin wrote back to the file. This could cause issues with some linters or version control systems.
  Fix: Upgrade to version `0.3.2` or newer to ensure `package.json` files maintain correct formatting upon modification.

Install

• pip install hatch-nodejs-version Install stable version

Quickstart

To use `hatch-nodejs-version`, you must first declare it in your `pyproject.toml` under `[build-system].requires`. Then, configure the version source by setting `[tool.hatch.version].source` to `nodejs`. You can optionally specify the `path` to your `package.json` if it's not in the project root. Additionally, the metadata hook can be configured under `[tool.hatch.metadata.hooks.nodejs]` to sync fields like name or description from `package.json` to your Python project's metadata.

# pyproject.toml
[build-system]
requires = ["hatchling", "hatch-nodejs-version"]
build-backend = "hatchling.build"

[tool.hatch.version]
source = "nodejs"
path = "./frontend/package.json" # Optional: if package.json is not in the project root

[tool.hatch.metadata.hooks.nodejs] # Optional: to sync other metadata
fields = ["name", "description"] # Optional: fields to sync

# package.json (example)
{
  "name": "my-package",
  "version": "1.2.3",
  "description": "A simple Node.js package."
}