Understand and Manage package-lock.json

Beginner8 min

Master the package-lock.json file to ensure reproducible installs, resolve merge conflicts, and maintain a healthy dependency tree.

Prerequisites

-Node.js and npm installed

Steps

Generate a fresh lockfile

Create or regenerate package-lock.json from package.json.

$ npm install

The lockfile pins exact versions of every package in the dependency tree. Always commit it to version control.

Install from lockfile only (CI mode)

Use npm ci for clean, reproducible installs in CI pipelines.

$ npm ci

npm ci deletes node_modules and installs exactly what is in package-lock.json. It fails if the lockfile is out of sync with package.json.

Check for outdated packages

See which dependencies have newer versions available.

$ npm outdated

Update a specific package

Update one dependency and its lockfile entry.

$ npm update lodash

npm update respects semver ranges in package.json. To jump to a new major version, use 'npm install lodash@latest'.

Verify lockfile integrity

Check that the lockfile matches the installed node_modules.

$ npm ls --all 2>&1 | grep -E '(WARN|ERR|invalid|missing)' || echo 'Dependency tree is clean'

Full Script

full-script.sh

#!/bin/bash
# npm Lockfile Health Check
set -euo pipefail

echo "=== Lockfile Status ==="
if [ -f "package-lock.json" ]; then
  LOCK_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('package-lock.json','utf8')).lockfileVersion)")
  echo "Lockfile version: $LOCK_VERSION"
  echo "File size: $(du -h package-lock.json | cut -f1)"
else
  echo "No package-lock.json found!"
  exit 1
fi

echo ""
echo "=== Dependency Counts ==="
TOTAL=$(npm ls --all --json 2>/dev/null | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));const count=(obj)=>obj.dependencies?Object.keys(obj.dependencies).length+Object.values(obj.dependencies).reduce((a,v)=>a+count(v),0):0;console.log(count(d))" 2>/dev/null || echo "unknown")
echo "Total packages in tree: $TOTAL"

echo ""
echo "=== Outdated Packages ==="
npm outdated 2>/dev/null || echo "All packages are up to date"

echo ""
echo "=== Tree Integrity ==="
npm ls --all 2>&1 | grep -cE '(ERR|invalid|missing|WARN)' | xargs -I{} echo "{} issues found" || echo "No issues found"

echo ""
echo "=== Commands ==="
echo "Clean install (CI): npm ci"
echo "Update all:         npm update"
echo "Update one:         npm update <package>"
echo "Rebuild lockfile:   rm package-lock.json && npm install"

FAQ

Discussion

Loading comments...

#!/bin/bash # npm Lockfile Health Check set -euo pipefail echo "=== Lockfile Status ===" if [ -f "package-lock.json" ]; then LOCK_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('package-lock.json','utf8')).lockfileVersion)") echo "Lockfile version: $LOCK_VERSION" echo "File size: $(du -h package-lock.json | cut -f1)" else echo "No package-lock.json found!" exit 1 fi echo "" echo "=== Dependency Counts ===" TOTAL=$(npm ls --all --json 2>/dev/null | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));const count=(obj)=>obj.dependencies?Object.keys(obj.dependencies).length+Object.values(obj.dependencies).reduce((a,v)=>a+count(v),0):0;console.log(count(d))" 2>/dev/null || echo "unknown") echo "Total packages in tree: $TOTAL" echo "" echo "=== Outdated Packages ===" npm outdated 2>/dev/null || echo "All packages are up to date" echo "" echo "=== Tree Integrity ===" npm ls --all 2>&1 | grep -cE '(ERR|invalid|missing|WARN)' | xargs -I{} echo "{} issues found" || echo "No issues found" echo "" echo "=== Commands ===" echo "Clean install (CI): npm ci" echo "Update all: npm update" echo "Update one: npm update <package>" echo "Rebuild lockfile: rm package-lock.json && npm install"