Yes. When you pass npm a before date during install, it rebuilds the dependency tree so that only versions available on or before that time are chosen. If no suitable version exists for a direct dependency, the command errors. It gives you a simple, client-side way to apply a holding period.
What the documentation says
The npm configuration reference describes the before option: if passed to npm install, it rebuilds the tree such that only versions that were available on or before the given time get installed. If there are no versions available for the current set of direct dependencies, the command errors. For a dist-tag that does not pass the filter, the most recent version less than or equal to that tag is used. The default is null, so the filter is off unless you set it.
Why intake teams care
There are two uses worth knowing.
A client-side hold. If your policy says a version must be public for a set number of days before it is eligible, you can compute a date that many days ago and pass it as the before value in CI jobs that resolve new versions. The tree then avoids anything newer than your holding period. It does not replace mirror-side controls, but it adds a second check close to the build.
Incident replay. After an advisory, you may want to know what your tree looked like on a given day, for example just before a bad version appeared. Resolving with a before date set to that day gives you a candidate tree to compare with the lockfile.
A safe way to use it for a hold
- Decide the holding period as a policy value.
- In the job that updates dependencies, compute the cutoff date from the current time minus that period.
- Run the install with the before value set to the cutoff.
- Commit the resulting lockfile change as a pull request, so the usual intake checks still run.
- Review the diff for anything unexpected, such as a package that errored out or pinned to an older version than you thought.
Limits to remember
- The option filters by publication time as reported by the registry metadata. Your mirror must preserve that metadata for it to work as expected.
- It applies when resolving. A committed lockfile with exact versions installs those versions as written when you use a clean install, so it is the update job, not the build job, that benefits.
- It only helps against threats that surface within the holding period. A package that stays malicious for months will pass.
- A direct dependency with no old enough version makes the command fail. That is a feature for brand new packages, but it can surprise people.
- It is specific to npm. Other ecosystems need their own equivalent, and some have none.
Comparing approaches to a hold
| Approach | Where it runs | Strength | Weakness |
|---|---|---|---|
| Mirror-side hold | Repository manager | Applies to all clients | Needs mirror support and metadata |
| Client-side date filter | Update job | Easy to add today | Per ecosystem, easy to forget |
| Bot cooldown setting | Update bot | Works at pull request time | Does not cover manual installs |
| Manual review of new releases | People | Flexible | Slow |
Most mature setups combine the mirror and the bot, and use the client option as a backstop.
Where Safeguard fits
Safeguard's dependency scanning and policies can check what an update actually pulled in, whichever way the version was selected. The free scan is a way to try it on a repository.
Quick check
Does the before option affect an existing lockfile at install time?
The option applies when npm resolves the tree. For a strict reproducible build, use the clean install command against a committed lockfile.
Is a date filter enough against malicious packages?
No. It reduces exposure to brand new releases only, so keep scanning and source checks in place.
Sources
Last reviewed: 19 October 2026.
