npm ci Lockfile Sync Errors
Problem
npm ci fails with EUSAGE error: “package.json and package-lock.json are in sync.” Lists many missing packages (tsx, esbuild, platform-specific @esbuild/ packages).
Root Cause
Someone edited package.json to add/update a dependency but didn’t run npm install locally to regenerate the lockfile before pushing. npm ci is strict — it refuses to reconcile differences (unlike npm install).
Why So Many Missing Packages
When a top-level dependency like tsx or esbuild is missing from the lockfile, the entire tree of platform-specific sub-packages (@esbuild/linux-x64, @esbuild/darwin-arm64, etc.) also becomes unresolvable.
Fix
# 1. Update lockfile locally
npm install
# 2. Verify strict install passes
npm ci
# 3. Commit the updated lockfile
git add package-lock.json
git commit -m "chore: sync lockfile"
git pushKey Differences
| Feature | npm install | npm ci |
|---|---|---|
| Purpose | Development / adding packages | CI pipelines / automated builds |
| Lockfile | Updates if needed | Must be in sync (fails otherwise) |
| node_modules | Modifies existing | Deletes and recreates from scratch |
| Speed | Slower (diffing) | Faster (optimized for fresh installs) |
Rule
Never manually edit package-lock.json. Always let the npm CLI generate it.
Related
- solopreneur-content-stack — Build pipeline context
- homelab-file-management-principles — Development workflow discipline