json5-manifest-sync 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.3.2] - 2026-11-09
+
+### Changed
+
+- Clarified the README's explanation and example for documenting npm package manifests with `package.json5`.
+
 ## [0.3.0] - 2026-11-02
 
 ### Added

package/README.md

@@ -1,15 +1,39 @@
 # json5-manifest-sync
 
-Keep `package.json` and a documented `package.json5` in sync. Choose either file as the source of truth: maintain comments in `package.json5` and generate strict JSON for tools that require it, or update the JSON5 companion from `package.json`.
+Add comments to your npm package manifest in `package.json5`, then sync it with the standard `package.json` expected by npm and other tools. Choose either file as the source of truth for manifest values; `package.json` always remains valid strict JSON.
+
+For example, document dependencies in `package.json5` and generate `package.json` from it:
+
+<!-- prettier-ignore -->
+```json5
+{
+  "dependencies": {
+    // Keep JSON5 parsing available to the CLI.
+    "json5": "^2.2.3",
+  },
+}
+```
+
+```bash
+npx json5-manifest-sync --source=package.json5
+```
+
+The tool can also work in the other direction: by default, it updates `package.json5` from `package.json`, preserving mapped `//` comments where possible.
 
 pnpm supports `package.json5` natively, but other tools in a project’s scripts, CI/CD, publishing, or deployment workflows may still expect `package.json`. When both files exist, pnpm prefers `package.json`; it reads `package.json5` natively when `package.json` is absent. This tool bridges mixed toolchains by keeping both manifests synchronized in either direction.
 
 ## Quick Start
 
+Install with the package manager your project already uses:
+
 ```bash
 npm install --save-dev json5-manifest-sync
 ```
 
+```bash
+pnpm add --save-dev json5-manifest-sync
+```
+
 Add a script in your project's `package.json`:
 
 ```json
@@ -39,13 +63,22 @@ This is also why the long-running Yarn Berry discussion about comment-friendly m
 > [!NOTE]
 > pnpm's native `package.json5` support is useful when pnpm controls the workflow, but it does not make `package.json5` universally recognized across npm, CI/CD, deployment, release, and other JavaScript tooling. This project keeps `package.json` available for compatibility while providing a documented companion file.
 
-The source of truth is configurable. By default:
+The source of truth for this tool is configurable. By default:
 
 - `package.json` is authoritative for manifest values.
 - `package.json5` is authoritative for comments; values are synchronized from `package.json` while mapped `//` comments are preserved where possible.
 
 Alternatively, make `package.json5` authoritative for values and generate a strict `package.json` for tools that need it. In this direction, comments remain in `package.json5`; they are not copied to `package.json`.
 
+**pnpm consideration:** pnpm has no setting or environment variable to prefer `package.json5` when both files exist. The `--source` option and `JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH` variable configure only this tool; they do not change pnpm's selection. When the two manifests are synchronized, this is straightforward: pnpm reads `package.json`, whose values match `package.json5`. If JSON5 is your source of truth, run this tool with `--source=package.json5` before pnpm operations that need the latest values. Pnpm commands may update `package.json`, so reconcile those changes into `package.json5` before syncing from JSON5 again, or they may be overwritten. Removing `package.json` lets pnpm read `package.json5` directly, but may break Node, npm, or other tools that require `package.json`.
+
+For CI or other automated workflows where `package.json5` is authoritative, run the sync as a separate step before pnpm reads the manifest. A lifecycle hook such as `preinstall` may run too late, after pnpm has already selected `package.json`:
+
+```bash
+pnpm dlx json5-manifest-sync --source=package.json5
+pnpm install
+```
+
 ## What it does
 
 - Finds `package.json` files recursively (excluding `node_modules`)
@@ -62,28 +95,43 @@ Alternatively, make `package.json5` authoritative for values and generate a stri
 
 - Per-item comment preservation is most reliable for arrays of strings.
 - Arrays of objects or numbers still serialize correctly, but item-level comments may be dropped.
-- Use `--blank-comments=preserve` to keep existing blank `//` lines without adding new ones.
-- Use `--blank-comments=fill` to add blank `//` placeholders where comments are omitted.
-- Use `--blank-comments=remove` to strip blank `//` lines from the output.
 
 Repository: https://github.com/BBaysinger/json5-manifest-sync
 
+Package: https://www.npmjs.com/package/json5-manifest-sync
+
 ## Author
 
 Bradley Baysinger ([@BBaysinger](https://github.com/BBaysinger))
 
-## Install from npm (recommended)
+## Install from the npm registry (recommended)
+
+Use the package manager already used by your project so its lockfile stays consistent.
+
+With npm:
 
 ```bash
 npm install --save-dev json5-manifest-sync
 ```
 
+With pnpm:
+
+```bash
+pnpm add --save-dev json5-manifest-sync
+```
+
 Global install (optional):
 
 ```bash
 npm install -g json5-manifest-sync
 ```
 
+Or with pnpm:
+
+```bash
+pnpm add --global json5-manifest-sync
+```
+
 ## Install from GitHub (alternative)
 
 Use this if you want an unreleased branch or tag:
@@ -110,27 +158,6 @@ Run it:
 npm run sync:json5
 ```
 
-## Generated `package.json5` example
-
-Illustrative output (trimmed):
-
-<!-- prettier-ignore -->
-```json5
-{
-  // Package name used by npm and consumers.
-  "name": "consumer-app",
-  // Release version (keep in sync with git tags).
-  "version": "1.2.3",
-  // Development and release scripts.
-  "scripts": {
-    // Compile TypeScript to dist/.
-    "build": "tsc -p tsconfig.json",
-  },
-}
-```
-
-For the current full output style, see this repo's live example: [`package.json5`](./package.json5).
-
 ### Options
 
 By default, the tool runs with `--blank-comments=preserve`.
@@ -166,6 +193,10 @@ Choose a blank-comment mode with one of the following:
 
 To warn after sync when blank `//` placeholders remain, add `--warn-blank-comments`. That warning applies to `preserve` and `fill`; `remove` strips those lines.
 
+### Pre-commit synchronization
+
+To keep both manifests aligned in each commit, run `json5-manifest-sync` from a Git pre-commit hook after manifest changes. It uses `JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH` or the `--source` option to choose the authoritative file. Make sure the hook stages the generated counterpart as well; if you use partial staging, stage only the file generated by the sync rather than blindly adding both manifests.
+
 ### Formatting note
 
 Recommended: exclude `package.json5` from Prettier (for example via `.prettierignore`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json5-manifest-sync",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Sync package.json and package.json5 manifests in either direction, preserving JSON5 comments where possible.",
   "author": {
     "name": "Bradley Baysinger",
@@ -47,14 +47,14 @@
   },
   "dependencies": {
     "dotenv": "^18.0.10",
-    "glob": "^13.0.6",
-    "ignore": "^7.0.5",
+    "glob": "^14.0.4",
+    "ignore": "^7.0.14",
     "json5": "^2.2.3"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "prettier": "^3.8.3",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "@types/node": "^26.6.6",
+    "prettier": "^3.9.10",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
   }
 }