SpunkArt
Command line and project setup

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

FieldWhat it does
nameLowercase, no spaces, unique on the registry if published. A scope such as @acme/ groups related packages.
versionThree numbers, MAJOR.MINOR.PATCH, following semantic versioning
type"module" makes .js files ES modules (import); without it they are CommonJS (require)
exportsThe entry points other code may import; anything not listed is private
filesWhich files go into the published package
scriptsNamed commands run with npm run <name>
enginesWhich Node versions the project supports
privatetrue 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

RangeAcceptsExample matches
^3.6.0Same major, anything newer3.6.1, 3.9.0 — not 4.0.0
~5.4.0Same major and minor, newer patch5.4.5 — not 5.5.0
1.2.3Exactly that version1.2.3 only
>=18That version or anything later18, 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 install after edits, or use npm install name@version.
  • Using npm install in CI. It may update the lock file. npm ci installs exactly what is locked and fails if the two files disagree.
  • Forgetting "private": true on an app. One accidental npm publish can 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.