Dependencies vs devDependencies vs peerDependencies

In JavaScript and Node.js projects, the package.json file uses different dependency fields to control how external libraries are installed and bundled. Understanding the differences between dependencies, devDependencies, and peerDependencies ensures that your production builds remain lightweight, development tools remain isolated, and published packages maintain compatibility with host environments.

dependencies (Production Dependencies)

The dependencies object lists the essential packages required for your application to run in a production environment. When your code executes in production, it directly relies on these modules.

• Purpose: Core runtime functionality.
• When installed: Always, including when users install your package via npm install <package-name> or when running npm install --production.
• Installation command: npm install <package-name> (or npm i -S <package-name>)
• Typical examples: react, express, axios, lodash

If a package is imported directly into the code that runs on your production server or client browser, it belongs in dependencies.

devDependencies (Development Dependencies)

The devDependencies object lists packages that are only needed during the local development, testing, and build phases of a project. These packages are not required for the application to run in production.

• Purpose: Tooling, testing, formatting, compiling, and bundling.
• When installed: During local development (npm install). They are omitted when installing with the --production flag or when your package is installed as a dependency by another project.
• Installation command: npm install <package-name> --save-dev (or npm i -D <package-name>)
• Typical examples: jest, eslint, webpack, typescript, babel, prettier

Placing build-time tools in devDependencies keeps production deployment artifacts smaller and reduces deployment times.

peerDependencies (Plugin and Host Dependencies)

The peerDependencies object is primarily used when developing libraries, plugins, or shared component packages. It specifies that your package requires a specific dependency, but expects the consumer (the root project importing your package) to provide it.

• Purpose: Preventing duplicate installations and version conflicts of shared core libraries.
• When installed: In npm versions 7 and higher, peer dependencies are installed automatically by default if they are missing. In older versions (npm 4–6), npm displays a warning if the host project does not satisfy the peer dependency.
• Installation command: Manually added to package.json or installed using npm install <package-name> --save-peer.
• Typical examples: A React UI component library requiring react and react-dom, or an ESLint configuration requiring eslint.

By declaring a peer dependency, you ensure that the host application and your package share the exact same instance of a library.

Summary Comparison