Registry / devops / hatch-nodejs-version

hatch-nodejs-version

library0.4.0pypypiunverified

hatch-nodejs-version is an active Hatch plugin, currently at version 0.4.0, that facilitates Python project versioning by integrating with Node.js `package.json` files. It provides two main functionalities: a version source plugin that reads and writes the package version from the `version` field of `package.json`, and a metadata hook plugin that reads PEP 621 metadata from the same file. The project sees regular updates, addressing enhancements and bug fixes.

devops serialization

pip install hatch-nodejs-version

github ↗package ↗

INSTALL

IMPORT

SIG · HATCH-NODEJS-VERSI

hatch-nodejs-version

devopspythonv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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." }

Debug

Known issues

gotchaThe 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`.

affects: All versions

breakingThe `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`.

affects: All versions

gotchaVersions 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.

affects: <0.3.2

Errors

Common errors & fixes

Plugin 'nodejs' not found for version source

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'

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.

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`.

Upgrade

Version history

0.4.0latest on PyPI · released Jul 24, 2025

Audit

Dependencies

hatchrequiredThis is a Hatch plugin and requires Hatch (and its build backend, hatchling) to function. hatchling must be in `build-system.requires`.

nodejsrequiredThe plugin interacts with `package.json` files, which are part of Node.js projects. Node.js itself is not a Python dependency but is implicitly required for the plugin's core functionality.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/agoose77/hatch-nodejs-version ↗

packagehttps://pypi.org/project/hatch-nodejs-version/ ↗