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?
answer
- not every hook fires on every command
- publish-only versus pack-time hooks
- prepack, prepare, postpack
- prepare also runs on a bare install
- prepublish deprecated since npm 4
basics
~20 sprepublishOnly 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{
"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
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.
Explain the order for pack and publish, where prepare additionally runs, and why prepublish was split into prepare and prepublishOnly in npm 4.
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.
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