Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For repeatable npm installs, commit both package.json and package-lock.json, then use npm ci in clean builds. Pinning exact versions in package.json is optional: the lockfile already records the project’s resolved dependency tree. Neither approach proves that a chosen release is safe, so pair reproducible installs with reviewed updates, vulnerability checks, and—when publishing—provenance verification.

What does pinning an npm dependency mean?

package.json specifies which dependency versions are acceptable. A spec such as ^1.2.3 is a range; an exact spec such as 1.2.3 narrows the manifest entry to that version. package-lock.json records the exact dependency tree npm generated for the project. npm describes the lockfile as a way for subsequent installs to generate identical trees despite intermediate dependency updates (npm package-lock.json documentation).

These are related but separate controls. Exact manifest entries express stricter version intent for direct dependencies. The lockfile captures resolved versions across the project’s dependency tree and should be committed whether your manifest uses exact versions or ranges.

Choose exact versions or ranges deliberately

Approach What it means Trade-off
Exact direct dependency version package.json records a specific version, for example "some-package": "1.2.3". It makes the direct dependency’s manifest intent stricter. Updates require an intentional manifest change.
Version range plus lockfile package.json permits a range, while the committed lockfile records the currently resolved tree. Ranges allow broader compatible resolution when you refresh the lockfile; review and commit that change deliberately.

Use npm install --save-exact (or npm install -E) when adding a dependency if your team wants npm to save an exact version in the manifest. This setting concerns newly saved direct-dependency specs; it does not replace committing the lockfile. npm documents these install options in its install command reference.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Commit the lockfile and use clean installs in automation

  1. Add or intentionally update dependencies: use npm install locally. Review any changes to both package.json and package-lock.json.
  2. Commit both files: the manifest records your declared specs, and the lockfile records the resolved tree for teammates, deployments, and CI.
  3. Use npm ci for clean automated builds: it requires a lockfile, removes an existing node_modules, and fails if the lockfile conflicts with the manifest. It does not write either file. See npm’s npm ci documentation.
  4. Keep install configuration aligned: if lockfile generation used tree-shaping options such as --legacy-peer-deps or --install-links, npm says those options must also be used with npm ci. A project-level .npmrc can preserve the setting for the project.

Use npm install for intentional dependency changes; unlike npm ci, it can update the lockfile when manifest specs and locked versions conflict. Lockfile behavior and formats depend on the npm generation, so check the project’s npm version when older projects or mixed environments are involved.

Review dependency changes and keep updates moving

A stable lockfile is useful only if the team continues to evaluate changes and security findings. Treat a lockfile diff as part of the code review surface rather than an opaque generated file.

  • Inspect additions, removals, and version changes. Identify which direct dependency prompted the change and whether its transitive dependencies changed too.
  • Use pull-request visibility. GitHub dependency review can surface dependency changes in pull requests so reviewers can investigate them. Dependabot can raise vulnerability alerts and propose update pull requests. See GitHub’s supply chain security overview.
  • Assess updates before merging. Automated proposals can save discovery effort, but compatibility and package behavior still need human review and appropriate tests.

Use npm audit as one security signal

npm audit checks dependencies against known vulnerability information; it does not establish that a package is trustworthy or harmless. npm documents that npm audit fix runs an install under the hood, and some findings require manual intervention or review rather than an automatic fix (npm audit documentation for CLI v6).

Review proposed fixes before applying them. In particular, a major-version change can alter behavior and warrants compatibility checks and testing. The cited audit reference is for legacy npm CLI v6 documentation, so confirm current command behavior and configuration against the npm version used by your project.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Why a lockfile does not eliminate supply-chain risk

A lockfile improves repeatability: it helps the project install the same resolved tree. It does not decide whether that tree is safe. It cannot guarantee a selected release is trustworthy, prevent package code from running during installation, or ensure that known vulnerabilities will be fixed.

Install behavior matters. npm documents lifecycle scripts, including prepare in certain installation and packaging contexts and in some Git dependency installs (npm scripts documentation). A frozen dependency tree is therefore not the same as an inert installation. Consider package behavior and installation context as part of dependency review.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

For npm publishers: consider trusted publishing and provenance

If your project publishes packages from supported CI, npm’s trusted publishing uses OpenID Connect (OIDC) to establish publishing identity without relying on a long-lived write token. npm’s current guide lists npm CLI 11.5.1+ and Node 22.14.0+ as prerequisites, and describes cloud-hosted support for GitHub Actions, GitLab CI/CD, and CircleCI. Automatic provenance availability is narrower: npm documents it for GitHub Actions and GitLab CI/CD under specified conditions. Provider, runner, and public-repository requirements matter, so check the current trusted publishing guide before configuring a workflow.

Provenance can provide links among a package, its source, build, and publisher for inspection; it is not proof that the package contains no malicious code. npm states this caveat in its provenance documentation. Consumers can inspect available attestations and use npm audit signatures to check registry signatures and provenance attestations; npm documents that this command requires npm CLI v9.5.0 or later.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

How the controls fit together

Control What it helps with What it does not establish
Exact manifest versions Stricter version intent for direct dependencies. That the chosen package version is safe.
Committed lockfile and npm ci Repeatable clean installs of the locked tree and detection of manifest/lockfile mismatch. That install scripts are harmless or the locked tree is vulnerability-free.
npm audit Known vulnerability findings and possible remediation paths. A complete assessment of package trust or behavior.
Signatures and provenance Integrity or origin/build evidence to inspect. Absence of malicious code.
Dependency review and update automation Visibility into changes and suggested updates. Compatibility or risk decisions without human assessment.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.