npm v12 breaking changes: what to know

TL;DR: npm v12 is coming in July 2026 with three security-focused breaking changes: staged publishing with an audit window, stricter install-time script execution controls, and tighter package.json validation. The changelog is already published on the GitHub Blog.

npm v12, estimated for July 2026, introduces three breaking changes to npm install that are worth understanding before they land. None of them are difficult to adapt to, but they’ll break CI pipelines and local installs 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 v12 beta before July to catch breakage early
• Most affected: monorepo tooling, custom registries, and CI pipelines

Staged publishing

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.

Stricter install script controls

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.

Stricter package.json validation

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.

Preparing for the upgrade

1. Test with the beta. The npm v12 beta is available now. Run it in CI and locally to catch breakage.
2. Clean up package.json warnings. Run npm audit fix and address any warnings your manifest produces.
3. Review install scripts. Check which of your dependencies use preinstall or postinstall scripts and whether they’ll be affected by the stricter controls.
4. 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.

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 actually 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 [email protected].