2923

This documentation answers my question very poorly. I didn't understand those explanations. Can someone say in simpler words? Maybe with examples if it's hard to choose simple words?

Also added peerDependencies, which is closely related and might cause confusion.

4
  • 81
    Note there are also optionalDependencies now. Commented Jun 4, 2016 at 18:50
  • 348
    @AidanFeldman "optionalDependencies" is my oxymoron of the day
    – Nick Bull
    Commented Mar 19, 2018 at 15:56
  • 6
    npm documentation says: "dependencies": Packages required by your application in production. "devDependencies": Packages that are only needed for local development and testing. see link: docs.npmjs.com/…
    – Deke
    Commented Sep 28, 2019 at 17:57
  • dependencies are the package references that are used by your library without which it cannot work and to be installed along with your library installation automatically. While looking at peerDependencies, npm will just throw a warning message in case the specified packages are not found in node modules. It will not install any package for you. For detailed explaination refer link: medium.com/p/16f43d6c7e45
    – Goofy
    Commented Feb 2, 2022 at 11:07

16 Answers 16

3247

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: https://flaviocopes.com/npm-peer-dependencies/
    • 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:

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.

peerDependencies

(Tested before 3.0)

Source: https://nodejs.org/en/blog/npm/peer-dependencies/

With regular dependencies, you can have multiple versions of the dependency: it's simply installed inside the node_modules of the dependency.

E.g. if dependency1 and dependency2 both depend on dependency3 at different versions the project tree will look like:

root/node_modules/
                 |
                 +- dependency1/node_modules/
                 |                          |
                 |                          +- dependency3 v1.0/
                 |
                 |
                 +- dependency2/node_modules/
                                            |
                                            +- dependency3 v2.0/

Plugins, however, are packages that normally don't require the other package, which is called the host in this context. Instead:

  • plugins are required by the host
  • plugins offer a standard interface that the host expects to find
  • only the host will be called directly by the user, so there must be a single version of it.

E.g. if dependency1 and dependency2 peer depend on dependency3, the project tree will look like:

root/node_modules/
                 |
                 +- dependency1/
                 |
                 +- dependency2/
                 |
                 +- dependency3 v1.0/

This happens even though you never mention dependency3 in your package.json file.

I think this is an instance of the Inversion of Control design pattern.

A prototypical example of peer dependencies is Grunt, the host, and its plugins.

For example, on a Grunt plugin like https://github.com/gruntjs/grunt-contrib-uglify, you will see that:

  • grunt is a peer-dependency
  • the only require('grunt') is under tests/: it's not actually used by the program.

Then, when the user will use a plugin, he will implicitly require the plugin from the Gruntfile by adding a grunt.loadNpmTasks('grunt-contrib-uglify') line, but it's grunt that the user will call directly.

This would not work then if each plugin required a different Grunt version.

Manual

I think the documentation answers the question quite well, maybe you are just not familiar enough with node / other package managers. I probably only understand it because I know a bit about Ruby bundler.

The key line is:

These things will be installed when doing npm link or npm install from the root of a package and can be managed like any other npm configuration parameter. See npm-config(7) for more on the topic.

And then under npm-config(7) find dev:

Default: false
Type: Boolean

Install dev-dependencies along with packages.
25
  • 9
    Ah. I see I've misunderstood. Your answer reads as though npm install package is a command you'd use to install all packages that are not dev dependencies, rather than what I now think you meant, which was 'install the package called [package]', which was how I thought it worked before reading this. If I were you I'd edit to say [package-name] which clearly shows that what you mean is 'insert-name-here'.
    – Tom W
    Commented Mar 18, 2014 at 12:39
  • 316
    This is great! I never realized, but this answer has taught me that the dependencies vs devDependencies difference is only applicable if you're going to publish an npm package. If you're just working on an application or site, it shouldn't matter too much. Thanks!
    – user677526
    Commented Aug 29, 2014 at 3:37
  • 7
    This post should be updated to reflect the changed peerDependencies behavior in the upcoming npm@3. From blog.npmjs.org/post/110924823920/npm-weekly-5: "We won’t be automatically downloading the peer dependency anymore. Instead, we’ll warn you if the peer dependency isn’t already installed. This requires you to resolve peerDependency conflicts yourself, manually, but in the long run this should make it less likely that you’ll end up in a tricky spot with your packages’ dependencies." Commented May 22, 2015 at 4:11
  • 13
    Also, devDependencies are not installed transitively by dependent packages. Example: package A depends on package B. Package B depends on package C, and B also devDepends on package D. If you run npm install from package A, you will get B and C but not D. Commented Jan 23, 2016 at 5:31
  • 29
    It's important to remark that devDependencies aren't installed when NODE_ENV is set to production. Commented Aug 4, 2018 at 19:23
