Everything in package.json Explained (The Fields You Skip Actually Matter)

dependencies are packages required to run your application in production — Express, React, database clients. They're installed when someone runs npm install in your project. devDependencies are packages needed only during development and building — Jest, TypeScript, ESLint, Webpack. They're not installed when your package is installed as a dependency by another project (unless NODE_ENV=development). peerDependencies are packages your library requires the consumer to provide — a React component library listing react as a peer dependency means it will use whatever React version the consuming project has, rather than installing its own. This prevents duplicate React instances and version conflicts. peerDependencies are not automatically installed; they're declared requirements.

main specifies the entry point when someone does require('your-package') in CommonJS. It's been the standard since Node.js began. exports is a newer, more powerful alternative that supports multiple entry points, ESM vs CJS distinction, and conditional exports based on environment. With exports, you can expose different files for Node vs browsers, restrict which internal files can be imported (preventing consumers from importing private internals), and define exports for both import (ESM) and require (CJS) formats. Modern packages targeting both Node and browsers should use exports; main is kept for backward compatibility with older Node versions and tools that don't yet support exports.

Exact version (1.2.3) installs only that version. Tilde (~1.2.3) allows patch updates: >=1.2.3 and <1.3.0. Caret (^1.2.3) allows minor and patch updates: >=1.2.3 and <2.0.0. This is npm's default when you run npm install --save. Asterisk (*) allows any version. The assumption behind caret: semver-compliant packages don't introduce breaking changes in minor versions, only in major versions. This assumption is frequently violated in practice, which is why package-lock.json exists — it pins exact versions so that npm install gives the same result every time, regardless of what new versions have been published.