# Dependency notes for JavaScript

`package.json` is JSON, and JSON has [no comments](https://pacmon.dev/package-json-comments/). Why a package is there, why it is pinned, what to run before upgrading it: none of that fits in the file. It ends up in commit messages, pull requests and people's memory, and the next person — or the next AI agent — upgrades the package anyway.

Pacmon keeps that note in `.pacmon/DEPENDENCY-NOTES.md`, beside `package.json`, and shows it on the dependency's line: the first line at the end of the line, the whole note on hover.

![package.json in IntelliJ IDEA: filled marks and the first line of the note after typescript, vite and vue-tsc, hollow marks before the packages that have no note yet](https://pacmon.dev/shots/javascript.png)

*`package.json` in [IntelliJ IDEA](https://www.jetbrains.com/idea/). Copyright © 2026 JetBrains s.r.o., used with permission. IntelliJ IDEA and the IntelliJ IDEA logo are trademarks of JetBrains s.r.o.*

## What Pacmon reads

- **Manifest:** `package.json`
- **Notes file:** `.pacmon/DEPENDENCY-NOTES.md`
- **Section heading:** the package name: `## express`, `## @types/node`

Pacmon reads `dependencies`, `devDependencies`, `peerDependencies` and `optionalDependencies`.

It does not matter which package manager installs the packages — npm, pnpm, Yarn or Bun. Pacmon reads `package.json` itself and never runs any of them.

## Example

```json
{
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@types/node": "^22.10.2"
  }
}
```

`.pacmon/DEPENDENCY-NOTES.md`:

```md
## @types/node

Types for the Node version in .nvmrc, not the newest one.

### Agent notes

- purpose: type definitions for the Node runtime the build scripts run on
- constraint: keep the major equal to the Node major in .nvmrc (22)

## react

Stay on 18 until the design system ships its React 19 build (DS-88).

### Agent notes

- purpose: UI library for the whole front end
- constraint: stay on ^18 — the design system still relies on APIs that React 19 removed
- bump-with: react-dom
- verify: `pnpm test` and the visual regression suite (`pnpm test:visual`)
- verified: 18.3.1
```

The heading is the package name as `package.json` spells it, scope included. Sections are sorted by name, so `@types/node` comes before `react`.

## For AI coding agents

An agent reads a package's section before it adds, upgrades or removes the package. `constraint:` tells it what must not change, `verify:` what to run, and `bump-with:` which packages move together. It logs what it tried, including the upgrades it reverted, so the next agent does not try them again. See [the rules agents follow](https://pacmon.dev/agents/).