647

If you do not want to install devDependencies you can use npm install --production

6
  • 1
    npm install --save is for software dependancy? Commented Jul 27, 2015 at 9:50
  • 24
    npm install will install all dependencies. --save flag is used when you want to add the specific module to package.json too. ex:- npm install uglify --save will install uglify in your project folder and add uglify to project, package.json file. Commented Sep 13, 2015 at 7:58
  • 7
    And because we're talking devDependencies, you can use --save-dev to save the new module as a devDependency. Example: npm install uglify --save-dev
    – Mykaelos
    Commented Sep 29, 2016 at 18:39
  • 26
    As of npm 5, the --save option is no longer necessary. If you do "npm install my-package", it will add my-package as a dependency in your package.json file. Commented Feb 23, 2018 at 22:58
  • 3
    As of npm 5, the --save option is no longer necessary. That's great news! I hadn't realized this before. I always found it annoying that most docs neglect the --save option when really it hardly ever makes sense not to save the fact you added a dependency. Commented Jan 14, 2019 at 18:25
170

dependencies
Dependencies that your project needs to run, like a library that provides functions that you call from your code.
They are installed transitively (if A depends on B depends on C, npm install on A will install B and C).
Example: lodash: your project calls some lodash functions.

devDependencies
Dependencies you only need during development or releasing, like compilers that take your code and compile it into javascript, test frameworks or documentation generators.
They are not installed transitively (if A depends on B dev-depends on C, npm install on A will install B only).
Example: grunt: your project uses grunt to build itself.

peerDependencies
Dependencies that your project hooks into, or modifies, in the parent project, usually a plugin for some other library or tool. It is just intended to be a check, making sure that the parent project (project that will depend on your project) has a dependency on the project you hook into. So if you make a plugin C that adds functionality to library B, then someone making a project A will need to have a dependency on B if they have a dependency on C.
They are not installed (unless npm < 3), they are only checked for.
Example: grunt: your project adds functionality to grunt and can only be used on projects that use grunt.

This documentation explains peer dependencies really well: https://nodejs.org/en/blog/npm/peer-dependencies/

Also, the npm documentation has been improved over time, and now has better explanations of the different types of dependencies: https://github.com/npm/cli/blob/latest/docs/content/configuring-npm/package-json.md#devdependencies

2
  • 12
    Should be market as "answer" - clear and neat, first sentence under "peerDependencies" explains everything correctly, without digging into how versions are resolved in npm which is not required to understand what peerDependecies are for.
    – fires3as0n
    Commented Jan 25, 2021 at 16:11
  • 3
    Finally an answer to peerDependencies that has satisfied the "why?" instead of "how?". Very helpful! Commented Jan 28, 2022 at 0:37
153

As an example, mocha would normally be a devDependency, since testing isn't necessary in production, while express would be a dependency.

