npm Scripts You're Probably Not Using (But Should Be)

Every JavaScript project has a package.json with a handful of scripts. Most stop at dev, build, and start. But npm scripts have a surprising amount of built-in power (lifecycle hooks, argument forwarding, cross-platform environment variables, parallel execution, and built-in package variables) that eliminates the need for separate tooling in many cases.

These eight patterns appear constantly in mature JavaScript projects but almost never make it into beginner tutorials. None of them require much setup: once you've seen them, you'll reach for them immediately.

Every script you write can carry pre and post hooks, but npm also defines its own lifecycle events that fire during install, pack, and publish. Knowing which event fires when is the difference between a hook that runs reliably and one that silently never executes.

The chain is flat, not recursive. npm runs prebuild, then build, then postbuild. It never looks for a preprebuild, so you cannot nest hooks inside hooks. If you need three ordered stages, chain them explicitly or use a serial runner.

Hooks do compose across script boundaries, though. If postbuild calls npm run upload, and upload has its own preupload hook, that hook runs too. Each npm run invocation starts a fresh hook cycle, which is how small primitives end up wiring themselves together without a build tool.

The event that surprises people is prepare. It runs on a bare npm install inside your own project, which makes it the correct home for developer setup rather than anything publish-related. It also runs for consumers who install your package straight from a git URL, which is why library authors use it to build from source.

That is exactly why Husky tells you to put its installer there. If you are wiring up git hooks alongside Prettier and lint-staged, our guide to setting up Husky, Prettier, and lint-staged in Next.js walks through the full configuration.

prepublish is the most misleading name in the npm lifecycle, and it is deprecated for good reason: despite the name, it does not run on npm publish. It runs on npm install and npm ci.

That is an accident of history rather than a design choice. Early npm ran prepublish both when publishing and when installing locally, so packages that used it to compile TypeScript recompiled on every contributor's machine, and packages that used it to run tests slowed down every install in the tree.

npm 4 split the behaviour into two clearly named hooks. Those are what you should use today.

The -- separator is an npm convention, not a universal one. If your team mixes package managers, or your README tells contributors one command while CI runs another, the difference bites quickly.

npm needs the separator because it parses unrecognised flags as its own configuration. npm run test --watch does not pass anything to Jest. npm reads --watch as a config value, sets npm_config_watch=true in the script environment, and runs test with no arguments at all. The suite runs once, exits, and nothing warns you that your flag disappeared.

Arguments always land at the end of the command. If your script is eslint src/ --max-warnings=0, then npm run lint -- --fix expands to eslint src/ --max-warnings=0 --fix. There is no way to inject a value into the middle of the command string.

When a command genuinely needs an argument in the middle, that is your signal to move it into a real script file that parses its own arguments.

Everything in this article cuts both ways. The same postinstall hook that lets you build a native module also lets any package anywhere in your dependency tree run arbitrary code the moment you type npm install.

That code runs with your user permissions, with network access, and with your environment variables in scope. That includes NPM_TOKEN, cloud credentials, and anything else your shell or CI runner exports. Self-replicating worms in the npm ecosystem have used precisely this path: the install script reads a publish token, then pushes a malicious version of every package that token can reach.

The number of packages that genuinely need an install script is small. Everything else in your node_modules is inherited risk you never agreed to.

We broke down how these campaigns actually work in npm postinstall attacks. If you want to check a specific project, the Lifecycle Hook Scanner risk-scores every install hook in a package.json without installing anything.

The tradeoff is real. Setting ignore-scripts=true also blocks your own prepare hook, so Husky will not register itself, and packages with genuine native builds fail at runtime instead of at install time. The workable pattern is to block everything by default and re-enable a short, reviewed allow-list with npm rebuild.

Before you add a runner, know what the shell already gives you. npm hands your script string to sh on macOS and Linux and to cmd.exe on Windows, so shell operators are available with the usual portability caveats.

The background-and-wait trick works, but it degrades badly. A failing background job does not reliably fail the whole script, output from both processes interleaves with no way to tell which line came from where, and pressing Ctrl+C often leaves orphaned processes holding your ports.

