A CLI tool to detect missing optional dependencies in package-lock.json
npm install @starcart.com/optional-deps-validate(note: this package is almost entirely written by AI)
> Validate that all optional dependencies declared by installed packages are present in package-lock.json.
This is a workaround for this npm issue.
When using Node.js and npm, certain packages declare OS- or architecture-specific sub-dependencies in their optionalDependencies. However, sometimes npm can generate a partial package-lock.json that excludes some or all of those optional deps. This can lead to problems on other machines or CI when npm fails to install required platform packages.
optional-deps-validate is a CLI tool that scans your local node_modules and compares each installed package's optionalDependencies against your package-lock.json. If any are missing, it warns you and exits with a non-zero status code.
``bash`
npm install -D @starcart.com/optional-deps-validateor
yarn add -D @starcart.com/optional-deps-validateor
pnpm add -D @starcart.com/optional-deps-validate
You can also install it globally:
`bash`
npm install -g @starcart.com/optional-deps-validateor
yarn global add @starcart.com/optional-deps-validateor
pnpm add -g @starcart.com/optional-deps-validate
Then run it using:
`bash`
npx @starcart.com/optional-deps-validate
Run the command in any project directory that has both a package-lock.json and a node_modules directory:
`bash`
cd /path/to/your/project
npx @starcart.com/optional-deps-validate
If everything is correct, you’ll see:
``
✅ All optional dependencies declared by installed packages appear in package-lock.json.
Otherwise, it will list warnings for each missing optional dependency and exit with status code 1.
`
⚠️ [Warning] Package "@swc/core" declares optional dependency "@swc/core-darwin-arm64" but it is NOT listed in package-lock.json
One or more optional dependencies are missing from package-lock.json!
`
1. Scans node_modules: Locates every installed package (including scoped packages) and reads its package.json.
2. Collects Optional Deps: For each package’s optionalDependencies, the tool records each optional dep name.
3. Parses package-lock.json: Gathers all package names listed in the lock file.
4. Compares: Any optional dep name that doesn’t appear in the lock file is flagged as missing.
* Prevent Partial Lockfiles: Whenever you suspect npm install might have generated an incomplete package-lock.json (for instance, if you re-installed without removing node_modules).npx optional-deps-validate` as part of your build or test pipeline to ensure the lockfile is fully consistent before merging changes.
* CI Enforcement: Add
MIT