# 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:

```json
{
  "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:

```md
## 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](https://pacmon.dev/javascript/) covers the details.