6
  • 5
    I would lean towards putting testing as a dependency since you may want to run self-tests before launching the production server
    – user9903
    Commented Jan 10, 2014 at 22:08
  • 61
    I would instead recommend using a continuous integration service like Hudson or CircleCI that runs your tests and then deploys to production if they pass.
    – Dan Kohn
    Commented Jan 12, 2014 at 13:57
  • 1
    It may still be relevant to test the actual server because the CI server might differ somehow from the prod server, and this difference may e.g. prevent the app from starting up...
    – Nicole
    Commented Mar 25, 2016 at 22:33
  • 2
    @Nicole why would you make your staging server not identical in configuration to your prod?
    – Lucas
    Commented Nov 20, 2017 at 15:57
  • 3
    Then again, adding test dependencies as regular dependencies introduces a whole bunch of extra libraries, each of which may fail in some way. I would lean (pun!) towards light-weight production servers with as little code on them as possible. Remember, the best code is no code! Commented Jan 14, 2019 at 18:27
82

To save a package to package.json as dev dependencies:

npm install "$package" --save-dev

When you run npm install it will install both devDependencies and dependencies. To avoid install devDependencies run:

npm install --production
1
  • 5
    you can also use : npm i -S
    – maysara
    Commented Jul 28, 2017 at 22:00
48

There are some modules and packages only necessary for development, which are not needed in production. Like it says it in the documentation:

If someone is planning on downloading and using your module in their program, then they probably don't want or need to download and build the external test or documentation framework that you use. In this case, it's best to list these additional items in a devDependencies hash.

3
  • 1
    What if you're running only bundle.js file on production? do you really need those dependencies?
    – RegarBoy
    Commented Sep 24, 2018 at 18:07
  • If you are running bundle.js on the server, you are doing server-side webpack or something... Please check if that's the case because it usually isn't and it actually takes a lot of work to get that running correctly (I know because I did that). I suspect your bundle.js is just served up to browsers and contains the client-side code. Commented Jan 14, 2019 at 18:29
  • 1
    The part that confuses me is, What is production here? is it the CDN server, I deploy my builds on or it the client browser that runs my build ? Commented Jan 5, 2022 at 10:30
32

peerDependencies didn't quite make sense for me until I read this snippet from a blog post on the topic Ciro mentioned above:

What [plugins] need is a way of expressing these “dependencies” between plugins and their host package. Some way of saying, “I only work when plugged in to version 1.2.x of my host package, so if you install me, be sure that it’s alongside a compatible host.” We call this relationship a peer dependency.

The plugin does expect a specific version of the host...

peerDependencies are for plugins, libraries that require a "host" library to perform their function, but may have been written at a time before the latest version of the host was released.

That is, if I write PluginX v1 for HostLibraryX v3 and walk away, there's no guarantee PluginX v1 will work when HostLibraryX v4 (or even HostLibraryX v3.0.1) is released.

... but the plugin doesn't depend on the host...

From the point of view of the plugin, it only adds functions to the host library. I don't really "need" the host to add a dependency to a plugin, and plugins often don't literally depend on their host. If you don't have the host, the plugin harmlessly does nothing.

This means dependencies isn't really the right concept for plugins.

Even worse, if my host was treated like a dependency, we'd end up in this situation that the same blog post mentions (edited a little to use this answer's made up host & plugin):

But now, [if we treat the contemporary version of HostLibraryX as a dependency for PluginX,] running npm install results in the unexpected dependency graph of

├── [email protected]
└─┬ [email protected]
  └── [email protected]

I’ll leave the subtle failures that come from the plugin using a different [HostLibraryX] API than the main application to your imagination.

... and the host obviously doesn't depend on the plugin...

... that's the whole point of plugins. Now if the host was nice enough to include dependency information for all of its plugins, that'd solve the problem, but that'd also introduce a huge new cultural problem: plugin management!

The whole point of plugins is that they can pair up anonymously. In a perfect world, having the host manage 'em all would be neat & tidy, but we're not going to require libraries herd cats.

If we're not hierarchically dependent, maybe we're intradependent peers...

Instead, we have the concept of being peers. Neither host nor plugin sits in the other's dependency bucket. Both live at the same level of the dependency graph.


... but this is not an automatable relationship. <<< Moneyball!!!

If I'm PluginX v1 and expect a peer of (that is, have a peerDependency of) HostLibraryX v3, I'll say so. If you've auto-upgraded to the latest HostLibraryX v4 (note that's version 4) AND have Plugin v1 installed, you need to know, right?

