npm Reference

npm install reads package.json and installs the latest versions matching semver ranges, updating package-lock.json if versions change. npm ci deletes node_modules first, then installs exactly what is recorded in package-lock.json without any resolution — it fails if lock and package.json are out of sync. Use npm ci in CI/CD pipelines and Docker builds for reproducible, faster installs. Use npm install locally when you want to update or add packages.

dependencies are packages required at runtime when your code runs in production. devDependencies are only needed during development and build — type definitions, linters, test frameworks, bundlers, and compilers. When you run npm install in production with NODE_ENV=production or use npm install --production, devDependencies are skipped. Add runtime packages with npm i package and development tools with npm i -D package.

The caret ^ allows updates that do not change the leftmost non-zero digit. ^1.2.3 means >=1.2.3 <2.0.0 — any minor or patch update within major version 1. ^0.2.3 means >=0.2.3 <0.3.0 because 0 is the leftmost non-zero digit. The tilde ~ is more conservative: ~1.2.3 means >=1.2.3 <1.3.0, only allowing patch updates. Use --save-exact or set save-exact=true in .npmrc to omit the caret entirely.

npm install -g installs a package permanently to your global node_modules directory, adding its binaries to PATH. npx downloads and runs a package temporarily without installing it, then discards it. npx always fetches the latest version (or the specified version) from the registry, so you always get a fresh copy. Use npx for scaffolding tools like create-react-app or one-off CLI operations. Use -g for tools you run repeatedly like typescript or nodemon.

package-lock.json records the exact resolved version, download URL, and integrity hash of every installed package and its transitive dependencies. It ensures that npm ci will install the exact same dependency tree on any machine. You should always commit package-lock.json for applications — it is what makes builds reproducible. For libraries published to npm, there is a community debate, but the modern guidance is to commit it in your repository even for libraries.

Run npm audit to scan your installed dependencies against the npm advisory database and see a list of vulnerabilities with severity levels (critical, high, moderate, low). Run npm audit fix to automatically upgrade packages to their minimum safe version within your semver constraints. If a fix requires a breaking major version change, npm audit fix will tell you but will not apply it — use npm audit fix --force to apply major version upgrades, but review the changes carefully as they may break your code.

For any script named foo, npm automatically looks for prefoo and postfoo scripts and runs them before and after foo. For example, if you define prebuild, build, and postbuild in package.json scripts, running npm run build will execute all three in sequence. This is useful for cleaning build output before a build (prebuild: "rimraf dist") and for post-processing or notifications after a build completes. The lifecycle hooks also work for the built-in npm start and npm test commands.

Set the registry in .npmrc: registry=https://your-registry.example.com/. For scoped packages from a private registry, use @scope:registry=https://your-registry.example.com/. You can set .npmrc at the project level (committed) for non-sensitive settings or at the user level (~/.npmrc) for credentials. For authentication tokens, add //your-registry.example.com/:_authToken=${NPM_TOKEN} in .npmrc and set NPM_TOKEN as an environment variable so the token is never hardcoded.