json5-manifest-sync 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -5
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -6,10 +6,16 @@ pnpm supports `package.json5` natively, but other tools in a project’s scripts
|
|
|
6
6
|
|
|
7
7
|
## Quick Start
|
|
8
8
|
|
|
9
|
+
Install with the package manager your project already uses:
|
|
10
|
+
|
|
9
11
|
```bash
|
|
10
12
|
npm install --save-dev json5-manifest-sync
|
|
11
13
|
```
|
|
12
14
|
|
|
15
|
+
```bash
|
|
16
|
+
pnpm add --save-dev json5-manifest-sync
|
|
17
|
+
```
|
|
18
|
+
|
|
13
19
|
Add a script in your project's `package.json`:
|
|
14
20
|
|
|
15
21
|
```json
|
|
@@ -39,13 +45,22 @@ This is also why the long-running Yarn Berry discussion about comment-friendly m
|
|
|
39
45
|
> [!NOTE]
|
|
40
46
|
> 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.
|
|
41
47
|
|
|
42
|
-
The source of truth is configurable. By default:
|
|
48
|
+
The source of truth for this tool is configurable. By default:
|
|
43
49
|
|
|
44
50
|
- `package.json` is authoritative for manifest values.
|
|
45
51
|
- `package.json5` is authoritative for comments; values are synchronized from `package.json` while mapped `//` comments are preserved where possible.
|
|
46
52
|
|
|
47
53
|
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`.
|
|
48
54
|
|
|
55
|
+
**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`.
|
|
56
|
+
|
|
57
|
+
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`:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pnpm dlx json5-manifest-sync --source=package.json5
|
|
61
|
+
pnpm install
|
|
62
|
+
```
|
|
63
|
+
|
|
49
64
|
## What it does
|
|
50
65
|
|
|
51
66
|
- Finds `package.json` files recursively (excluding `node_modules`)
|
|
@@ -62,28 +77,43 @@ Alternatively, make `package.json5` authoritative for values and generate a stri
|
|
|
62
77
|
|
|
63
78
|
- Per-item comment preservation is most reliable for arrays of strings.
|
|
64
79
|
- Arrays of objects or numbers still serialize correctly, but item-level comments may be dropped.
|
|
65
|
-
- Use `--blank-comments=preserve` to keep existing blank `//` lines without adding new ones.
|
|
66
|
-
- Use `--blank-comments=fill` to add blank `//` placeholders where comments are omitted.
|
|
67
|
-
- Use `--blank-comments=remove` to strip blank `//` lines from the output.
|
|
68
80
|
|
|
69
81
|
Repository: https://github.com/BBaysinger/json5-manifest-sync
|
|
70
82
|
|
|
83
|
+
Package: https://www.npmjs.com/package/json5-manifest-sync
|
|
84
|
+
|
|
71
85
|
## Author
|
|
72
86
|
|
|
73
87
|
Bradley Baysinger ([@BBaysinger](https://github.com/BBaysinger))
|
|
74
88
|
|
|
75
|
-
## Install from npm (recommended)
|
|
89
|
+
## Install from the npm registry (recommended)
|
|
90
|
+
|
|
91
|
+
Use the package manager already used by your project so its lockfile stays consistent.
|
|
92
|
+
|
|
93
|
+
With npm:
|
|
76
94
|
|
|
77
95
|
```bash
|
|
78
96
|
npm install --save-dev json5-manifest-sync
|
|
79
97
|
```
|
|
80
98
|
|
|
99
|
+
With pnpm:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
pnpm add --save-dev json5-manifest-sync
|
|
103
|
+
```
|
|
104
|
+
|
|
81
105
|
Global install (optional):
|
|
82
106
|
|
|
83
107
|
```bash
|
|
84
108
|
npm install -g json5-manifest-sync
|
|
85
109
|
```
|
|
86
110
|
|
|
111
|
+
Or with pnpm:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pnpm add --global json5-manifest-sync
|
|
115
|
+
```
|
|
116
|
+
|
|
87
117
|
## Install from GitHub (alternative)
|
|
88
118
|
|
|
89
119
|
Use this if you want an unreleased branch or tag:
|
|
@@ -166,6 +196,10 @@ Choose a blank-comment mode with one of the following:
|
|
|
166
196
|
|
|
167
197
|
To warn after sync when blank `//` placeholders remain, add `--warn-blank-comments`. That warning applies to `preserve` and `fill`; `remove` strips those lines.
|
|
168
198
|
|
|
199
|
+
### Pre-commit synchronization
|
|
200
|
+
|
|
201
|
+
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.
|
|
202
|
+
|
|
169
203
|
### Formatting note
|
|
170
204
|
|
|
171
205
|
Recommended: exclude `package.json5` from Prettier (for example via `.prettierignore`).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "json5-manifest-sync",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"description": "Sync package.json and package.json5 manifests in either direction, preserving JSON5 comments where possible.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Bradley Baysinger",
|
|
@@ -47,14 +47,14 @@
|
|
|
47
47
|
},
|
|
48
48
|
"dependencies": {
|
|
49
49
|
"dotenv": "^18.0.10",
|
|
50
|
-
"glob": "^
|
|
51
|
-
"ignore": "^7.0.
|
|
50
|
+
"glob": "^14.0.4",
|
|
51
|
+
"ignore": "^7.0.14",
|
|
52
52
|
"json5": "^2.2.3"
|
|
53
53
|
},
|
|
54
54
|
"devDependencies": {
|
|
55
|
-
"@types/node": "^
|
|
56
|
-
"prettier": "^3.
|
|
57
|
-
"typescript": "^
|
|
58
|
-
"vitest": "^
|
|
55
|
+
"@types/node": "^26.6.6",
|
|
56
|
+
"prettier": "^3.9.10",
|
|
57
|
+
"typescript": "^7.0.2",
|
|
58
|
+
"vitest": "^5.1.0"
|
|
59
59
|
}
|
|
60
60
|
}
|