Dev.to Security 🔐 Cybersecurity 👁 0 📖 2 min read

The .npmignore trap: why npm publish ships files your .gitignore hides

Adding a .npmignore makes npm stop reading .gitignore — so .env files, source maps, and build leftovers end up in the tarball. Git secret scanning never sees them. Originally published on ReleaseShield. 1. A .

Adding a .npmignore makes npm stop reading .gitignore — so .env files, source maps, and build leftovers end up in the tarball. Git secret scanning never sees them.

Originally published on ReleaseShield.

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 tarball

2. 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"]

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 445 popular packages, 56% ship source maps — and a meaningful fraction inline the source.

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. Free, no login.

Fix order if something leaked

  1. Rotate the credential first. Unpublishing doesn't help: mirrors and caches already have the tarball.
  2. Switch to a "files" allowlist, or put every .gitignore line you still need into .npmignore.
  3. Publish a patch version and deprecate the leaky one with npm deprecate.
  4. Add the dry-run check (or a scanner) to the publish job so it fails before it ships next time.

The full walkthrough, including how to find every affected version and npm's unpublish limits, is in the companion guide: published a secret to npm.

Check any published package before you ship it: scan a package or upload a tarball, free.

📰 Read the original article on Dev.to Security

Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.