The .npmignore trap
Why npm publish ships files that never reached your git repo, and why secret scanning on GitHub can't catch it.
1. A .npmignore replaces .gitignore, it doesn't extend it
With no .npmignore, npm uses your .gitignore to decide what to leave out. The moment you add a .npmignore (usually to drop src/ or test/), npm stops reading .gitignore for that directory. Everything git was hiding is back in scope.
# .gitignore
node_modules
.env
dist/*.map
coverage/
# .npmignore (added later "to make the package smaller")
src/
test/
# result: .env, dist/*.map and coverage/ are now in the tarball2. npm packs the working directory, not the commit
npm pack and npm publish read files from disk. Gitignored files exist on disk: the .env on your laptop, the source maps your bundler just wrote to dist/, the coverage report from the test step that ran before publish in CI. None of them were ever committed, so push protection, gitleaks, or any scanner that walks git history has nothing to look at. The tarball is a separate artifact and nobody inspects it.
3. "files" wins over both ignore files
A "files" array in package.json is an allowlist and is the safer default. But a root .npmignore or .gitignore can't exclude anything it includes. "files": ["dist"] ships every file in dist/, including *.map, dotfiles like dist/.env, and anything else a build step dropped there. Negate inside the array if you need to:
"files": ["dist", "!dist/**/*.map"]Precedence, nested ignore files, and what npm always adds or drops: package.json "files", tested.
4. Source maps carry your source
Most bundlers write sourcesContent into maps by default (esbuild does; TypeScript does with inlineSources). That field holds the full pre-build source of every input file. For an open-source package it's dead weight. For a closed-source SDK or CLI it's the codebase, comments included. In our audit of popular packages a large share ship maps and a meaningful fraction inline the source. Per-bundler fix: source maps in npm packages.
5. Check before you publish
List exactly what would ship, without publishing:
npm pack --dry-run --json | jq -r '.[0].files[].path'
# quick grep for the usual suspects
npm pack --dry-run --json | jq -r '.[0].files[].path' \
| grep -E '(^|/)\.env|\.map$|\.pem$|id_rsa|\.npmrc|coverage/|\.sqlite'That catches filenames. It won't catch a Stripe key pasted into a fixture or a token baked into dist/ by a build-time env var. For that you have to read file contents, which is what ReleaseShield does: it unpacks the tarball and runs secret patterns and sensitive-file rules over every byte that would ship.
Fix order if something leaked
Short version below. Full walkthrough, including how to find every affected version and npm's unpublish limits: published a secret to npm.
- Rotate the credential first. Unpublishing doesn't help: mirrors and caches already have the tarball.
- Switch to a
"files"allowlist, or put every.gitignoreline you still need into.npmignore. - Publish a patch version and deprecate the leaky one with
npm deprecate. - Add the dry-run check (or a scanner) to the publish job so it fails before it ships next time.
Check yours
Scan any published package or upload a tarball, free, no login. Or fail the publish in CI when a new file or secret shows up.