Use min-release-age to ignore versions published fewer than a set number of days ago, and use before to freeze resolution at a fixed date. The npm docs say that if both are set in the same source, before takes precedence. Check that your npm version supports them.
What the npm config reference says
min-release-age (default null, a number): with a value set, npm installs only versions that were available more than the given number of days ago. If no eligible version exists, the command errors. Packages matching min-release-age-exclude are exempt. The page says the setting is not passed to child processes.
before (default null, a date): npm rebuilds the dependency tree so that only versions available on or before the given date are installed. If before and min-release-age are both set in the same source, before takes precedence.
The reference does not say in which npm release either option arrived, so confirm in your environment.
Choosing between them
| Need | Use |
|---|---|
| A rolling delay, such as nothing newer than a week | min-release-age |
| Reproduce an old build from a known date | before |
| Exempt an internal package from the delay | min-release-age-exclude |
| Fail loudly if nothing old enough exists | min-release-age (it errors) |
Why delay at all
Compromised releases are often detected and pulled within a short window. A delay means your resolver skips the newest versions until others have had time to notice a problem. The longer discussion, with its limits, is in dependency cooldown periods as a malware defense. A delay is not a guarantee, since a bad version might survive past your window.
Delay and security fixes
The risk of a delay is that a patch for a known vulnerability is also new. If your policy applies blindly, you wait for the fix. Plan an exception route:
- Keep the delay short enough that an urgent fix is at most days away.
- Use the exclude list for the specific package while you review the new release.
- Record each exception with the advisory and the reviewer.
- Remove the exclusion afterwards so the default applies again.
Setup steps
- Pick a number of days. A few days to a week is a common starting point, and your team's tolerance decides.
- Add
min-release-ageto the project.npmrcand commit it. - Run a clean install in CI to see which resolutions change.
- Fix any "no eligible version" errors by choosing an older range or an exception.
- Decide who approves exclusions.
- Review the number every quarter.
What it does not change
The setting affects resolution of versions that npm picks. It does not alter versions already pinned in a lockfile, and npm ci installs what the lockfile says. Delay applies when you update. That is why lockfile review stays important, see what to check in a lockfile diff.
Safeguard scans your lockfile and monitors for new advisories on pinned versions, so a delayed fix does not go unnoticed. A free scan shows your current state.
Quick check
Which wins if both are set?
before, if both are set in the same source, per the npm config reference.
Does min-release-age change an existing lockfile?
Not by itself. It affects which versions npm resolves when it updates. npm ci installs what the lockfile records.
Sources
Last reviewed: 19 October 2026.
