What's the best way to include comments in package.json files?

Other Questions NPM
1

I’m working with a basic package.json configuration file and I need to document some of my dependency choices. I want to explain why certain packages are included or excluded from my project setup.

{
  "name": "Web Application",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "fastify": "4.x",
    "sequelize": "6.x"
  },
  "devDependencies": {
    "jest": "*"
    /* "chai": "*" skipping this since jest covers our testing needs */
  }
}

The comment syntax shown above causes npm to fail during package installation. I’ve attempted using // comment style as well but that doesn’t work either. Are there any workarounds or alternative approaches to add documentation directly within the package.json file itself?

2

JSON specification doesn’t support comments natively, so you’re stuck with workarounds if you absolutely need inline documentation. I’ve been using a “_comments” field approach for years:

{
  "name": "Web Application",
  "version": "1.0.0",
  "_comments": {
    "dependencies": "Using fastify for performance, sequelize for ORM",
    "devDependencies": "Jest chosen over chai for integrated testing suite"
  },
  "dependencies": {
    "fastify": "4.x",
    "sequelize": "6.x"
  }
}

Most npm tooling ignores unknown fields, so this works reliably. Another option is maintaining a separate README.md section explaining your dependency choices, which actually provides better documentation since you can elaborate more thoroughly than cramped inline comments would allow.

3

honestly just use package.json for what its meant for and put ur docs elsewhere. ive tried all these workarounds and they just make things messy

create a deps.md file or add a section to your readme explaining why you chose each package. way cleaner than cluttering json with fake comment fields that confuse other devs later

4

I ran into this exact problem about two years ago when onboarding new developers to our team. The solution that worked best for us was using descriptive field names alongside the actual dependencies.

Instead of trying to force comments into JSON, we created a documentation pattern like this:

{
  "name": "Web Application",
  "version": "1.0.0",
  "dependencies": {
    "fastify": "4.x",
    "sequelize": "6.x"
  },
  "devDependencies": {
    "jest": "*"
  },
  "_dependency_notes": "fastify selected for speed over express, sequelize provides postgres compatibility, jest replaces chai for simpler setup"
}

This approach keeps everything in one file without breaking npm functionality. The underscore prefix ensures the field gets ignored by package managers but remains visible to anyone reading the configuration. We found this more maintainable than separate documentation files since dependency reasoning stays close to the actual declarations.