json5-manifest-sync 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.3.5] - 2026-11-09
+
+### Changed
+
+- Clarified the README's pnpm workflow for projects that start with only `package.json5`.
+- Marked pnpm manifest-precedence claims that still need a citation.
+
+## [0.3.4] - 2026-11-09
+
+### Changed
+
+- Simplified README installation guidance and removed repeated usage examples.
+
 ## [0.3.3] - 2026-11-09
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # json5-manifest-sync
 
-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.
+Document your npm package manifest with comments in a companion `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:
 
@@ -21,7 +21,7 @@ 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.
 
 > [!NOTE]
-> pnpm supports `package.json5` natively, but when both files exist it prefers `package.json`. Keeping the manifests synchronized makes this trivial: pnpm reads `package.json`, whose values match `package.json5`. Other tools in your scripts, CI/CD, publishing, or deployment workflows may also expect `package.json`.
+> pnpm supports `package.json5` natively, but when both files exist it prefers `package.json` (citation needed). Keeping the manifests synchronized makes this trivial: pnpm reads `package.json`, whose values match `package.json5`. Other tools in your scripts, CI/CD, publishing, or deployment workflows may also expect `package.json`.
 
 ## Quick Start
 
@@ -51,6 +51,28 @@ Run it:
 npm run sync:json5
 ```
 
+## Alternative installation methods
+
+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:
+
+```bash
+npm install github:BBaysinger/json5-manifest-sync#main
+```
+
 ## Why this exists
 
 `package.json` must be strict JSON, which means comments are invalid. That makes it hard to document complex scripts, dependency choices, or workspace settings directly in the manifest.
@@ -61,9 +83,6 @@ Some tooling does not treat `package.json5` as a package manifest source. While
 
 This is also why the long-running Yarn Berry discussion about comment-friendly manifests is relevant here: [yarnpkg/berry#241](https://github.com/yarnpkg/berry/issues/241) describes the same underlying need, along with the ecosystem compatibility constraints that make a companion `package.json5` approach useful today.
 
-> [!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 for this tool is configurable. By default:
 
 - `package.json` is authoritative for manifest values.
@@ -71,7 +90,7 @@ The source of truth for this tool is configurable. By default:
 
 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`.
+**pnpm consideration:** pnpm has no setting or environment variable to prefer `package.json5` when both files exist (citation needed). 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`:
 
@@ -101,65 +120,7 @@ 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 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:
-
-```bash
-npm install github:BBaysinger/json5-manifest-sync#main
-```
-
-## Use in a project
-
-Add a script in your consuming project's `package.json`:
-
-```json
-{
-  "scripts": {
-    "sync:json5": "json5-manifest-sync"
-  }
-}
-```
-
-Run it:
-
-```bash
-npm run sync:json5
-```
-
-### Options
+## Options
 
 By default, the tool runs with `--blank-comments=preserve`.
 
@@ -176,15 +137,17 @@ JSON5_MANIFEST_SYNC_SOURCE_OF_TRUTH=package.json5
 
 An existing shell environment variable takes precedence over `.env`, and `--source=...` takes precedence over both. If the setting is omitted, the default remains `package.json`.
 
-For a project that has only `package.json5`, run the tool through `npx` (or install it globally) to generate the initial `package.json`—no pnpm installation is needed:
+If you use npm in a project that has only `package.json5`, run the tool through `npx` (or install it globally) to generate the initial `package.json`:
 
 ```bash
 npx --yes --package=json5-manifest-sync json5-manifest-sync --source=package.json5
 ```
 
-You cannot use a local `npm run` script or install this tool as a local dev dependency until `package.json` exists. Once generated, npm and other strict-JSON tools can use it. Note that commands such as `npm install` update `package.json`; reconcile those changes back into `package.json5` with the default `--source=package.json` mode before regenerating JSON from the JSON5 source, or those updates could be overwritten.
+Without `package.json`, npm cannot run project scripts or install local dev dependencies. pnpm supports `package.json5` directly, so you can install the tool with `pnpm add --save-dev json5-manifest-sync` and run `pnpm exec json5-manifest-sync --source=package.json5`. If you define a script in `package.json5`, include `--source=package.json5` in its command; the default direction reads `package.json`. Once generated, `package.json` is available to npm and other tools that require strict JSON.
+
+Commands such as `npm install` update `package.json`; reconcile those changes back into `package.json5` with the default `--source=package.json` mode before regenerating JSON from the JSON5 source, or those updates could be overwritten.
 
-Because pnpm prefers `package.json` when both files exist, it will read the generated JSON copy in that setup; it reads `package.json5` directly only when `package.json` is absent.
+In this setup, pnpm reads the generated `package.json`; it reads `package.json5` directly only when `package.json` is absent (citation needed).
 
 Choose a blank-comment mode with one of the following:
 
@@ -217,16 +180,10 @@ Example prompt:
 
 > "Complete empty `//` comment lines in `package.json5` with concise, field-specific comments."
 
-## Example dependency block in consumer
-
-```json
-{
-  "dependencies": {
-    "json5-manifest-sync": "^0.3.0"
-  }
-}
-```
-
 ## Changelog
 
 See `CHANGELOG.md` for full release history.
+
+## Author
+
+Bradley Baysinger ([@BBaysinger](https://github.com/BBaysinger))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json5-manifest-sync",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Sync package.json and package.json5 manifests in either direction, preserving JSON5 comments where possible.",
   "author": {
     "name": "Bradley Baysinger",