package.json "files": what npm publish actually includes

Everything below was checked with npm pack --dry-run --json on npm 10.9.9. Older npm versions differ in places (CHANGELOG used to be auto-included).

1. It's an allowlist, with a few exceptions

When "files" is present, only the paths it matches go in the tarball. npm adds a few on its own and drops a few on its own:

"files": [] ships package.json plus whatever matches the always-in list. Not CHANGELOG, not src/.

2. "dist" means everything in dist, dotfiles included

This is the one that bites. A directory entry pulls in the whole tree, and dotfiles aren't special. Real result from a test package with "files": ["dist"]:

$ ls -A dist
.env  a.js  a.js.map  sub/

$ npm pack --dry-run --json | jq -r '.[0].files[].path'
LICENSE
README.md
cli.js            # from "bin"
dist/.env         # <- shipped
dist/a.js
dist/a.js.map     # <- shipped
dist/sub/b.js
dist/sub/b.js.map
index.js          # from "main"
package.json

Build tools that copy .env into the output folder, write *.map next to every file, or leave a stats.json/meta.json behind all end up published. The allowlist only protects you from files outside dist/.

3. Negate inside the array

"files": [
  "dist",
  "!dist/**/*.map",
  "!dist/**/.env*"
]

Order matters. Put negations after the entry they trim: ["!dist/**/*.map", "dist"] ships every map. In the test above, the first negation dropped the maps. .env and .env.local stayed until the second one was added.

4. Which ignore files still count

So you can trim from inside dist/, but most build tools wipe that folder on every build, ignore file included. Negations in package.json survive a clean build. Use those.

5. Patterns, briefly

6. Check it on every publish

# what would ship, nothing published
npm pack --dry-run --json | jq -r '.[0].files[].path'

# fail the publish on the usual suspects
"scripts": {
  "prepublishOnly": "npm pack --dry-run --json | jq -r '.[0].files[].path' | (! grep -E '(^|/)\\.env|\\.map$|\\.pem$|id_rsa|coverage/')"
}

That catches filenames. It won't catch an API key a bundler inlined into dist/index.js from process.env at build time. ReleaseShield unpacks the tarball and runs secret patterns over the contents of every file that would ship. The same scan runs in CI via the CLI or the GitHub Action (docs).

Related

Check yours

Scan any published package or upload a tarball, free, no login.