npm save vs save-dev: dependencies and devDependencies

Quick Summary

  • npm install --save-dev, or -D, adds a package to devDependencies for build and test tools; a plain npm install saves to dependencies, the same as --save, which has been the default since npm 5.
  • devDependencies are skipped by npm install --omit=dev, by any install while NODE_ENV is production, and when someone installs your package in their project.
  • In a WordPress theme, Sass, bundlers and @wordpress/scripts go in devDependencies, so build before you deploy or install them for the build step with --include=dev.

npm install --save adds a package to dependencies in your package.json: the packages your code needs when it runs. npm install --save-dev, or its short form -D, adds it to devDependencies: tools you only need while developing, testing or building, such as Sass, a bundler or a linter. Since npm 5, a plain npm install <package> saves to dependencies, so you no longer need to type --save.

What does each flag write to package.json?

These commands were run in an empty folder with npm 12.1, the current release, and with npm 11.16. Both gave the same result:

Shell
npm init -y
npm install bootstrap
npm install --save-dev sass
npm install -D esbuild

The resulting package.json, without the fields npm init adds:

JSON
{
  "dependencies": {
    "bootstrap": "^5.3.8"
  },
  "devDependencies": {
    "esbuild": "^0.28.2",
    "sass": "^1.105.0"
  }
}

The version numbers are whatever is current when you install. The caret (^) allows later minor and patch releases; add -E (--save-exact) to save the exact version instead.

The other flags you may meet:

  • --save and -P (--save-prod) save to dependencies, the same as no flag. -P is also how you move a package from devDependencies back to dependencies.
  • npm install -D bootstrap on a package that is already in dependencies moves it to devDependencies.
  • --no-save installs the package into node_modules but leaves package.json unchanged.

When are devDependencies installed?

  • A plain npm install or npm ci in your project folder installs both groups.
  • npm install --omit=dev or npm ci --omit=dev installs only dependencies. In the project above, that installed Bootstrap and @popperjs/core (Bootstrap’s peer dependency, which npm adds on its own) and skipped Sass and esbuild.
  • When the NODE_ENV environment variable is set to production, npm omits devDependencies by default. It doesn’t warn you: the install finishes normally, just without your build tools. Add --include=dev to install them anyway.
  • When someone installs your package in their project, they get its dependencies but never its devDependencies. That’s why test and build tools don’t belong in dependencies: every user of the package would download them.

--production is the old flag for skipping devDependencies. It still works in npm 12 but prints npm warn config production Use `--omit=dev` instead. The npm config docs list omit, include and the deprecated production option.

Which packages belong in devDependencies?

Tools you only use to build, test or check your code: compilers such as TypeScript and Sass, bundlers such as esbuild or webpack, PostCSS and Autoprefixer, test runners and linters. TypeScript is a good example: once your code is compiled to JavaScript, the deployed app no longer needs the compiler.

If your code loads a package while it runs, or the package’s code ends up in the files you ship, it belongs in dependencies.

What goes where in a WordPress theme build?

A WordPress theme or plugin usually keeps its package.json in its own folder and uses npm only to compile the CSS and JavaScript that WordPress enqueues. Nothing in node_modules runs on the server; WordPress loads the compiled files. So:

  • Sass, esbuild or webpack, PostCSS, Autoprefixer, linters and @wordpress/scripts go in devDependencies. The @wordpress/scripts docs install it with npm install @wordpress/scripts --save-dev.
  • Libraries whose code ends up in your compiled files, such as Bootstrap or Font Awesome, go in dependencies. In a theme this mostly tells the next developer what reaches visitors, but it matters as soon as anyone installs with --omit=dev.

A small theme setup that compiles a stylesheet with Sass and a script with esbuild:

JSON
{
  "name": "my-theme",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "build:css": "sass src/scss/style.scss assets/css/style.css --style=compressed --no-source-map",
    "build:js": "esbuild src/js/main.js --bundle --minify --outfile=assets/js/main.js",
    "build": "npm run build:css && npm run build:js"
  },
  "dependencies": {
    "bootstrap": "^5.3.8"
  },
  "devDependencies": {
    "esbuild": "^0.28.2",
    "sass": "^1.105.0"
  }
}

With src/js/main.js importing one Bootstrap component (import Collapse from 'bootstrap/js/dist/collapse';), npm run build writes assets/css/style.css and an 18.1 KB assets/js/main.js for the theme to enqueue. "private": true makes npm refuse to publish the theme by accident. For the SCSS side, see how to organize SCSS files.

The problem people hit: a server or deploy pipeline runs npm ci --omit=dev, or has NODE_ENV=production set, and then runs npm run build. The build stops at its first step because the sass command was never installed. Either build before you deploy and upload only the compiled files, or install everything for the build step with npm ci --include=dev. Either way, node_modules doesn’t need to be on the live server.

Frequently asked questions

Do I still need to type --save?

No. npm 5.0.0 (May 2017) made saving the default: its release notes say “--save is no longer necessary. All installs will be saved by default.” --save still works and does the same as no flag.

Why does npm warn about install scripts when I add esbuild?

npm 11.16 and later list dependencies whose install scripts you haven’t approved, and npm 12 skips those scripts until you do. Installing the theme setup above with npm 12.1 blocked the scripts of esbuild and @parcel/watcher (an optional dependency of Sass), and both tools still built the files. If a package really needs its script, approve it with npm install-scripts approve <package> in npm 12 (npm approve-scripts <package> in npm 11). The approval is saved in the allowScripts field of package.json. See the npm install-scripts docs.

Share on X (opens in a new tab) Share on LinkedIn (opens in a new tab) Share on Facebook (opens in a new tab)

ChatGPT (opens in a new tab) Claude (opens in a new tab) Gemini (opens in a new tab) Perplexity (opens in a new tab) Grok (opens in a new tab)

More Insights

See More