---
id: hatch-nodejs-version
version: "0.4.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# hatch-nodejs-version — Hatch plugin for versioning from a package.json file

License: permissive · Maintenance: aging · Downloads: 204.9K/mo

## What it is and what it does

This is a Hatch build plugin that bridges Python and Node.js packaging by reading version and metadata from a package.json file instead of requiring them to be duplicated in pyproject.toml. It provides two plugins: a version-source plugin that treats package.json as the single source of truth for version numbers, and a metadata-hook plugin that populates Python package metadata (author, description, URLs) from corresponding fields in package.json.

The plugin is designed for projects that maintain both Python and Node.js distributions or that want to keep version information in a single place. It handles conversion between semantic versioning (used by Node.js) and PEP 440 (Python's versioning standard), accepting only the common subset: major, minor, patch, pre-release, and dev-release components. The version-source plugin supports round-trip consistency, meaning versions can be read from and written back to package.json without loss of information, provided delimiters are chosen carefully.

Use it for:

- Maintain a single version number in package.json for a project that publishes both Python and Node.js packages.
- Automatically populate Python package metadata (author, repository, homepage) from an existing package.json without manual duplication.
- Ensure version consistency across Python and Node.js distributions during CI/CD builds.
- Migrate a Node.js project to Python packaging while keeping version management in the familiar package.json format.
- Use package.json as the canonical metadata source for monorepo or polyglot projects.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides Hatch plugins to read and write Python package version and metadata from a Node.js package.json file, enabling version-source and metadata-hook integration.

Yes, if you maintain both Python and Node.js distributions or want to keep version and metadata in package.json as a single source of truth. The plugin has low install friction, permissive licensing, and no known vulnerabilities. The aging maintenance status (386 days since last release) is not a blocker—the package is stable and the repository remains active—but verify that your version format and metadata fields align with the plugin's supported subset before adopting it.

## Install

pip install hatch-nodejs-version
uv add hatch-nodejs-version
poetry add hatch-nodejs-version

## Installing hatch-nodejs-version

Before you install: Low install friction with a single runtime dependency on hatchling. The package is aging (386 days since last release) but remains actively maintained with recent commits; supports current Python versions 3.9–3.13.

License in practice: MIT license is permissive and imposes no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

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

[tool.hatch.version]
source = "nodejs"

# Then hatch reads version from package.json automatically during build

Requires a package.json file in the project root (or at a configured path) with a version field; only accepts semver versions compatible with PEP 440 (major.minor.patch[-pre-release][-dev-release]).

Verify before relying:

- Whether the metadata hook correctly handles all PEP 621 fields when reading from package.json, or only a subset.
- Performance impact of metadata hook on build time for large package.json files.
- Compatibility with monorepo setups where package.json may be in a non-standard location.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 204.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

hatch version from package.json, nodejs package.json version plugin, hatch metadata hook nodejs, sync python version with node, package.json version source hatch, cross-language version management, hatch build plugin nodejs, hatch-plugin, version-management, nodejs-integration

[View on SkillFed](https://skillfed.io/packages/hatch-nodejs-version) · [View on PyPI](https://pypi.org/project/hatch-nodejs-version/)