Comments in package.json

package.json is JSON, and JSON has no comment syntax. Add a // pinned for the auth middleware line and npm stops with EJSONPARSE before it does anything else; Node cannot read the file either. The usual workarounds follow, with what each one costs.

A "//" key

npm leaves alone the top-level fields it does not use, so a "//" key can hold a comment, and npm keeps it when it rewrites the file:

{
  "name": "api",
  "//": "express stays on 4.x: the auth middleware breaks on 5 (SEC-1234).",
  "dependencies": {
    "express": "^4.19.2"
  }
}

That works, within limits:

• It sits away from the dependency. The note is at the top of the file, express further down, and nothing ties the two together.
• It cannot go inside dependencies. There npm reads it as a package named //, and npm install fails with EINVALIDPACKAGENAME.
• One per object. A second "//" next to the first is a duplicate key. npm keeps only the last one: the next time it rewrites the file — npm pkg set, for one — the others are gone, without a warning.

package.json5 or package.yaml

pnpm reads a package.json5 or a package.yaml in place of package.json, and both allow comments. npm does not: it looks for package.json and stops when there is none, so npm can no longer install the project. Node reads only package.json as well: a "type" set in package.yaml never reaches it.

A separate file

A DEPENDENCIES.md or a section of the README holds as much text as you need. It is not where anyone looks when they change package.json, though, and nothing notices when a package arrives without a line.

A note on the dependency's line

Pacmon keeps the notes in a file of their own, .pacmon/DEPENDENCY-NOTES.md, beside package.json, one section per dependency:

## express

HTTP API layer (SEC-1234).
Do not upgrade to v5 — the auth middleware is incompatible.

### Agent notes

- constraint: stay on ^4 — v5 changes router path matching and the session API
- verify: `vitest src/api` and the login e2e (`pnpm e2e:auth`)

In package.json, the first line of the note appears at the end of the dependency's line, and the whole note on hover. package.json itself stays plain JSON, which npm, pnpm, Yarn, Bun and Node read as before. Documentation Coverage lists the dependencies that have no note yet. AI coding agents read the same file before they touch a package, and keep their own lines under ### Agent notes.

Dependency notes for JavaScript covers the details.