What's the difference between dependencies, devDependencies, and peerDependencies in NPM package.json file?

When working with Node.js or front-end JavaScript projects, the package.json file often contains three key sections that determine how packages are installed and used: dependencies, devDependencies, and peerDependencies. Each serves a specific purpose in how you manage and share your project’s dependencies.

1. dependencies

What It Is

• dependencies are packages that your project needs in production—i.e., at runtime.
• These packages are typically required or imported by your code, such that your app breaks or doesn’t function if these dependencies are missing.

How They’re Installed

• By default, npm install will install these dependencies in the node_modules folder.
• They appear in the dependencies section of package.json and are installed for anyone who runs npm install or yarn install.

Example

{
  "dependencies": {
    "react": "^17.0.2",
    "axios": "^0.27.2"
  }
}

Here, your project depends on react and axios at runtime. Any environment that runs your app must have these installed.

2. devDependencies

What It Is

• devDependencies are packages needed during development but not required at runtime.
• They often include:
  • Testing frameworks (e.g., Jest, Mocha)
  • Linting tools (e.g., ESLint)
  • Build or bundling tools (e.g., Webpack, Babel)
  • Documentation generators, etc.

How They’re Installed

• Typically installed alongside dependencies via npm install, but they aren’t included in production builds if you only deploy the compiled output (e.g., when using bundlers or build pipelines).
• For Node.js apps, if you run npm install --production, only dependencies are installed, not devDependencies.

Example

{
  "devDependencies": {
    "webpack": "^5.74.0",
    "babel-core": "^6.26.3",
    "jest": "^28.0.0",
    "eslint": "^8.0.0"
  }
}

3. peerDependencies

What It Is

• peerDependencies are packages that your code expects the consuming project to provide. This is common when developing plugins or add-ons that must use the same exact instance of a library as the host application.
• Essentially, you’re declaring: “My package works with this particular library, but you, the consumer, must install it.”

How They’re Installed

• Not automatically installed in older npm versions.
• In npm v7+, peer dependencies are auto-installed under certain circumstances, but in general, the idea is that the parent application declares and manages those dependency versions to avoid duplication or version conflicts.

Example

{
  "peerDependencies": {
    "react": "^17.0.2"
  }
}

If you create a React component library, you might list React as a peer dependency so the consuming app uses its own React version, preventing multiple conflicting React versions from being installed.

Why Use peerDependencies?

1. Plugins & Extensions: A plugin expects to share the host’s instance of a library.
2. Avoid Version Conflicts: For example, multiple React versions can lead to obscure bugs or performance issues.
3. Reduced Bundle Size: The host app already includes the library, so you don’t bundle or re-install it in your package.

Practical Guidelines

1. dependencies

   • Everything the user of your app must have at runtime belongs here.

2. devDependencies

   • Tools for building, testing, and developing your code.
   • They aren’t part of production runtime.

3. peerDependencies

   • If you’re building a library or plugin that depends on a host library, but you don’t want to bundle or manage that library version yourself, declare it as a peer dependency.
   • This ensures the consumer of your library installs the correct version.

Examples in Context

Typical Web App

{
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "axios": "^0.27.2"
  },
  "devDependencies": {
    "webpack": "^5.74.0",
    "babel-core": "^7.12.10",
    "jest": "^28.0.0",
    "eslint": "^8.0.0"
  }
}

• At runtime, the app needs React, ReactDOM, and Axios.
• For development, we need Webpack, Babel, Jest, ESLint, etc.

A React Component Library

{
  "name": "my-react-library",
  "peerDependencies": {
    "react": "^17.0.2"
  },
  "devDependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "webpack": "^5.74.0"
  }
}

• We list react as a peer dependency because the consuming application (the parent project) should provide React.
• In devDependencies, we still need React to develop and test our library, but it won’t be bundled for consumers.

Recommended Resource

• Grokking JavaScript Fundamentals

Final Takeaways

1. dependencies: Required in production at runtime.
2. devDependencies: Required for development (build, test, lint), but not in production.
3. peerDependencies: Declares compatibility—the host project (app or library) must install these packages itself to prevent version conflicts or multiple instances.

By understanding these distinctions, you’ll better manage version constraints, reduce bundle sizes, and avoid conflicts, making your project’s dependency management more robust and predictable.