An npm Release Checklist for Teams Shipping Fast
The package you publish is the product customers receive. If your team does not inspect the final tarball, you are trusting your release pipeline more than you should.
Jason Overmier
Innovative Prospects Team
Release engineering bugs are dangerous because they bypass normal code review. The reviewed code is not always the same thing as the published artifact.
That is especially true for npm packages, where a stray file, debug artifact, or build misconfiguration can turn a normal release into a public incident.
Final Artifact Checklist
Before publishing, verify:
- which files are actually included in the package
- whether any debug artifacts or source maps are present
- whether test fixtures or internal docs are leaking
- whether the package size changed unexpectedly
- whether the published entrypoint matches what you expect
The Commands Worth Automating
| Check | Why |
|---|---|
npm pack --dry-run | Shows exact package contents before publish |
| Tarball size diff | Flags suspicious artifact growth |
| Forbidden-file scan | Catches .map, .env, fixtures, and local artifacts |
| CI publish-from-clean-tree | Reduces accidental local state leakage |
High-Risk Release Smells
| Smell | Why it matters |
|---|---|
| Unexpected package growth | Often means extra build output was included |
| Manual publish from a laptop | Harder to reproduce and audit |
| Reliance on default include rules | Easier to ship unintended files |
| No artifact review gate | Final package may differ from reviewed code |
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
Teams trust .gitignore to control packaging | npm packaging rules are different | Use explicit package allowlists |
| Source maps leak accidentally | Build defaults change or env flags drift | Fail CI when forbidden files appear |
| Package contents are never reviewed | Publish process is too habitual | Add automated and human checks |
| Rollback is improvised | Teams assume release issues are rare | Practice revoke, replace, and notify workflows |
The Rule
Review the tarball, not just the code. The tarball is what you actually shipped.
If your release pipeline moves fast enough that packaging mistakes are starting to worry you, reach out. We help teams harden CI/CD and artifact validation before a routine publish becomes an avoidable incident.
