npm v12 breaking changes: what to know
npm v12 ships July 2026 with three security-focused breaking changes: staged publishing, stricter install scripts, and tighter package.json validation. What's changing and how to prepare.
TL;DR: My CI pipeline broke on a Friday because npm v11 silently accepted a malformed package.json that v12 rejected. That was the first of three breaking changes. Staged publishing, stricter install scripts, and tighter validation are all coming in July 2026.
npm v12 ships in July 2026 with three security-focused breaking changes to npm install. None of them are hard to fix. But they will break your CI if you’re not prepared.
Key takeaways:
- Staged publishing: two-phase publish with an audit window between registration and availability
- Stricter install scripts: more controls over when and how install scripts execute
- Stricter package.json validation: malformed manifests that v11 silently accepted will now be rejected
- Test with
npm v12beta before July to catch breakage early- Most affected: monorepo tooling, custom registries, and CI pipelines
How does staged publishing work in npm v12?
The biggest change is staged publishing. Instead of a package being available immediately after npm publish, there’s now a two-phase process: registration (the package is submitted) and activation (it becomes available after an audit window).
This is a supply-chain security measure. It gives the npm registry time to scan new packages for malicious code before they’re broadly available. For most developers, this is transparent: your packages will show up after the audit window. But CI workflows that publish and immediately install the same package version will need adjustment.
What install script controls does npm v12 add?
npm v12 introduces more granular controls over preinstall and postinstall scripts. The change targets the supply-chain attack vector where malicious packages use install scripts to exfiltrate data or modify the developer environment.
The new controls let you restrict install scripts by origin (first-party vs dependency), by package scope, and by script type. ignore-scripts still works, but the new granular controls mean you don’t have to choose between allowing all scripts or none.
What package.json validation does npm v12 enforce?
npm v12 will reject malformed package.json manifests that v11 silently accepted. This includes missing required fields, invalid semver ranges, and incorrectly structured fields like exports or imports.
Most packages won’t be affected, but if you have legacy package.json files with warnings, now is the time to clean them up. Run npm doctor or npm audit to catch issues before the v12 upgrade.
How do I prepare for the npm v12 upgrade?
- Test with the beta. The
npm v12beta is available now. Run it in CI and locally to catch breakage. - Clean up package.json warnings. Run
npm audit fixand address any warnings your manifest produces. - Review install scripts. Check which of your dependencies use
preinstallorpostinstallscripts and whether they’ll be affected by the stricter controls. - Update CI pipelines. If your CI publishes packages, test the staged publishing flow to ensure your automation handles the audit window.
The full changelog is on the GitHub Blog: Upcoming breaking changes for npm v12
For more on developer tooling and ecosystem changes, check out my comparison of AI coding tools and thoughts on open source development.
FAQ
When is npm v12 being released? Estimated for July 2026, with the changelog already published on the GitHub Blog.
What are the breaking changes in npm v12? Three major changes: staged publishing (two-phase publish with audit window), stricter install script execution controls, and more rigorous package.json validation that will reject malformed manifests that v11 silently accepted.
How should I prepare for npm v12? Run npm audit on your package.json files, test your CI pipelines with the npm v12 beta, and review any install scripts in your dependencies for compliance with the new script policies.
Related Posts
- Your AI Agent Just Scaffolded a Project from 2020. How npm silently downgrades packages and why AI agents don’t catch it
- How AI coding agents use your SDK. How agents discover and invoke tooling in production
This article was published on Agentic Up (https://agenticup.dev): practical guides for developers and founders building with AI agents. Reach me at hello@agenticup.dev.
