Yes. The npm before configuration, used with npm install, rebuilds the tree so that only versions available on or before a given date are installed. It can help you reproduce an older state or step back from a very new release, but it is not a replacement for a committed lockfile.
What the documentation says
npm's configuration reference describes the setting: if passed to npm install, it rebuilds the npm tree such that only versions that were available on or before the given time get installed. If no versions are available for the current set of direct dependencies, the command errors. If the requested version is a dist-tag and the tag does not pass the filter, the most recent version less than or equal to that tag is used. The page's example is that latest might install 1.2 even though latest is 2.0.
The documentation also lists a shorthand, enjoy-by, that maps to the same setting.
npm install --before=2026-09-01
The date there is only an example.
When it helps
- Reproducing an old build when you have no lockfile for that state, and want the closest available approximation.
- Stepping back from a very recent release while you wait to learn whether it is sound.
- Investigating a regression by asking what the tree looked like at a date.
Why it is not a lockfile
The date filter limits which versions are candidates. It does not record what was chosen. Two installs with the same date can still differ if dependency ranges permit different resolutions or if you run different npm versions. A lockfile, by contrast, records the exact tree. The npm documentation says package-lock.json describes the exact tree so later installs produce identical trees.
It also applies at the moment you run the command. It does not protect the next developer who runs a plain install on a project with no lockfile.
| Tool | Records the result | Reviewable in a pull request |
|---|---|---|
| Before option | No | No |
| Lockfile | Yes | Yes |
Using it as a safety valve
- Commit your lockfile, and install from it with npm ci.
- If a new release appears bad, keep the lockfile unchanged until you have checked it.
- When regenerating the lockfile, you can use the before option to avoid releases from the last few days, then review the diff as usual.
- Remember the limit: a release that is older than your cutoff can still be bad.
A caution on cooldown thinking
Waiting a few days before adopting a new release gives the community time to notice problems. It is a reasonable habit, but it is a probability shift, not a guarantee, and you should not describe it as a security control on its own. Combine it with scanning, install script review and lockfile diffs.
Where Safeguard fits
Safeguard's dependency scanning and SBOM generation can check the tree you end up with against known vulnerabilities, and you can try a free scan at gold.safeguard.sh/scan.
Quick check
What is the shorthand for the before option?
The npm configuration page lists enjoy-by as a shorthand for before.
Does the before option replace package-lock.json?
No. It filters candidate versions at install time but records nothing. The lockfile records the exact tree.
Sources
Last reviewed: 19 October 2026.
