skip to content

Registry & Publishing

Scoped registries and tokens in .npmrc, what npm publish uploads via files and .npmignore, dist-tags and provenance. Asked because shipping a secret or the wrong file set is a real incident.

on this pageshow

explore

questions

5

With npm, what does `npm publish` put into a package's tarball by default, and how do you see that file list before publishing?

level: juniorimportance: must knowfreq 24%

answer

  1. the folder, not the Git tree
  2. files defaults to everything
  3. ignore files subtract from it
  4. some files always in, some never
  5. a rehearsal that prints the list

basics

~20 s

Without 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 s

The `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
bash
$ 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.tgz

go deeper

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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
open as a page

In npm's `.npmrc`, how do you send the `@harbor` scope to a private registry and give npm its token without committing the token?

level: middleimportance: must knowfreq 19%

basics

~10 s

Put @harbor:registry=https://registry.harbor.example/ and //registry.harbor.example/:_authToken=${HARBOR_NPM_TOKEN} in the project .npmrc. npm expands the environment variable when it reads the file, so only the placeholder is committed.

open as a page

With npm 12, how do you publish `[email protected]` without moving the `latest` dist-tag, and what happens if you leave out `--tag`?

level: middleimportance: should knowfreq 14%

basics

~20 s

Run npm publish --tag beta: the version goes up under the beta dist-tag and latest stays on 2.x. Since npm 11, publishing a prerelease version without --tag (or a publishConfig tag) stops with an error instead of moving latest.

open as a page

In an npm package that nearly published a `.env` and its source maps, how do `files` and `.npmignore` decide what `npm publish` includes?

level: middleimportance: should knowfreq 13%

basics

~20 s

files is an allow-list: only matching paths, plus package.json, README, LICENSE, main and bin, are packed. .npmignore is a deny-list over the rest, and once it exists npm stops reading .gitignore, so a git-ignored .env can ship.

open as a page

With npm, `[email protected]` went out broken twenty minutes ago — what do `npm unpublish` and the registry's unpublish policy allow, and why must the fix still ship as 2.4.2?

level: seniorimportance: should knowfreq 8%

basics

~20 s

The registry lets npm unpublish [email protected] through only with no public dependents and, unless the package itself is under 72 hours old, under 300 weekly downloads and one owner. 2.4.1 can never be reused, so the fix ships as 2.4.2.

open as a page