Lockfiles & Reproducible Installs

Lockfiles pin the exact dependency graph so laptops, CI, and production builds install identical packages every time.

Recipe

Quick-reference recipe card - copy-paste ready.

# Developer: update deps intentionally
npm install
git add package.json package-lock.json
 
# CI: reproducible clean install
npm ci

# .github/workflows/ci.yml (excerpt)
- run: npm ci
- run: npm test

When to reach for this:

• CI must not resolve new versions on every pipeline run.
• Production Docker builds need deterministic node_modules.
• Security audits must reference the same versions you ship.

Working Example

# Dockerfile - multi-stage API build
FROM node:24.18.0-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
 
FROM node:24.18.0-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:24.18.0-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json ./
CMD ["node", "dist/server.js"]

# Local verify: lockfile matches package.json
npm ci
npm test

What this demonstrates:

• npm ci deletes node_modules and installs exactly from package-lock.json.
• Docker deps stage uses --omit=dev for a smaller production image.
• Build stage runs full npm ci so devDependencies (TypeScript) are available to compile.

Deep Dive

How It Works

• package-lock.json (npm) records resolved versions, integrity hashes, and nested structure.
• npm install may update the lockfile when ranges allow newer compatible versions.
• npm ci fails if package.json and lockfile disagree, protecting CI from drift.
• pnpm uses pnpm-lock.yaml; Yarn uses yarn.lock - only one per repo.

Manager Commands

TypeScript Notes

{
  "scripts": {
    "verify:lockfile": "npm ci && npm run typecheck && npm test"
  }
}

• Run verify:lockfile after merging dependency PRs to catch missing native rebuilds.
• Commit lockfile changes in the same PR as package.json edits.

Gotchas

• Running npm install in CI - Resolves fresh versions and hides lockfile drift until production. Fix: use npm ci exclusively in pipelines.
• Partial lockfile commits - Updating package.json without the lockfile breaks teammates and CI. Fix: always commit both files together.
• Mixed managers - package-lock.json plus yarn.lock causes unpredictable installs. Fix: delete unused lockfiles; document the chosen manager in README.
• Lockfile merge conflicts - Manual edits corrupt integrity entries. Fix: regenerate with npm install after resolving package.json.
• Global cache masking issues - Stale CI caches serve old tarballs. Fix: key caches on lockfile hash; bust on lockfile change.

Alternatives

FAQs

rm -rf node_modules
npm install
git add package-lock.json

npm audit --audit-level=high

Related

• package.json Scripts - npm ci then npm test in CI
• Supply Chain: npm audit & Socket - audit the locked graph
• Package Managers Best Practices - one lockfile policy

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.