package.json — Node.js Project Manifest

Learning Focus

package.json is the cornerstone JSON config in the JavaScript ecosystem. Every Node.js project starts with it.

Anatomy of package.json

package.json

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "A Node.js web application",
  "main": "dist/index.js",
  "type": "module",
  "scripts": {
    "start":  "node dist/index.js",
    "dev":    "tsx watch src/index.ts",
    "build":  "tsc",
    "test":   "jest --coverage",
    "lint":   "eslint . --ext .ts",
    "format": "prettier --write ."
  },
  "dependencies": {
    "express": "^4.18.2",
    "zod":     "^3.22.0"
  },
  "devDependencies": {
    "typescript":     "^5.3.0",
    "jest":           "^29.7.0",
    "@types/express": "^4.17.21"
  },
  "engines": { "node": ">=18.0.0" },
  "license": "MIT"
}

Version Specifiers

Specifier	Meaning
"4.18.2"	Exact version only
"^4.18.2"	Compatible with 4.x.x
"~4.18.2"	Patch updates only: 4.18.x
">=4.0.0 <5.0.0"	Range expression

dependencies vs devDependencies

Category	Installed When	Examples
dependencies	Always	express, zod
devDependencies	Dev only	typescript, jest, eslint
peerDependencies	Provided by host app	React component libraries

Common Pitfalls

Pitfall	Consequence	Prevention
Committing node_modules	Huge repo, wrong binaries	Add to .gitignore
"*" version specifier	Breaking changes break app	Use ^ or exact pin
Tool deps in dependencies	Inflated production bundle	Move to devDependencies
Missing engines	Runs on wrong Node version	Specify "node": ">=18"

What's Next

• Next: tsconfig.json and JSONC — TypeScript config and JSON with comments.
• Section Overview — Return to the Configuration module index.