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:
npm init -y
npm install bootstrap
npm install --save-dev sass
npm install -D esbuildThe resulting package.json, without the fields npm init adds:
{
"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:
--saveand-P(--save-prod) save todependencies, the same as no flag.-Pis also how you move a package fromdevDependenciesback todependencies.npm install -D bootstrapon a package that is already independenciesmoves it todevDependencies.--no-saveinstalls the package intonode_modulesbut leavespackage.jsonunchanged.
When are devDependencies installed?
- A plain
npm installornpm ciin your project folder installs both groups. npm install --omit=devornpm ci --omit=devinstalls onlydependencies. 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_ENVenvironment variable is set toproduction, npm omitsdevDependenciesby default. It doesn’t warn you: the install finishes normally, just without your build tools. Add--include=devto install them anyway. - When someone installs your package in their project, they get its
dependenciesbut never itsdevDependencies. That’s why test and build tools don’t belong independencies: 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/scriptsgo indevDependencies. The @wordpress/scripts docs install it withnpm 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:
{
"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.
Related articles
- front-end npm commands that use both flags: Sass as a dev dependency, Bootstrap and Font Awesome as dependencies
- how SCSS partials work: what Sass does with the files it compiles
