unclear documentation on install scripts

[chharvey]

I'm opening this issue because:

npm is doing something I don't understand.

What's going wrong?

https://docs.npmjs.com/misc/scripts does not contain detailed documentation on the preinstall, install, and postinstall scripts. It says:

• preinstall: Run BEFORE the package is installed
• install, postinstall: Run AFTER the package is installed

This conflicts with descriptions I’ve seen all over the web[*], most of which say—vaguely, in the
passive voice—“after npm install is run”.

Does this mean that in my package.json, the postinstall script will run after I (myself) run npm install, i.e. when I’m installing dependencies? Or does it mean that if someone runs npm install my-package that my script will run on their computer after they install my package? I’ve searched all over the web and have gotten mixed answers. Please make the docs precisely clear about this.

The reason I ask is because would like to have a script run automatically after a user installs my package. The script runs a gulp task that generates dist files, which are not checked in to git.

If this script runs only after I run npm install, it isn’t helpful at all to users of my package. I would like the script to run after they install my package.

  "scripts": {
    "postinstall": "gulp build"
  }

[*]sources:

• NPM "lifecycle" scripts order: install/postinstall scripts being run before all dependencies are finished installing #5001
• install/postinstall scripts run before devDependency install #10366
• StackOverflow | How do I add a custom script to my package.json file that runs a javascript file?
  
• StackOverflow | Npm postinstall only on development
• CSS-Tricks | Why npm Scripts?
• “Fun playing with npm, dependencies and postinstall script”