Create a new package.json file.

npm init              # interactive prompts
npm init -y           # accept all defaults
npm init @scope       # use an initializer package

-y is the fastest way to start a new project.

The most important fields in your package.json.

{
  "name": "my-app",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest"
  },
  "dependencies": {},
  "devDependencies": {},
  "engines": { "node": ">=18" }
}

Set "type": "module" to use ES module import/export syntax.

How npm version numbers work: MAJOR.MINOR.PATCH.

1.2.3
│ │ └── patch: bug fixes (backward compatible)
│ └──── minor: new features (backward compatible)
└────── major: breaking changes
In package.json
“^1.2.3”   → allows 1.x.x  (minor + patch updates)
“~1.2.3”   → allows 1.2.x  (patch updates only)
“1.2.3”    → exact version only

^ (caret) is the default and usually what you want.

Install all dependencies from package.json.

npm install               # install everything
npm i                     # shorthand

Creates node_modules/ and package-lock.json. Always commit the lock file.

Add a package as a dependency.

npm install express                # production dependency
npm install -D vitest              # devDependency (--save-dev)
npm install -g typescript          # global install
npm install express@4.18.2         # specific version
npm install @scope/package         # scoped package

Use -D for tools only needed during development (linters, test runners, bundlers).

Remove a package.

npm uninstall express
npm uninstall -D vitest        # remove from devDependencies
npm uninstall -g typescript    # remove global package

Also removes it from package.json and package-lock.json.

Clean install from lock file. Ideal for CI/CD pipelines.

npm ci

Deletes node_modules/ first, then installs exact versions from package-lock.json. Faster and more reliable than npm install in automated environments.

Update packages to the latest allowed version per semver range.

npm update                # update all
npm update express        # update one package

This respects the ^ or ~ ranges in your package.json.

Check which packages have newer versions available.

npm outdated

Shows current, wanted (within semver range), and latest versions. Red = needs update.

View installed packages.

npm list               # full dependency tree
npm list --depth=0     # top-level only
npm list -g --depth=0  # global packages
npm list express       # check specific package

View registry info about a package.

npm info express
npm info express version       # latest version only
npm info express versions      # all published versions

Run a script defined in package.json.

npm run dev
npm run build
npm run test
npm run lint -- --fix     # pass args to the script

Built-in shortcuts: npm start, npm test, npm stop don't need run.

Run a package binary without installing it globally.

npx create-react-app my-app
npx create-next-app@latest
npx tsc --init
npx eslint .
npx -p node@18 node -v    # run with specific Node version

Downloads and runs the package temporarily. Great for one-off commands and scaffolding tools.

npm automatically runs pre and post scripts.

{
  "scripts": {
    "prebuild": "rm -rf dist",
    "build": "tsc",
    "postbuild": "cp package.json dist/"
  }
}

prebuild runs before build, postbuild runs after.

Check for known vulnerabilities in your dependencies.

npm audit                  # show vulnerabilities
npm audit fix              # auto-fix what's possible
npm audit fix --force      # fix even with breaking changes
npm audit --json           # machine-readable output

Run this regularly and before deploying to production.

Manage the local package cache.

npm cache clean --force    # clear the cache
npm cache verify           # check cache integrity

Clearing the cache can fix weird install issues.

Publish your package to the npm registry.

npm login                          # authenticate
npm publish                        # publish public package
npm publish --access public        # scoped package as public
npm version patch                  # bump 1.0.0 → 1.0.1
npm version minor                  # bump 1.0.0 → 1.1.0
npm version major                  # bump 1.0.0 → 2.0.0

npm version updates package.json and creates a git tag.

Create a tarball of your package without publishing.

npm pack                   # creates .tgz file
npm pack --dry-run         # preview what would be included

Useful for testing what your package looks like before publishing.

Control which files are included in your published package.

# .npmignore (like .gitignore for npm)
src/
tests/
*.test.js
Or use “files” in package.json (allowlist approach)
{
“files”: [“dist”, “README.md”]
}

The files field is preferred — it’s an allowlist instead of a blocklist.

Manage multiple packages in one repository.

# Root package.json
{
  "workspaces": ["packages/*"]
}
Install all workspace dependencies
npm install
Run a script in a specific workspace
npm run build -w packages/ui
Run a script in all workspaces
npm run build —workspaces

Workspaces share a single node_modules at the root, saving disk space and ensuring consistency.

Symlink a local package for development.

# In the library you're developing
npm link
In the project that uses it
npm link my-library
Remove the link
npm unlink my-library

Changes to the linked package are reflected immediately — no need to reinstall.