📖 Guide
npm — Complete Reference
Complete npm cheat sheet — package management, scripts, publishing, and configuration.
84 commands across 10 categories
Package ManagementScriptsPublishingConfigurationWorkspacesSecuritynpxCommon Commandspackage.json FieldsTips & Tricks
Package Management
| Command | Description |
|---|---|
npm install | Install all dependencies from package.json |
npm install express | Install a package as a dependency |
npm install -D typescript | Install a package as a devDependency |
npm install express@4.18.0 | Install a specific version |
npm uninstall lodash | Remove a package |
npm update | Update all packages to latest allowed by semver range |
npm outdated | Check for outdated packages |
npm ls | List installed packages (tree view) |
npm ls --depth=0 | List only top-level installed packages |
npm ci | Clean install from lockfile (faster, deterministic, for CI) |
Scripts
| Command | Description |
|---|---|
npm run dev | Run a custom script defined in package.json |
npm start | Run the 'start' script (shorthand, no 'run' needed) |
npm test | Run the 'test' script (shorthand) |
npm run build | Run the build script |
"preinstall": "echo before install" | Lifecycle hook: runs before npm install |
"postbuild": "echo done" | Lifecycle hook: runs after the build script |
npm run lint -- --fix | Pass arguments to a script using -- |
npm run dev & npm run watch | Run multiple scripts in parallel (shell) |
"scripts": { "dev": "next dev", "build": "next build" } | Define scripts in package.json |
Publishing
| Command | Description |
|---|---|
npm login | Authenticate to the npm registry |
npm publish | Publish the package to npm |
npm publish --access public | Publish a scoped package as public |
npm version patch | Bump patch version (1.0.0 → 1.0.1), commit, and tag |
npm version minor | Bump minor version (1.0.0 → 1.1.0) |
npm version major | Bump major version (1.0.0 → 2.0.0) |
npm pack | Create a tarball of the package (preview before publishing) |
npm deprecate my-pkg@1.0.0 "Use v2 instead" | Deprecate a published version |
npm unpublish my-pkg@1.0.0 | Unpublish a version (within 72h) |
Configuration
| Command | Description |
|---|---|
npm config list | Show current npm configuration |
npm config set registry https://registry.npmjs.org/ | Set the package registry URL |
npm config set init-author-name "Your Name" | Set default author for npm init |
.npmrce.g. registry=https://registry.npmjs.org/
save-exact=true | Project-level config file (also: ~/.npmrc for user-level) |
npm config get prefix | Show global installation prefix |
npm config set save-exact true | Save exact versions instead of ranges |
npm config delete proxy | Remove a config entry |
npm config edit | Open the config file in an editor |
Workspaces
| Command | Description |
|---|---|
"workspaces": ["packages/*"] | Define workspaces in root package.json |
npm install -w packages/shared | Install dependencies for a specific workspace |
npm run build -w packages/app | Run a script in a specific workspace |
npm run build --workspaces | Run a script in all workspaces |
npm run test --workspaces --if-present | Run script in workspaces that have it defined |
npm ls --workspaces | List dependencies across all workspaces |
npm install lodash -w packages/shared | Add a dependency to a specific workspace |
Security
| Command | Description |
|---|---|
npm audit | Check for known vulnerabilities in dependencies |
npm audit fix | Automatically fix vulnerabilities where possible |
npm audit fix --force | Fix vulnerabilities including breaking changes (semver major) |
npm audit --json | Output audit results as JSON |
npm audit signatures | Verify registry signatures of installed packages |
npm token list | List your active npm tokens |
npm token revoke <token> | Revoke an npm authentication token |
npx
| Command | Description |
|---|---|
npx create-next-app@latest | Run a package without installing it globally |
npx -y degit user/repo my-project | Skip confirmation prompt with -y flag |
npx --package=typescript tsc --init | Run a binary from a specific package |
npx -p node@18 node -v | Run a command with a specific Node.js version |
npx tsx script.ts | Execute TypeScript files directly |
npx serve dist | Quickly serve a static directory |
npx npm-check-updates -u | Update package.json versions to latest |
Common Commands
| Command | Description |
|---|---|
npm init -y | Create package.json with defaults |
npm init @scope | Run a scoped create package (e.g., npm init @eslint/config) |
npm info react | Show package metadata from the registry |
npm search express | Search the registry for packages |
npm link | Symlink a local package globally for development |
npm link my-lib | Use a globally linked package in the current project |
npm cache clean --force | Clear the npm cache |
npm doctor | Run diagnostics to check npm environment |
npm explain lodash | Show why a package is installed (dependency chain) |
package.json Fields
| Command | Description |
|---|---|
"name": "my-package" | Package name (must be unique on npm if publishing) |
"version": "1.0.0" | Semver version (major.minor.patch) |
"main": "dist/index.js" | Entry point for CommonJS (require) |
"module": "dist/index.mjs" | Entry point for ESM (import) |
"types": "dist/index.d.ts" | TypeScript type definitions entry |
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
}
} | Conditional exports map (modern approach) |
"files": ["dist", "README.md"] | Files included when package is published |
"engines": { "node": ">=18" } | Specify required Node.js version |
"private": true | Prevent accidental publishing to npm |
"overrides": { "semver": "7.5.4" } | Override transitive dependency versions |
Tips & Tricks
| Command | Description |
|---|---|
npm i express@latest | Install the absolute latest version |
npm i --save-exact react | Save exact version (no ^ or ~ prefix) |
npm i --legacy-peer-deps | Ignore peer dependency conflicts during install |
npm i --prefer-offline | Use cached packages when available |
npm pkg get version | Read a field from package.json |
npm pkg set scripts.dev="next dev" | Write a field to package.json from CLI |
npm diff --diff=lodash@4.17.20 --diff=lodash@4.17.21 | Show diff between two package versions |
npm exec --yes -- sort-package-json | Sort package.json fields alphabetically |
📖 Free, searchable command reference. Bookmark this page for quick access.