A friendly guide to `npm install` flags

Note: this guide is current as of npm version 9.8.0.

The npm install command is a critical tool for managing your Node.js project’s dependencies. It provides several options or "flags" that you can use to customize its behavior. In this blog post, we’re going to break down those flags to make them easier to understand, and provide examples when needed.

Saving flags: choosing how and where to save

  1. -S, --save: This flag saves the installed package into a list called dependencies in your package.json file. For example, npm install express --save would save Express as a needed package for your Node.js application.
  2. --no-save: Stops the package from being saved into dependencies.
  3. --save-prod: Similar to -S, --save, it adds the package to the dependencies list.
  4. --save-dev or -D: Installs packages that are only needed when you’re developing your project, but not when users are running the software. This flag will install dependencies into the devDependencies list in your application. Example: npm install jest --save-dev would save Jest as a development only dependency.
  5. --save-optional or -O: Adds packages that aren’t necessary for your project but might enhance it. The crucial difference is if these can’t be installed, npm install won’t fail.
  6. --save-peer: Puts the package into peerDependencies, a list of packages that your software needs to work but that you expect users to install themselves.
  7. --save-bundle or -B: This packages up certain dependencies with your application when it’s time to deploy it.
  8. -E, --save-exact: Handy if you want to make sure everyone is working with or using the exact same version of a dependency, no newer versions allowed.

Installing packages just for you or for everyone

  • -g, --global: If you want to use a package in lots of projects, you might install it globally, meaning it gets installed in a special place that all your Node.js projects can reach.

How should npm install your packages?

  • --install-strategy <hoisted|nested|shallow|linked>: Sometimes, you have control over how npm organizes these dependencies when they’re installed. This flag lets you make that choice. Here’s what these options mean:
    • hoisted: Your packages get installed at the highest possible level in the node_modules folder.
    • nested: Keeps different versions of each package separate from each other.
    • shallow: Limits the amount of nesting that npm does.
    • linked: Symlinks packages from a global cache, helping to save disk space.

Older npm versions and global style

  • --legacy-bundling: Make sure that older npm versions can work with the installed modules.
  • --global-style: Replicates the folder structure that global install would produce, in your local node_modules directory.

Choosing what type of dependencies to skip

  • --omit <dev|optional|peer>: If you don’t want to install certain types of dependencies when you run npm install, this flag can help. For example, if you don’t want to install the dev and optional dependencies, you might run: npm install --omit dev optional.

Get strict with peer dependencies

  • --strict-peer-deps: Don’t let the installation process finish unless all dependencies are correctly installed.

I hope you find this guide helpful to understand npm install flags. Remember, the best way to learn is by doing, so don’t hesitate to experiment with these flags in your projects.