skip to content

With npm, a design-token package compiles tokens in `prepublishOnly`, yet `npm pack` yields a tarball without them — why, and which hook should build them?

level: middleimportance: must knowfreq 18%

answer

  1. not every hook fires on every command
  2. publish-only versus pack-time hooks
  3. prepack, prepare, postpack
  4. prepare also runs on a bare install
  5. prepublish deprecated since npm 4

basics

~20 s

prepublishOnly runs only on npm publish; npm pack runs prepack, prepare and postpack. Build in prepack to compile only when a tarball is made, or in prepare to also build on every bare local npm install.

solid answer

~40 s

`npm pack` fires `prepack`, `prepare`, `postpack`; `npm publish` fires `prepublishOnly`, `prepack`, `prepare`, `postpack`, `publish`, `postpublish`. So a build in `prepublishOnly` is skipped by `npm pack`, and the tarball you inspect differs from the one you would publish. Move the build to `prepack`, which runs on both pack and publish, or to `prepare`, which runs there too and also on a bare `npm install` or `npm ci` in the repo — handy when developers need built output, and the usual place a Git-hook installer goes. Keep `prepublishOnly` for last checks such as tests. The old `prepublish` is deprecated: since npm 4 `prepare` and `prepublishOnly` replaced it, and today it runs on install and `npm ci` but not on `npm publish`.

code

json · 9 lines
json
{
  "name": "@printroom/design-tokens",
  "scripts": {
    "build:tokens": "node scripts/build-tokens.js",
    "prepack": "npm run build:tokens",
    "prepublishOnly": "npm test",
    "test": "node --test"
  }
}

go deeper

for a junior

Recall that npm fires some hooks by itself and that prepublishOnly belongs to npm publish alone, while prepack and prepare also run on npm pack.

for a middle

Explain the order for pack and publish, where prepare additionally runs, and why prepublish was split into prepare and prepublishOnly in npm 4.

for a senior

Diagnose a tarball that differs between pack and publish, choose prepack or prepare by cost and consumer, and keep publish-only checks out of the build path.

for a principal

Insist that the artifact a maintainer inspects is produced exactly as the one published, and decide whether a team's packages build on install or only at packing time.

## Three hooks that sound alike npm fires a handful of **lifecycle scripts** on its own, during install, pack and publish. Three of them are easy to confuse: - **`prepublishOnly`** runs before the package is prepared and packed, **only on `npm publish`**. - **`prepack`** runs before a tarball is packed: on `npm pack` and on `npm publish`. - **`prepare`** runs before packing on `npm pack` and `npm publish`, on a **bare local `npm install`** or `npm ci` (no package arguments), and when the package is installed as a link with `npm install <folder>`. `postpack` runs after the tarball has been generated, before it is moved to its final place. None of these runs when another project installs the published package from the registry: consumers get exactly what was packed, which is why the build has to happen before packing. ## The order for each command `npm pack`: 1. `prepack` 2. `prepare` 3. `postpack` `npm publish`: 1. `prepublishOnly` 2. `prepack` 3. `prepare` 4. `postpack` 5. `publish` 6. `postpublish` A bare `npm install` or `npm ci` runs `preinstall`, `install`, `postinstall`, `prepublish`, `preprepare`, `prepare`, `postprepare` from the project's own `scripts`. Installing a named package (`npm install some-package`) does **not** run the project's `prepare`. | Hook | bare `npm install` / `npm ci` | `npm pack` | `npm publish` | |---|---|---|---| | `prepublishOnly` | no | no | yes, first | | `prepack` | no | yes | yes | | `prepare` | yes | yes | yes | | `postpack` | no | yes | yes | | `prepublish` (deprecated) | yes | no | no | ## Why the tarball came out without tokens The design-token package's maintainer runs `npm pack` to inspect the tarball before a release. Its `prepublishOnly` compiles the tokens into `dist/`, but `npm pack` never fires `prepublishOnly`, so on a clean checkout the tarball is packed without `dist/`. On `npm publish` the build would have run, which makes the bug worse: the tarball you checked and the tarball you shipped are produced differently. The fix is to move the build to a hook that every packing command fires: - **`prepack`** if the build should run only when a tarball is made, on pack and publish. A developer's everyday `npm install` in the repo stays fast. - **`prepare`** if the build should also run on every bare `npm install` of the repo, so contributors always have built output after a fresh clone. `prepublishOnly` remains useful for checks that should block a publish but have no business in a pack — running the test suite one last time, for example. ## Choosing between `prepare` and `prepack` | Need | Hook | |---|---| | build output must exist after a fresh clone and `npm install` | `prepare` | | build only when a tarball is produced | `prepack` | | one-time developer setup on clone, such as installing Git hooks | `prepare` | | gate a publish on tests passing | `prepublishOnly` | `prepare` is the hook Git-hook installers use because a bare install in a fresh clone fires it. Note that since npm 7 lifecycle scripts run in the background during installs; pass `--foreground-scripts` to see their output. On `npm pack` and `npm publish`, `foreground-scripts` already defaults to `true`. ## The deprecated `prepublish` Since npm 1.1.71, `prepublish` ran on both `npm publish` and `npm install`, which confused nearly everyone. npm 4.0.0 introduced `prepare` to keep the "build before use" behaviour and `prepublishOnly` for "only on publish". In current npm, `prepublish` still runs during `npm install` and `npm ci` but **not** during `npm publish`, so a package still using it builds on every install and never on publish. Rename it: build steps go to `prepare` or `prepack`, publish gates to `prepublishOnly`. ## Traps - `npm run pack` is not `npm pack`: the first runs a user script named `pack` and never builds a tarball. - A build in `prepare` runs on every developer install; keep it fast or move it to `prepack`. - Hooks run from the package root with `node_modules/.bin` on `PATH`, so a build tool kept in devDependencies works in `prepack` — on the maintainer's checkout, which is exactly why consumers should receive built output rather than a build step. - Which files end up in the tarball is decided after these hooks run, by the package's file-selection rules — a separate subject from when the build runs.

  • Does `npm install some-package` run the project's own `prepare` script?
    No. `prepare` runs on a bare local `npm install` or `npm ci` with no package arguments, even with flags like `--omit=dev`, but not when you install a specific package. So adding a dependency does not re-run a `prepare` build or reinstall Git hooks.
  • Why might you see no output from a `prepare` script during `npm install`?
    Since npm 7 lifecycle scripts run in the background during installs, so their output is hidden. Run the install with `--foreground-scripts` to see it; on `npm pack` and `npm publish` that setting already defaults to `true`.

  • prepublishOnly runs on npm pack as well as on npm publish
  • prepare runs only when a package is published
  • prepublish is still the right hook for a build before publishing
  • npm run pack builds the same tarball as npm pack
  • Installing a named package re-runs the project's prepare script