Anatomy of a package.jsonWhat is json?A text format for exchanging data between systems. It uses key-value pairs and arrays, and every programming language can read and write it. Ask AI for more

Here is a realistic package.json for a React project, annotated with what each section does:

{
  "name": "my-react-app",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint src/"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.20.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.0",
    "@vitejs/plugin-react": "^4.2.0",
    "eslint": "^8.55.0",
    "typescript": "^5.3.0",
    "vite": "^5.0.0"
  }
}

The "private": true field prevents accidental publishing to the npm registryWhat is registry?A server that stores and distributes packages or container images - npm registry for JavaScript packages, Docker Hub for container images. Ask AI for more. Always include it for application projects (as opposed to libraries you intend to share).

The scripts section

This is the section you interact with most. It maps short names to terminalWhat is terminal?A text-based interface where you type commands to interact with your computer. Also called the command line or shell. Ask AI for more commands:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "test": "vitest",
    "lint": "eslint src/",
    "format": "prettier --write src/"
  }
}

Two scripts have special shorthand, npm start and npm test work without the run keyword. Everything else requires npm run:

npm start          # shorthand for npm run start
npm test           # shorthand for npm run test
npm run dev        # must use "run" for custom scripts
npm run build      # must use "run"

Scripts can call other scripts and chain commands:

{
  "scripts": {
    "prebuild": "npm run lint",
    "build": "vite build",
    "build:all": "npm run build && npm run build:css"
  }
}

The pre prefix is special, prebuild runs automatically before build every time you run npm run build.

dependencies vs devDependencies

This distinction determines what gets installed in production. Getting it wrong is one of the most common deployment bugs.

The rule is simple: if your app needs the package to run in a user's browser or on a production server, it belongs in dependencies. If it is only used while you are writing, testing, or building code, it belongs in devDependencies.

# Add to dependencies (needed at runtime)
npm install react

# Add to devDependencies (needed only during development)
npm install --save-dev typescript
# Shorthand:
npm install -D typescript

Common mistakes:

vite in dependencies        → should be devDependencies (build tool)
@types/react in dependencies → should be devDependencies (type definitions)
express in devDependencies   → should be dependencies (runs your server)

Version specifiers (semver)

Every version number follows semantic versioningWhat is semantic versioning?A numbering system (major.minor.patch) that communicates whether a release contains breaking changes, new features, or bug fixes. Ask AI for more: MAJOR.MINOR.PATCH. Each part has a specific meaning:

The symbols before a version number control how flexible npm is:

The caret ^ is the default and usually the right choice. It allows minor and patch updates (bug fixes and new features) while protecting you from breaking major version changes.

The lockfileWhat is lockfile?An auto-generated file (like package-lock.json) that records the exact version of every installed package so every environment gets identical code. Ask AI for more: package-lock.jsonWhat is json?A text format for exchanging data between systems. It uses key-value pairs and arrays, and every programming language can read and write it. Ask AI for more

package-lock.json is auto-generated and records the exact version of every package (including sub-dependencies) that was installed. It can be thousands of lines long, you never edit it by hand.

package.json says:        "react": "^18.2.0"
package-lock.json says:   "react": "18.2.0" (exact resolved version)

Without the lockfile, two developers running npm install on the same package.json could get different versions (one might get 18.2.0, another 18.3.1). The lockfile prevents that.

Always commitWhat is commit?A permanent snapshot of your staged changes saved in Git's history, identified by a unique hash and accompanied by a message describing what changed. Ask AI for more package-lock.json to Git. Never add it to .gitignore.

Troubleshooting dependencyWhat is dependency?A piece of code written by someone else that your project needs to work. Think of it as a building block you import instead of writing yourself. Ask AI for more problems

These commands will save you hours of debugging:

# See all installed packages and their versions
npm ls

# Find packages with newer versions available
npm outdated

# Scan for known security vulnerabilities
npm audit

# Fix vulnerabilities automatically where possible
npm audit fix

# Nuclear option: delete everything and reinstall from scratch
rm -rf node_modules package-lock.json
npm install

The "delete and reinstall" approach fixes most mysterious dependency issues. Use it when nothing else works.

Quick reference