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:
- Always in:
package.json,README*,LICENSE*/LICENCE*, the file in"main", and every file in"bin". - Always out:
.git,node_modules(unless bundled),.npmrc,package-lock.json,.DS_Store,npm-debug.log.
"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.jsonBuild 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
- Root
.npmignore/.gitignore: ignored for anything"files"includes. Puttingdist/a.jsin a root.npmignoredid nothing. - Nested ignore files inside an included directory: still applied. A
dist/.npmignoreordist/.gitignorelisting a file kept it out.
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
"dist"and"dist/"behave the same: whole tree."dist/*.js"is one level only. Use"dist/**/*.js"for nested output.- A typo matches nothing and npm doesn't warn. You find out when a user gets
Cannot find module.
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
- The .npmignore trap: what happens when you don't use
"files". - Source maps in npm packages: turning them off per bundler.
- Published a secret to npm: what to do, in order.
Check yours
Scan any published package or upload a tarball, free, no login.