{"id":8213,"library":"hatch-nodejs-version","title":"Hatch Node.js Version Plugin","description":"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.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/agoose77/hatch-nodejs-version","tags":["hatch","plugin","versioning","nodejs","packaging","pyproject.toml"],"install":[{"cmd":"pip install hatch-nodejs-version","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This is a Hatch plugin and requires Hatch (and its build backend, hatchling) to function. hatchling must be in `build-system.requires`.","package":"hatch","optional":false},{"reason":"The 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.","package":"nodejs","optional":false}],"imports":[],"quickstart":{"code":"# pyproject.toml\n[build-system]\nrequires = [\"hatchling\", \"hatch-nodejs-version\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.version]\nsource = \"nodejs\"\npath = \"./frontend/package.json\" # Optional: if package.json is not in the project root\n\n[tool.hatch.metadata.hooks.nodejs] # Optional: to sync other metadata\nfields = [\"name\", \"description\"] # Optional: fields to sync\n\n# package.json (example)\n{\n  \"name\": \"my-package\",\n  \"version\": \"1.2.3\",\n  \"description\": \"A simple Node.js package.\"\n}","lang":"toml","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `\"hatch-nodejs-version\"` to the `requires` array under `[build-system]` in your `pyproject.toml`.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Upgrade to version `0.3.2` or newer to ensure `package.json` files maintain correct formatting upon modification.","message":"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.","severity":"gotcha","affected_versions":"<0.3.2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"Plugin 'nodejs' not found for version source"},{"fix":"Ensure `package.json` exists in your project, or set the correct `path` (e.g., `path = \"./frontend/package.json\"`) in your `pyproject.toml` configuration.","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.","error":"No 'package.json' file found at expected path: './package.json'"},{"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`.","cause":"The version in your `package.json` includes unsupported elements according to PEP 440, such as build metadata (e.g., `+build123`).","error":"The version string in package.json does not conform to PEP 440 compatible format."}]}