npm can't manage this situation for me --

"Hey, I see you're using PluginX v1! I'm automatically downgrading HostLibraryX from v4 to v3, kk?"

... or...

"Hey I see you're using PluginX v1. That expects HostLibraryX v3, which you've left in the dust during your last update. To be safe, I'm automatically uninstalling Plugin v1!!1!

How about no, npm?!

So npm doesn't. It alerts you to the situation, and lets you figure out if HostLibraryX v4 is a suitable peer for Plugin v1.


Coda

Good peerDependency management in plugins will make this concept work more intuitively in practice. From the blog post, yet again...

One piece of advice: peer dependency requirements, unlike those for regular dependencies, should be lenient. You should not lock your peer dependencies down to specific patch versions. It would be really annoying if one Chai plugin peer-depended on Chai 1.4.1, while another depended on Chai 1.5.0, simply because the authors were lazy and didn’t spend the time figuring out the actual minimum version of Chai they are compatible with.

4
  • I still don't get the argument that the plugin does not depend but expects the host package -- what is the difference, really? If it's just that the plugin does not require/import the host lib then that seems like a technicality, one could still say the plugin depends on it, clearly it still depends on (by implementing) the interface defined by it. Commented Sep 12, 2023 at 8:41
  • @AloisMahdal You're using human logic & definitions for those words, but we have to be specialized here. If libDependsV2 depends on libRequirement V3, in npm-land, libRequirementV3 will be installed if libDependsV2 is in package.json. We don't want that with plugins. Key is this quote: "If you don't have the host, the plugin harmlessly does nothing." If the plugin didn't "fail gracefully", we would have an issue. But the plugin expects a peer relationship and "comes alive" if [and only if] a compatible host is found. Otherwise you end up with the management issues I describe, above.
    – ruffin
    Commented Sep 12, 2023 at 15:51
  • Look back over the ... but the plugin doesn't depend on the host... section. It's a fine (qua "small") distinction, and you could write a "plugin" that used conventional dependencies if you wanted, but that tight coupling is what peerDependencies tries to work around. That is, your scenario is already handled, but what can we do if we don't want to use tightly coupled dependencies? We'd get a lot more flexibility, but npm could no longer automate the enforcement of that relationship. If that works for what you'd like to accomplish, peerDependencies lets you do it.
    – ruffin
    Commented Sep 12, 2023 at 15:57
  • Finally, the blog makes a good point here: "One piece of advice: peer dependency requirements, unlike those for regular dependencies, should be lenient." What peerDependencies does for you is allow an "out of spec" plugin to stick around even when libRequirementV4 is released. If it libDependsV2 automagically works with the new version, perfect! But since we've told npm, "this isn't a relationship for you to enforce", npm can only "alert you to the situation, and let you figure out if HostLibraryX v4 is a suitable peer for Plugin v1."
    – ruffin
    Commented Sep 12, 2023 at 16:04
26

A simple explanation that made it more clear to me is:

When you deploy your app, modules in dependencies need to be installed or your app won't work. Modules in devDependencies don't need to be installed on the production server since you're not developing on that machine. link

3
  • 3
    So, if we are making website and in prod version all libs will be inlined into vendor.js, all our deps should be dev deps if compiled code is commited into the repo? And it should be commited, as otherwice it's strange that you have to compile module, not just install it (and testing is also somewhere here as any change in submodules can lead to regression)...
    – Qwertiy
    Commented Oct 2, 2017 at 10:04
  • Awesome answer, but there is a question? Does possible Webpack build a corrupted bundle? My guess is devDependencies packages will not work in product version, webpack -p I mean. please answer my question.
    – AmerllicA
    Commented Nov 29, 2017 at 10:18
  • If there is any issue while production build, your deployment process should be designed in a way that it shows error at build time and does not push corrupted code to production(e.g. you can try Jenkins). Devdependencies anyways are not required to be installed on production server. Commented Dec 4, 2017 at 16:04
