How to write a package.json, field by field
Every Node.js project and npm package starts from a package.json file. It names the project, lists what it depends on and defines the commands you run. This page explains the fields you will actually use and the version rules that confuse people most.
Creating one
npm init asks a few questions and writes the file; npm init -y accepts every default. The result is plain JSON, so the usual JSON rules apply: double quotes around keys and strings, no comments and no trailing commas. A single stray comma stops every npm command with a parse error.
A realistic example
{
"name": "@acme/invoice-tools",
"version": "1.4.0",
"description": "Helpers for formatting and totalling invoices",
"type": "module",
"exports": "./dist/index.js",
"files": ["dist"],
"scripts": {
"build": "tsc",
"test": "vitest run",
"lint": "eslint src",
"prepublishOnly": "npm run build"
},
"dependencies": {
"date-fns": "^3.6.0"
},
"devDependencies": {
"typescript": "~5.4.0",
"vitest": "^1.6.0"
},
"engines": { "node": ">=18" },
"license": "MIT",
"repository": "github:acme/invoice-tools"
}
The fields that matter
| Field | What it does |
|---|---|
name | Lowercase, no spaces, unique on the registry if published. A scope such as @acme/ groups related packages. |
version | Three numbers, MAJOR.MINOR.PATCH, following semantic versioning |
type | "module" makes .js files ES modules (import); without it they are CommonJS (require) |
exports | The entry points other code may import; anything not listed is private |
files | Which files go into the published package |
scripts | Named commands run with npm run <name> |
engines | Which Node versions the project supports |
private | true makes npm refuse to publish; use it for apps |
dependencies or devDependencies?
Ask one question: does the code need this package when it runs? A date library used at runtime goes in dependencies. Build tools, test runners, linters and type definitions go in devDependencies. npm install name adds to the first list and npm install -D name to the second. For a deployed application the split matters less, but for a published library it decides what your users download.
Reading version ranges
| Range | Accepts | Example matches |
|---|---|---|
^3.6.0 | Same major, anything newer | 3.6.1, 3.9.0 — not 4.0.0 |
~5.4.0 | Same major and minor, newer patch | 5.4.5 — not 5.5.0 |
1.2.3 | Exactly that version | 1.2.3 only |
>=18 | That version or anything later | 18, 20, 22 |
One special case: for versions below 1.0.0 the caret is stricter. ^0.3.1 allows 0.3.x patches but not 0.4.0, because in the zero range a minor bump may break things.
How scripts behave
npm adds node_modules/.bin to the PATH while a script runs, so "test": "vitest run" finds the locally installed tool without a global install. A script called pre or post plus another script’s name runs automatically before or after it. test and start also work without run: npm test. To pass extra arguments through, put them after a double dash: npm test -- --watch.
Common mistakes
- Editing versions by hand and skipping install. The lock file falls out of step. Run
npm installafter edits, or usenpm install name@version. - Using
npm installin CI. It may update the lock file.npm ciinstalls exactly what is locked and fails if the two files disagree. - Forgetting
"private": trueon an app. One accidentalnpm publishcan push internal code to the public registry.
Questions
Can I add comments to package.json?
JSON has no comment syntax. Some people use a key such as "//" for notes, but a README is a better home for explanations.
What does the main field do?
It is the older way to name the entry file. Newer packages use exports, and many keep main as well for older tools.