npm publishes whatever the files field in package.json allows, minus anything excluded by ignore files, plus a few files that are always included. To see the result before you release, run a dry run of npm pack and read the file list. A published version cannot be changed afterwards.
The rules, in order
From the npm package.json documentation:
- The files field is an allowlist of what to include.
- You can add a .npmignore file to keep files out. At the package root it does not override the files field. In subdirectories it does.
- If there is a .gitignore and no .npmignore, the .gitignore contents are used instead.
- Some files are always included regardless: package.json, the README, the LICENSE, the file named in main, and the files named in bin.
Rule 3 surprises people. If you never wrote an .npmignore, your .gitignore decides, and a file you keep out of git for being local can still matter in the other direction when you add an .npmignore and forget to list it.
Preview the tarball
npm pack --dry-run
The dry run reports what npm would do without making changes. Read the list line by line. You are looking for anything that should not ship.
What to look for
| Found in the list | Why it is a problem |
|---|---|
| .env or credential files | Secrets become public and permanent |
| Source maps you did not intend | Exposes original source |
| Test fixtures with real data | Leaks customer or personal data |
| CI config, scripts, internal docs | Reveals internals |
| Large build leftovers | Slows installs for everyone |
| Missing dist or lib folder | The package will not work |
Make it a gate
- Prefer a files allowlist over ignore lists. New files are excluded by default.
- Run the dry run in CI on every release branch and fail on unexpected paths.
- Scan the packed tarball, not just the repository, for secrets.
- Keep the publish step separate and protected, with a token limited to publishing.
Because the registry will not let you replace a version once published, a leaked file stays in that version. If a secret ships, rotate it first, then publish a fixed version. See can you overwrite a published package version.
Related reading
Package contents are one part of release safety. The open source release security checklist covers the rest of the path.
Safeguard's SBOM and dependency scanning can inventory what your build pulls in, while zero-day discovery and reachability analysis help you judge which findings in your own dependencies matter. You can run a free scan.
Quick check
Does .npmignore override the files field?
At the package root, no. In subdirectories, yes. npm's documentation describes this difference.
What if I have no .npmignore?
npm uses the contents of .gitignore instead, if one exists.
Sources
Last reviewed: 19 October 2026.