25

I found a simple explanation.

Short Answer:

dependencies "...are those that your project really needs to be able to work in production."

devDependencies "...are those that you need during development."

peerDependencies "if you want to create and publish your own library so that it can be used as a dependency"

More details in this post: https://code-trotter.com/web/dependencies-vs-devdependencies-vs-peerdependencies

1
  • Top answer are pretty descriptive and detailed but this answer ELI5'd peerDependencies for me. Commented Feb 9, 2021 at 8:54
21

I'd like to add to the answer my view on these dependencies explanations

  • dependencies are used for direct usage in your codebase, things that usually end up in the production code, or chunks of code
  • devDependencies are used for the build process, tools that help you manage how the end code will end up, third party test modules, (ex. webpack stuff)
1
  • What about css assets? Commented Mar 28, 2019 at 1:13
12

In short

  1. Dependencies - npm install <package> --save-prod installs packages required by your application in production environment.

  2. DevDependencies - npm install <package> --save-dev installs packages required only for local development and testing

  3. Just typing npm install installs all packages mentioned in the package.json

so if you are working on your local computer just type npm install and continue :)

7

dependencies: packages that your project/package needs to work in production.

devDependencies: packages that your project/package needs to work while development but are not needed on production (eg: testing packages)

peerDependencies: packages that your project/package needs to work in tandem with (“colaborating” with them) or as a base, useful mainly when you are developing a plugin/component to let know with which version of the “main” package your plugin/component is supposed to work with (eg: React 16)

5

Dependencies

These are the packages that your package needs to run, so they will be installed when people run

 npm install PACKAGE-NAME

An example would be if you used jQuery in your project. If someone doesn't have jQuery installed, then it wouldn't work. To save as a dependency, use

 npm install --save

Dev-Dependencies

These are the dependencies that you use in development, but isn't needed when people are using it, so when people run npm install, it won't install them since the are not necessary. For example, if you use mocha to test, people don't need mocha to run, so npm install doesn't install it. To save as a dev dependency, use

npm install PACKAGE --save-dev

Peer Dependencies

These can be used if you want to create and publish your own library so that it can be used as a dependency. For example, if you want your package to be used as a dependency in another project, then these will also be installed when someone installs the project which has your project as a dependency. Most of the time you won't use peer dependencies.

3

When trying to distribute an npm package you should avoid using dependencies. Instead you need to consider adding it into peerDependencies.

Update

Most of the time dependencies are just a bunch of libraries that describes your ecosystem. Unless, you're really using a specific version of a library you should instead let the user choose whether or not to install that library and which version to choose by adding it into the peerDependencies.

4
  • 2
    Please add some explanation to your answer such that others can learn from it - why exactly should using the dependencies be avoided?
    – Nico Haase
    Commented Jun 30, 2020 at 6:53
  • Most of the time dependencies are just a bunch of libraries that describes the ecosystem. Unless, you're really using a specific version of a library you should let the user choose whether or not to install that library and which version to choose by adding it into the peerDependencies instead.
    – Melchia
    Commented Nov 8, 2021 at 15:08
  • Please add all clarification to your answer by editing it
    – Nico Haase
    Commented Nov 8, 2021 at 15:16
  • @NicoHaase Let me know if you have any questions
    – Melchia
    Commented Nov 8, 2021 at 15:27
3

When using Webpack to bundle a frontend application, the distinction between dependencies and devDependencies is not so clear. For the final bundle, it doesn't matter where you place the dependencies (but it may be important for other tools). That's why the documentation seems confusing.

I found the explanation here: Do "dependencies" and "devDependencies" matter when using Webpack?

1

dependencies are required to run, devDependencies only to develop

1
  • An answer which basically proposes the same solution as an existing answer can theoretically still be a valuable contribution, if it explains more, or from a different angle, or more understandably... But this post does not. Please do not expect users to find this post helpful.
    – Yunnosch
    Commented Apr 30, 2022 at 9:25

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.