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?
EDIT also added peerDependencies, which is closely related and might cause confusion.
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:
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.
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.
If you do not want to install devDependencies you can use npm install --production
As an example, mocha would normally be a devDependency, since testing isn't necessary in production, while express would be a dependency.
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
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
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.
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
├── HostLibraryX#4.0.0
└─┬ PluginX#1.0.0
└── HostLibraryX#3.0.0
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.
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
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
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)
In short
Dependencies - npm install <package> --save-prod installs packages required by your application in production environment.
DevDependencies - npm install <package> --save-dev installs
packages required only for local development and testing
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 :)
Dependencies vs dev dependencies
Dev dependencies are modules which are only required during development whereas dependencies are required at runtime. If you are deploying your application, dependencies has to be installed, or else your app simply will not work. Libraries that you call from your code that enables the program to run can be considered as dependencies.
Eg- React , React - dom
Dev dependency modules need not be installed in the production server since you are not gonna develop in that machine .compilers that covert your code to javascript , test frameworks and document generators can be considered as dev-dependencies since they are only required during development .
Eg- ESLint , Babel , webpack
#FYI,
mod-a
dev-dependents:
- mod-b
dependents:
- mod-c
mod-d
dev-dependents:
- mod-e
dependents:
- mod-a
----
npm install mod-d
installed modules:
- mod-d
- mod-a
- mod-c
----
checkout the mod-d code repository
npm install
installed modules:
- mod-a
- mod-c
- mod-e
If you are publishing to npm, then it is important that you use the correct flag for the correct modules. If it is something that your npm module needs to function, then use the "--save" flag to save the module as a dependency. If it is something that your module doesn't need to function but it is needed for testing, then use the "--save-dev" flag.
# For dependent modules
npm install dependent-module --save
# For dev-dependent modules
npm install development-module --save-dev
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.
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)
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.
dependencies are required to run, devDependencies only to develop
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?
I'm a little confused as to why I can't get my Gruntfile.js to run, here's the rub:
I installed grunt globally using npm. It lives in my /usr/local/bin/ directory, here it is:
Previously, I'd installed node.js using homebrew, then grunt with npm. Other issues led me to uninstall node via homebrew & reinstall node directly from the disk image node provides.
In my web project's index, there's a Gruntfile.js script that rebuilds my jekyll site everytime live-reload updates. When I run grunt, I get this message:
What I'm trying to wrap my head around:
Why isn't /usr/local/bin/grunt a valid path? Grunt exists at that location. My guess was that running grunt locally, from within my website's index, would fix things.
There's a node_modules folder there & everything was working fine before after all. I found this link, and tried running \grunt to bypass the bash alias, but that had no effect.
Any advice/suggestions are much appreciated! I feel like an imbecile using things, breaking things & not understanding why/how. Eager to finish my project, get a paycheck & finally have time to learn the ins and outs of terminal, bash & popular package managers so I don't run into these sorts of problems...
After discussion with OP, I find this is a Node.js environment issue. After install - do something - uninstall - reinstall in another way - do something, somehow, when npm install -g XXX is executed, the symbolic link is created and point to some place, but the package is installed some where else. That's why OP see /usr/local/bin/grunt but cannot run it.
I've recommended OP to clean up all Node.js stuff, make a clean environment and start right from the beginning.
I use Node.js (via browserify) for each of my web apps, all of which have some dependencies in common and others specific to themselves. Each of these apps has a package.json file that specifies which versions of which modules it needs.
Right now, I have a /node_modules directory in the parent folder of my apps for modules that they all need to reference, and then I put app-specific modules in a node_modules folder in that app's directory. This works fine in the short term, since my require() statements are able to keep looking upward in the file structure until they find the node_modules directory with the correct app in it.
Where this gets tricky is when I want to go back to an old project and run npm install to make sure it can still find all the dependencies it needs. (Who knows what funny-business has occurred since then at the parent directory level.) I was under the impression that npm install did this:
for each module listed in package.json, first check if it's present, moving up the directory the same way require does. If it's not, install it to the local node_modules directory (creating that directory if necessary).
When I run npm install inside an app folder, however, it appears to install everything locally regardless of where else it may exist upstream. Is that the correct behavior? (It's possible there's another reason, like bad version language in my package.json). If this IS the correct behavior, is there a way for me to have npm install behave like the above?
It's not a big deal to widely replicate the modules inside every app, but it feels messy and prevents me from make small improvements to the common modules and not having to update every old package.json file. Of course, this could be a good thing...
When I run npm install inside an app folder, however, it appears to install everything locally regardless of where else it may exist upstream. Is that the correct behavior? (It's possible there's another reason, like bad version language in my package.json). If this IS the correct behavior, is there a way for me to have npm install behave like the above?
Yes, that is what npm install does. In node.js code, the require algorithm has a particular sequence of places it looks, including walking up the filesystem. However, npm install doesn't do that. It just installs in place. The algorithms it uses are all constrained to just a single node_modules directory under your current directory and it won't touch anything above that (except for with -g).
It's not a big deal to widely replicate the modules inside every app, but it feels messy and prevents me from make small improvements to the common modules and not having to update every old package.json file. Of course, this could be a good thing...
Yeah basically you're doing it wrong. The regular workflow scales well to the Internet. For your use case it creates some extra tedious work, but you can also just use semantic versioning as intended and specify "mylib": "^1.0.0" in your package.json for your apps and be OK with automatically getting newer versions next time you npm install.
I'm building a Node module with devDependencies that should be globally installed, such as jasmine-node and jshint. What I essentially need is to be able to reference their binaries in my makefile / npm scripts section to run tests, lint, etc. In other words I do not wish to require() them programmatically.
After digging around I'm still confused on how to handle this:
1) My first approach was to assume that these modules would be globally installed, clarify this in my module's documentation and reference their binaries as globals - i.e. expect them to be globally available. This conflicts with this piece of advice
Make sure you avoid referencing globally installed binaries. Instead, point it to the local node_modules, which installs the binaries in a hidden .bin directory. Make sure the module (in this case "mocha") is in your package.json under devDependencies, so that the binary is placed there when you run npm install.
(taken from this post)
This generally sounds right, as the aforementioned setup is rather fragile.
2) My next approach was explicitly including those modules in devDependencies (although they are still globally installed on my system (and most probably on users' & contributors' systems as well)). This ensures that appropriate versions of the binaries are there when needed and I can now reference them through node_modules/.bin/.
However I'm now in conflict with this piece of advice
Install it locally if you're going to require() it.
(taken from npm docs)
Regardless of that, I do notice that npm install will now actually fetch nothing (display no network activity) for the globally installed modules.
My questions:
Are the local versions of globally installed modules (that are mentioned in devDependencies) just snapshots (copies) of the global ones, taken during npm install?
Is 2) the correct way to go about doing this? or is there some other practice I'm missing?
Here's my personal take on this, which is decidedly divergent from node.js common practice, but I believe it is an overall superior approach. It is detailed in my own blog post (disclaimer about self-promotion, yada yada) Managing Per-Project Interpreters and the PATH.
It basically boils down to:
Never use npm -g. Never install global modules.
Instead, adjust your PATH to include projectDir/node_modules/.bin instead
Revisiting my own question a couple of years after it was originally written, I feel I can now safely say that the quoted 'advice'
Install it locally if you're going to require() it.
does not stand anymore. (It was part of the npm docs but the posted 2-year old link gives me a 404 at the time of this writing.)
Nowadays, npm run is a fine way to do task management / automation and it'll automatically export modules which are installed locally, into the path before executing. Thus, it makes perfect sense to locally install modules that are not to be require()d such as linters and test-runners. (By the way, this is completely in line with the answer that Peter Lyons provided a couple of years ago - it may have been 'decidedly divergent from node.js common practice' back then, but it's pretty much widely accepted today :))
As for my second question
Are the local versions of globally installed modules (that are mentioned in devDependencies) just snapshots (copies) of the global ones, taken during npm install?
I am pretty confident that the answer is No. (Perhaps the lack of network activity that I was observing back then, during the installation of local modules which were also globally installed was due to caching..?)
Note, Nov 12 2016
The relevant npm docs to which the original question linked have moved here.