Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Publishing

npm pack and publish

See what npm pack puts in the tarball, how files and .npmignore work, how integrity hashes are made, and how to publish with npm, Yarn and pnpm safely.

A published package is just a tarball: a gzip-compressed archive with a package.json inside, uploaded to a registry together with some metadata. Once you understand what goes into that tarball and how it is fingerprinted, publishing stops being mysterious. This lesson covers pack, publish, the dry run, and the commands in all three package managers.

Commands in plain code blocks are read-only on this site. The TryIt examples build a real tarball and its hashes with Node's standard library, so you can see exactly what the registry would store.

What npm pack does

npm pack runs the prepack and prepare scripts, selects the files, creates name-version.tgz in the current folder and prints a summary. The dry run prints the same list without writing anything:

Terminal
npm pack --dry-run
npm pack --json          # machine-readable output, handy in CI

Inside the tarball every path is prefixed with package/. When someone runs npm install, the manager downloads the tarball, checks it against an integrity hash and unpacks it into node_modules.

Which files are included

The rules, from strongest to weakest:

  1. Always included: package.json, README*, LICENSE*/LICENCE*, CHANGELOG* (since npm 7 only some of these), and the files named by main, module, bin and exports targets.
  2. Always excluded: .git, node_modules, .npmrc, lockfiles, .DS_Store, and files such as *.orig.
  3. If package.json has a files array, only those paths (plus rule 1) are included. Patterns work like gitignore globs; a folder name includes everything inside it.
  4. Otherwise an .npmignore file is used; if there is none, .gitignore is used instead. An .npmignore replaces .gitignore completely, which surprises many people: files git ignores (like .env) become publishable the moment you create an empty .npmignore.
  5. files patterns apply to the root. A nested .npmignore inside a sub-folder can exclude more.

Treat the dry run as a security step. Secrets, test fixtures with real data, and source maps that embed private paths have all been published by accident, and a published version can be copied the moment it is public.

Seeing the tarball for yourself

This example builds the same kind of archive in plain Node: it selects files with a simplified allow-list, writes a minimal tar (ustar) stream, compresses it with gzip and prints the two fingerprints the registry stores, the legacy SHA-1 shasum and the modern SHA-512 integrity.

Node.js Stand-in: build a package tarball and fingerprint it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The important lesson hides in the last two lines: change one byte of any file and both fingerprints change. That is how a lockfile can prove that tomorrow's install is the same code as today's (see lockfiles explained).

Publishing

Log in once (npm login, which opens a browser, or a token in .npmrc for CI), then publish:

Terminal
npm publish                     # public unscoped package
npm publish --access public     # first publish of a scoped package
npm publish --tag beta          # publish under a dist-tag instead of latest
npm publish --dry-run           # everything except the upload
npm publish --provenance        # attach a signed build attestation (from supported CI)

Scoped packages (@acme/tool) are private by default and need --access public the first time, or "publishConfig": { "access": "public" } in the manifest. Details are in scopes and registries.

Yarn and pnpm

Task npm Yarn (Berry) pnpm
Make a tarball npm pack yarn pack pnpm pack
Publish npm publish yarn npm publish pnpm publish
Dry run npm publish --dry-run yarn npm publish --dry-run pnpm publish --dry-run
Tag --tag beta --tag beta --tag beta

pnpm refuses to publish from a branch that is not clean and up to date unless you pass --no-git-checks. Yarn and pnpm also rewrite workspace: and catalog: versions into real ranges inside the published manifest, which npm cannot do (covered in workspace protocol and local linking).

Publishing is hard to undo

  • A version can be published once. Even after unpublish, the number is burned.
  • npm unpublish is allowed only within 72 hours, or when nothing else depends on the package. Afterwards use npm deprecate to add a warning that appears on install: npm deprecate [email protected] "Use 1.0.1, which fixes a crash".
  • Two-factor authentication on publish, and granular access tokens limited to one package, reduce the damage of a stolen credential.

Verify what you published

The last step of every release is to look at the real thing:

Terminal
npm view demo version dist.integrity dist.tarball
mkdir /tmp/check && cd /tmp/check && npm init -y && npm install demo@latest

This second example shows how a consumer's install checks a download against the stored integrity string, including what happens when a tarball is tampered with.

Node.js Stand-in: verifying a download against its integrity hash

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is inside the tarball that npm pack creates?

    The tarball is a compressed archive of the chosen files, each under a package/ prefix, with package.json always included.
  2. 2. You create an empty .npmignore file in a repo that has a .gitignore listing .env. What happens?

    When .npmignore exists, .gitignore is no longer used for packing. That is one reason to prefer the files allow-list.
  3. 3. A scoped package is published for the first time. What is needed to make it public?

    Scoped packages default to private, so the first publish needs public access to be set explicitly.
  4. 4. A bad version is already installed by people. What is the best response?

    Versions are immutable. Ship a fix under a new number and deprecate the broken one so installs show a warning.

Summary

  • A package is a gzip tarball with package/ paths, fingerprinted by SHA-1 and SHA-512 hashes.
  • files (allow-list) beats .npmignore; .npmignore replaces .gitignore.
  • Always run pack --dry-run and read the list; verify the published package afterwards.
  • Scoped packages need --access public on their first publish.
  • Versions are immutable: fix forward and deprecate.

Next: Scopes, Registries and .npmrc