What's the Difference Between Dependencies, devDependencies and peerDependencies in Npm Package. Json File?

Summary of important behavior differences:

• dependencies are installed on both:

  • npm install from a directory that contains package.json
  • npm install $package on any other directory

• devDependencies are:

  • also installed on npm install on a directory that contains package.json, unless you pass the --production flag (go upvote Gayan Charith's answer), or if the NODE_ENV=production environment variable is set
  • not installed on npm install "$package" on any other directory, unless you give it the --dev option.
  • are not installed transitively.

• peerDependencies:

  • before 3.0: are always installed if missing, and raise an error if multiple incompatible versions of the dependency would be used by different dependencies.
  • expected to start on 3.0 (untested): give a warning if missing on npm install, and you have to solve the dependency yourself manually. When running, if the dependency is missing, you get an error (mentioned by @nextgentech) This explains it nicely:
  • in version 7 peerDependencies are automatically installed unless an upstream dependency conflict is present that cannot be automatically resolved

• Transitivity (mentioned by Ben Hutchison):

  • dependencies are installed transitively: if A requires B, and B requires C, then C gets installed, otherwise, B could not work, and neither would A.

  • devDependencies is not installed transitively. E.g. we don't need to test B to test A, so B's testing dependencies can be left out.

Related options not discussed here:

• bundledDependencies which is discussed on the following question: Advantages of bundledDependencies over normal dependencies in npm
• optionalDependencies (mentioned by Aidan Feldman)

devDependencies

dependencies are required to run, devDependencies only to develop, e.g.: unit tests, CoffeeScript to JavaScript transpilation, minification, ...

If you are going to develop a package, you download it (e.g. via git clone), go to its root which contains package.json, and run:

npm install

Since you have the actual source, it is clear that you want to develop it, so by default, both dependencies (since you must, of course, run to develop) and devDependency dependencies are also installed.

If however, you are only an end user who just wants to install a package to use it, you will do from any directory:

npm install "$package"

In that case, you normally don't want the development dependencies, so you just get what is needed to use the package: dependencies.

If you really want to install development packages in that case, you can set the dev configuration option to true, possibly from the command line as:

npm install "$package" --dev

The option is false by default since this is a much less common case.