dependencies vs devDependencies vs peerDependencies

If you want to correctly maintain a Javascript project that uses NPM / a package.json file, it's important to know the differences between dependencies, devDependencies and peerDependencies. It'll also help you to manage them efficiently.

#dependencies

The libraries under dependencies are those that your project really needs to be able to work in production. Usually, these libraries have all or part of their code in your final bundle(s). You can add them in your project using the following command line: yarn add my-library.

The libraries you can find under dependencies include utility libraries such as lodash, classnames etc and also the "main" libraries of your project.

#devDependencies

As we can guess thanks to its name, the libraries under devDependencies are those that you need during development. To add dependencies in this section, you just have to add the -D or --dev option to your command line: yarn add -D my-library.

So you'll find here different types of libraries such as:

• formatting libraries: eslint, prettier, ...
• bundlers: webpack, gulp, parceljs, ...
• babel and all its plugins
• everything related to tests: enzyme, jest, ...
• a bunch of other libraries: storybook, react-styleguidist, husky, ...

#peerDependencies

95% of the time, you'll use only dependencies and devDependencies. But if you want to create and publish your own library so that it can be used as a dependency, you may also need the peerDependencies. Under this section, you can indicate which versions of some of your important libraries are required. Let's imagine that your project (ProjectA) uses an important library (peer-lib) and you know or at least guess that the project (MainProject) which will use your library will also use this peer-lib library. If you want to make sure that the version of peer-lib used in MainProject works with your version in ProjectA, you should use peerDependencies.

You can add this peer-lib under peerDependencies thanks to --peer option: yarn add --peer peer-lib. And then the corresponding version will indicate to MainProject which version of peer-lib is required. If they don't match this version, a warning will be displayed when they'll add ProjectA as a dependency and each time they'll run a yarn install.

It's not mandatory but it's highly recommended to be lenient when you indicate the corresponding version(s). However, if your version is too restrictive, it may be really complicated to match it.

Here are some examples of libraries that we usually put under peerDependencies : react, react-dom, styled-components, etc.

---

TL;DR: dependencies and devDependencies are used to make a difference between the libraries that will be (or won't be) in your final bundle. peerDependencies are useful only if you want to create and publish your own library.