# Dependency notes for JavaScript

`package.json` is JSON, and JSON has [no comments](https://depos.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.

Depos keeps that note in `.depos/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://depos.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 Depos reads

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

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

It does not matter which package manager installs the packages — npm, pnpm, Yarn or Bun. Depos 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"
  }
}
```

`.depos/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`.

## Comments in package.json

JSON has no comment syntax: a `//` line makes npm stop with `EJSONPARSE` before it installs anything. A `"//"` key at the top level holds a comment that npm keeps, but away from the dependency it is about; inside `dependencies`, npm reads it as a package and fails. [Comments in package.json](https://depos.dev/package-json-comments/) goes through each workaround and where it breaks.

## Pinning a version

`npm install express@4` saves a caret range, `"^4.22.3"`, which accepts any later 4.x release. `npm install --save-exact` (`-E`) saves `"4.22.3"` instead, and `save-exact=true` in the project's `.npmrc` makes that the default. pnpm, Yarn and Bun have the same switch: `pnpm add -E`, `yarn add -E`, `bun add --exact`. pnpm 11 reads the default as `saveExact: true` from `pnpm-workspace.yaml` and ignores `save-exact` in `.npmrc`.

The lockfile — `package-lock.json`, `pnpm-lock.yaml` or `yarn.lock` — records the exact version of every package in the tree, and `npm ci` stops when it no longer matches `package.json`. A package deeper in the tree, which [`npm why`](https://depos.dev/npm-why/) traces to the dependency that brings it in, is held with `overrides` in `package.json` for npm, `overrides` in `pnpm-workspace.yaml` for pnpm (before pnpm 11, `pnpm.overrides` in `package.json`), and `resolutions` for Yarn.

None of these says why a version is held. That goes in the package's note: the `constraint:` line above is why react stays on ^18.

## 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://depos.dev/agents/).