That is the gap npm-run-all and concurrently fill. You are not paying a dependency for parallelism itself. You are paying for labelled output, correct exit codes, clean shutdown, and Windows support.

npm does not simply execute your command string. It constructs an environment first, and several variables in it save you from writing glue code.

The most important one is invisible. npm prepends node_modules/.bin to PATH, which is why "lint": "eslint src/" works with no path prefix, and why the identical command fails when you paste it into a bare terminal.

npm_lifecycle_event unlocks a pattern worth knowing: point several hooks at the same Node.js file and branch inside it. One file, no duplicated logic, and the branching lives somewhere you can actually read it.

npm_config_* is the other half of the story. Any flag npm does not recognise becomes a config value, so npm run deploy --target=staging sets npm_config_target=staging inside the script. It is a crude named-argument mechanism, and it reaches places the -- form cannot.

Script configuration and application configuration are separate concerns. For .env file loading order, the NEXT_PUBLIC_ prefix, and build-time versus runtime resolution, see our guide to Next.js environment variables.

Every command in an npm script communicates exactly one thing back to npm: an exit code. Zero means success. Anything else means failure, and npm surfaces it as an ELIFECYCLE error along with the code the command returned.

This is the mechanism behind every gate in this article. prebuild blocks build because a failing tsc --noEmit exits non-zero. npm run lint && npm run build stops because ESLint exits 1 when it finds an error. Nothing is magic; it is all exit codes.

Two patterns come up constantly. The first is deliberately swallowing a failure, which is why Husky's own documentation suggests "prepare": "husky || true". In a CI container with no .git directory, Husky exits non-zero and would otherwise fail every install.

The second is --if-present, which makes npm exit 0 when the script is not defined instead of erroring. That is what lets a single shared CI workflow run npm run test --if-present across repositories where some have tests and some do not.

Your CI provider reads the same exit code your terminal does. If you are wiring these scripts into a pipeline, our GitHub Actions tutorial covers how a failing step propagates to the job result and how to cache dependencies between runs.

npm has built-in workspace support, and it extends to scripts. Declare your packages in the root package.json and every npm run command gains flags for targeting them.

Flag placement matters less than it looks. npm parses its own known flags first, so npm run build --workspaces passes --workspaces to npm rather than to your build command. Anything npm does not recognise still ends up as an npm_config_* variable.

What npm does not give you is a dependency graph. Workspace scripts run in resolution order, not topological order, and there is no caching between runs. If packages/ui must build before apps/web, npm will not work that out for you. That is the exact line where Turborepo, Nx, or pnpm's filter syntax start earning their configuration files.

cross-env fixes environment variables. It does not fix everything else that differs between a POSIX shell and cmd.exe, and contributors on Windows will find the rest within an hour.

npm also lets you choose the shell outright. Setting script-shell in .npmrc makes every script run under the shell you name. That is a reasonable move for a team that standardises on Git Bash or WSL, and a poor one for an open-source project where you cannot control contributor machines.

package.json is a JSON file, and JSON is a hostile place to write a program. No comments, no line breaks inside a string, escaped quotes everywhere, and no way to write a conditional a reviewer can follow at a glance.

There is a point where a clever one-liner costs more than it saves. These are reliable signals that you have passed it:

The replacement is deliberately boring. A file under scripts/ gets comments, real argument parsing, testable functions, and a stack trace when it fails.

parseArgs ships with Node.js 18.3 and later, so flag parsing no longer needs a dependency. Prefer setting process.exitCode = 1 over calling process.exit(1) so buffered output has a chance to flush before the process ends.

Keep the npm script as the entry point either way. The script name stays part of your project's public interface, and the implementation becomes something you can comment, test, and review.

A postbuild hook is also a good place to check what you are about to ship. Restricting or stripping source maps is a common one, since publishing them hands your original source to anyone who opens DevTools. See how source maps leak your source code for what to look for.

The naming convention pattern is worth pausing on. dev:*, build:*, db:* turns a flat list of scripts into self-documenting project structure: a new team member can read it and understand what the project does without asking.

Most of these patterns replace tools you might reach for separately: Makefiles for task composition, nodemon for file watching, dotenv CLI for environment injection. Check how much of that tooling your package.json scripts can handle before adding another dependency.