Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Scripts and Workspaces

Lifecycle Scripts and Hooks

Understand pre and post script hooks, the install-time lifecycle (preinstall, install, postinstall, prepare), when each runs for you and your users, and why install scripts are a security concern.

Besides the scripts you run by name, npm runs certain scripts automatically at defined moments: before and after another script, around installation, and around publishing. These lifecycle hooks are handy for build steps, but install-time scripts also run code on strangers' machines, so they deserve respect.

pre and post hooks

For any script named x, npm also looks for prex and postx. Running npm run x executes prex, then x, then postx, stopping at the first failure.

JSON
{
  "scripts": {
    "prebuild": "node scripts/clean.js",
    "build": "tsc",
    "postbuild": "node scripts/copy-assets.js",
    "pretest": "npm run lint",
    "test": "node --test"
  }
}

Here npm run build cleans, compiles, then copies assets. npm test lints first. Hooks also apply to built-in commands: pretest, posttest, prestart, prepublishOnly, and so on.

pnpm 7 and later do not run arbitrary pre/post hooks automatically by default (to avoid surprises); enable enable-pre-post-scripts in .npmrc, or call the steps explicitly with &&. Yarn Berry does not run them for user scripts either. npm always does.

Simulating the hook chain

Node.js pre / main / post ordering

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.

Install and publish lifecycle

When you install a package or publish one, npm runs more events in a fixed order.

When you run npm install in a project

preinstall Before anything is installed
install After packages arrive
postinstall Typically native builds or setup
prepare Last, in the root project

These run for the project you are in, and for dependencies that define them.

1 / 2

The most useful ones:

  • prepare: runs after a local npm install with no arguments and before npm publish/npm pack. It is the right place to compile TypeScript or install git hooks (Husky does this).
  • prepublishOnly: runs only on npm publish, ideal for npm test && npm run build.
  • postinstall: runs after a package is installed, including when it is installed as a dependency. Native modules use it to compile; some tools download binaries here.

Install scripts run other people's code

Dependencies can declare preinstall, install and postinstall. When you npm install them, those scripts execute on your computer with your privileges. Attackers have used this to publish malicious packages that steal tokens during install. Defenses:

  • Review packages before installing, especially new or unknown ones.
  • Use npm install --ignore-scripts (or ignore-scripts=true in .npmrc) when you do not need native builds, and run required scripts explicitly.
  • pnpm 10 blocks dependency lifecycle scripts by default; you allow specific packages in onlyBuiltDependencies (or via pnpm approve-builds). Yarn Berry lets you set enableScripts: false.
  • Keep your own postinstall minimal; consumers will run it too. Prefer prepare for developer-only setup, because it does not run when your package is installed as a dependency from the registry.
Node.js Which hooks run in which situation?

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 list is a simplified summary; npm's documentation gives the exact order, which changed slightly between versions.)

A safe, small postinstall

If you must run something after install, make it quick, offline-safe and tolerant of failure:

Node.js A defensive setup script

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.

Run order, --ignore-scripts and project-level allow lists are revisited in the Security chapter. Next you will see how environment variables flow into scripts, in Environment Variables and Cross-Platform Scripts.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In what order does npm run build execute hooks?

    pre runs first, then the script, then post.
  2. 2. Which hook is meant to run tests only when you publish?

    prepublishOnly runs only on npm publish.
  3. 3. Why are postinstall scripts of dependencies a risk?

    Malicious packages can abuse install scripts; --ignore-scripts and allow lists help.
  4. 4. Which flag skips lifecycle scripts?

    --ignore-scripts prevents scripts from running.

Summary

  • pre<name> and post<name> hooks wrap any script automatically in npm (not by default in pnpm or Yarn Berry).
  • Install-time hooks: preinstall, install, postinstall, prepare; publish-time: prepublishOnly, prepack, postpublish.
  • prepare is for developer setup and builds; prepublishOnly guards releases.
  • Dependency install scripts run foreign code: use --ignore-scripts, allow lists and careful review.
  • Keep your own install hooks tiny and failure-tolerant.

Next: Environment Variables and Cross-Platform Scripts