Inspect the package tarball

Your git repo and the npm tarball are different products. Consumers never clone your repository. They install whatever lands inside the .tgz file npm builds at publish time.

Run a dry run first:

npm pack --dry-run

npm lists every file it would include, plus the tarball size. For @acme/[email protected] you want to see dist/index.js, dist/index.d.ts, README.md, LICENSE, and package.json. You do not want test fixtures, .env samples, or CI config.

Control inclusion with files

.gitignore only affects git. npm uses its own rules unless you set a files array:

{
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ]
}

After adding files, run npm pack --dry-run again. The list should shrink to exactly what you listed (plus always-included metadata npm adds automatically).

Unpack and inspect like a consumer

Create the real tarball:

npm pack

That writes something like acme-slugify-title-0.1.0.tgz in the current directory. List its contents:

tar -tzf acme-slugify-title-0.1.0.tgz

You should see paths prefixed with package/:

package/dist/index.js
package/dist/index.d.ts
package/package.json
package/README.md
package/LICENSE

If package/tests/fixtures/leaked-secret.env shows up, fix files or .npmignore before anyone installs a broken release.

One failure mode I see often

A maintainer runs tests against source files in the repo, publishes, and forgets that dist/ was stale or missing from the tarball. The registry then serves JavaScript from last month.

My habit: run npm pack, install that tarball into a clean temp directory, and import the package there. If that smoke test passes, the artifact is worth publishing.

Add a CI job that fails when npm pack --dry-run lists unexpected paths. A one-line shell check for .env or coverage/ catches accidents before they reach the registry.

Compare tarball size between releases. A sudden jump often means test assets or source maps landed in files by mistake.