Finally, A Safety Net for npm: Why Staged Publishing Matters More Than You Think

I published a broken package to npm last year. Not catastrophically broken—just a missing export that broke a handful of projects downstream. The fix was five minutes of work, but the damage was already done. Developers had already pulled the bad version, filed issues, and wasted time debugging something that shouldn't have shipped. I've thought about that moment a lot since then, wondering how many other developers have done the same thing and just lived with the guilt.

This is why npm's new staged publishing feature genuinely excites me. It's not flashy. It won't make your code faster or smaller. But it addresses something that keeps developers up at night: the inability to catch mistakes before they're permanently on the public registry. For the first time, we have a built-in way to say "hold on, let me double-check this before everyone sees it."

What Staged Publishing Actually Is

Staged publishing is simple in concept but powerful in practice. Instead of running npm publish and immediately making your package available to millions of developers, you now have the option to publish it in a "staged" state first. The package sits in a review period where you—or your team—can verify everything is correct before giving final approval to make it live on the registry.

Both npm 11.15.0 and pnpm 11.3 added support for this. That dual support matters. The JavaScript ecosystem doesn't converge on single tools, and having this feature available across multiple package managers means more teams can actually use it without friction.

The mechanics are straightforward. You publish with staged mode enabled, do whatever verification you need—run your test suite against real installations, check that your documentation builds, verify your exports work—and then approve it. Only then does it become available on the registry.

Why This Matters More Than It Sounds

Here's what most people miss: staged publishing is primarily about preventing the human moment. It's not protecting you from subtle bugs that tests should catch. It's protecting you from the obvious mistakes—the ones that happen at 11 PM when you're tired, or the ones that slip through because you forgot to rebuild, or the ones where you accidentally committed debug code.

I think about the kinds of errors that haunt the npm registry. Someone publishes version 1.0.0 when they meant 2.0.0. A TypeScript build doesn't run and you ship uncompiled JavaScript. Your barrel file exports the wrong thing. These aren't sophisticated bugs. They're the ones that make you immediately publish 1.0.1 with "oops" in the changelog.

Staged publishing gives you a window to catch these. That window is invaluable if you're serious about your packages.

What This Means for Teams

The team angle is interesting. If you're maintaining a library with multiple contributors, staged publishing becomes a lightweight review mechanism. Someone on your team publishes, another team member verifies the build artifacts and exports before approval. You're not enforcing heavyweight CI or bureaucratic approval processes—just a simple human checkpoint.

This resonates with me because I've seen teams add staged publishing as a natural part of their publishing workflow, like how you'd check a build in CI. It's friction-light but safety-heavy.

The Implementation Angle

What I appreciate is that both npm and pnpm made this opt-in rather than default. If you're happy with your current workflow, you don't have to change anything. But if you've had the experience I have—watching a broken version propagate—you can adopt it immediately.

For pnpm specifically, the new pnpm stage command integrates cleanly into existing workflows. It doesn't require learning new concepts or restructuring how you think about publishing.

My Honest Take

I'm using staged publishing from now on for anything I publish to npm. It's low enough friction that it costs almost nothing, and the upside is real. The downside is basically zero unless you count the thirty seconds of waiting for approval.

What I'd like to see next is integration with CI systems to make approval automatic based on test results. Imagine: publish stages automatically if your tests pass, but requires human approval if they fail. That would be the natural next step.

My question for you: have you had a bad publish moment? What did it teach you about your release process?

Source: This post was inspired by "npm and pnpm introduce staged publishing" by JavaScript Weekly. Read the original article