With npm, what does `npm publish` put into a package's tarball by default, and how do you see that file list before publishing?
answer
- the folder, not the Git tree
- files defaults to everything
- ignore files subtract from it
- some files always in, some never
- a rehearsal that prints the list
basics
~20 sWithout a files field, npm publish packs every file in the package folder except what .npmignore (or .gitignore, when there is no .npmignore) and npm's built-in ignores exclude. Run npm pack --dry-run to print the exact list first.
solid answer
~40 sThe `files` field defaults to `["*"]`, so a package without a `files` list ships everything in its folder, minus the ignore rules: a `.npmignore`, or the `.gitignore` when no `.npmignore` exists, plus a short built-in ignore list. Some files go in whatever you configure — `package.json`, the README, the LICENSE, the file named in `main` and the files in `bin` — and some can never go in: `.git`, `.npmrc`, `node_modules` (bundled dependencies aside) and lockfiles such as `package-lock.json`. Everything else that no rule excludes ships, including a stray `.env`, source maps or test fixtures, whether or not Git tracks them. Before a release, run `npm pack --dry-run` (or `npm publish --dry-run`): it computes the file list and prints it under "Tarball Contents" without writing a tarball or uploading anything.
code
bash · 17 lines$ npm pack --dry-run
npm notice
npm notice package: [email protected]
npm notice Tarball Contents
npm notice 312B .env
npm notice 18.4kB dist/index.js
npm notice 41.0kB dist/index.js.map
npm notice 1.1kB LICENSE
npm notice 1.3kB package.json
npm notice 2.9kB README.md
npm notice 6.2kB src/index.js
npm notice Tarball Details
npm notice name: a11y-datepicker
npm notice version: 2.4.0
npm notice filename: a11y-datepicker-2.4.0.tgz
npm notice total files: 7
a11y-datepicker-2.4.0.tgzgo deeper
Recall that files defaults to everything in the folder, that ignore files subtract from it, and that npm pack --dry-run prints the list before you publish.
Explain the fixed lists: package.json, README, LICENSE, main and bin always ship, while .git, .npmrc, node_modules and lockfiles never do, and .env is on neither.
Show the habit that prevents the incident: a dry run or a file-list check in the release job, read for dotfiles, maps and source that should stay home.
Argue for an allow-list plus an automated tarball check across every package a team publishes, so no release depends on one person remembering what the folder holds.
## What `npm publish` actually uploads A published npm package is a **tarball**: a gzipped archive that the registry stores under one `name@version` and that every consumer later downloads and unpacks into `node_modules`. `npm publish` builds that tarball from the **package folder on disk** — the directory holding `package.json` — not from your Git history. A file that Git does not track, such as a local `.env` or a build artefact, is still a file in the folder, so npm will pack it unless a rule leaves it out. That is why "what will this tarball contain?" is a real question rather than a formality. The two classic incidents are a credential file shipped to the public registry and a package that ships its whole `src/`, tests and source maps while missing the compiled output it actually needs. ## The default: `files` is `["*"]` The `files` field in `package.json` is an **allow-list** of paths and globs to include. When it is absent, npm treats it as `["*"]` — every file. What then keeps files out is a set of **ignore rules**: - a `.npmignore` file, which uses the same pattern syntax as `.gitignore`; - if there is **no** `.npmignore`, the `.gitignore` is used in its place — and if both exist, only the `.npmignore` counts; - a built-in ignore list (editor swap files, `.DS_Store`, `npm-debug.log`, `config.gypi` and similar), which applies even with no ignore file at all. So a package with no `files` field and no ignore file publishes essentially its whole folder. ## Files npm always adds and files it always leaves out Two fixed lists sit on top of whatever you configure. | List | Members | Can you change it? | |---|---|---| | **Always included** | `package.json`, `README` (any case or extension), `LICENSE` / `LICENCE`, the file in `main`, the files in `bin` | No — leaving them out of `files` does not drop them | | **Never included** | `.git`, `.npmrc`, `node_modules` (except bundled dependencies), `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb` | No — listing them in `files` does not add them | | **Ignored by default** | `.DS_Store`, `npm-debug.log`, `config.gypi`, `*.orig` and the rest of the built-in list | Yes — most can be brought back by naming them in `files` | The never-included list is short and specific. It protects `.npmrc` (where registry tokens often live) and the lockfiles, but it does **not** protect a `.env`, a private key file, a `coverage/` folder or source maps — those depend entirely on your `files` field or ignore files. ## Seeing the tarball before it leaves the machine npm gives you a rehearsal: 1. Run `npm pack --dry-run` in the package folder. npm computes the file list exactly as a publish would and prints it under **Tarball Contents**, followed by **Tarball Details** (name, version, sizes, total file count). Nothing is written and nothing is uploaded. 2. Read the list for anything that should not be public: dotfiles, `src/` when you meant to ship `dist/`, `*.map`, fixtures, screenshots. 3. If you want to inspect the real archive, run plain `npm pack`: it writes `<name>-<version>.tgz` into the current directory so you can unpack it or install it into a test project. 4. `npm publish --dry-run` does the same rehearsal from the publish side — it prints the file list and the registry, tag and access it would use — and stops before the upload. Making the dry run a habit (or a CI step before the real publish) turns "we shipped the wrong files" from an incident into a failed check. ## Surprises worth knowing - **Untracked does not mean unpublished.** Git ignoring a file only matters to npm while `.gitignore` is the active ignore file. - **Adding a `.npmignore` changes the rules.** As soon as it exists, npm stops reading `.gitignore`, so anything only `.gitignore` excluded is back in. - **`files` cannot drop the always-included files.** A README you did not list still ships. - **Symbolic links are never included** in a package. - **Scoped packages start private on the public registry.** The first publish of a public `@scope/name` package needs `--access public`; later versions keep the access level already set. The short version for an interview: npm publishes the folder, filtered by `files` and the ignore files, plus a fixed always-in list and minus a fixed never-in list — and `npm pack --dry-run` shows you the result before anyone else sees it.
- The date picker moves to a scoped name, `@harbor/datepicker`, for its first public release on the npm registry. What else does that first `npm publish` need?Scoped packages are not public by default, so the first publish needs `--access public` (or `"access": "public"` in `publishConfig`). The flag has the same effect as setting the package's access to public right after publishing. Later versions of an existing scoped package keep the access level already set, so the flag only matters the first time.
- A package's `files` field is `["dist"]`. Do its README and LICENSE still ship?Yes. `package.json`, the README, the LICENSE (or LICENCE), the file named in `main` and the files in `bin` are always included, whatever `files` says. Leaving them out of the allow-list does not drop them, so there is no need to list them.
- Can you force `.npmrc` or `package-lock.json` into the tarball by naming them in `files`?No. `.git`, `.npmrc`, `node_modules` (bundled dependencies aside), `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` and `bun.lockb` can never be included. Other default-ignored files such as `.DS_Store` or `npm-debug.log` are different: naming them in `files` brings them back.
- npm publish uploads only what is committed to Git
- With no files field, npm publishes only the main file
- Leaving README out of files keeps it out of the tarball
- npm pack --dry-run uploads a test version to the registry
- npm never packs dotfiles, so a stray .env is safe
- Listing .npmrc in files ships the registry settings to consumers