From 284c1c055a28c4b334496101799acefe3c54ceb3 Mon Sep 17 00:00:00 2001 From: Michael Perrotte Date: Mon, 27 Jan 2020 16:04:54 -0500 Subject: [PATCH] docs: updated scripts docs in using-npm section - A continuation of @seanhealy's work PR-URL: https://github.com/npm/cli/pull/729 Credit: @ Close: #729 Reviewed-by: @Darcy Clarke --- docs/content/using-npm/scripts.md | 175 ++++++++++++------------------ 1 file changed, 71 insertions(+), 104 deletions(-) diff --git a/docs/content/using-npm/scripts.md b/docs/content/using-npm/scripts.md index d464a7f92423..7de73077b22b 100644 --- a/docs/content/using-npm/scripts.md +++ b/docs/content/using-npm/scripts.md @@ -10,130 +10,64 @@ description: How npm handles the "scripts" field ### Description -The `"scripts"` property of of your `package.json` file supports a number of built-in scripts and their preset life cycle events as well as arbitrary scripts which can be executed by running `npm run `. *Pre* and *post* commands with matching names will be run for those as well (e.g. `premyscript`, `myscript`, -`postmyscript`). Scripts from dependencies can be run with `npm explore - -- npm run `. - -* `prepublish` (_as of npm@5, `prepublish` is deprecated. Use `prepare` for - build steps and `prepublishOnly` for upload-only._): - * Runs BEFORE the package is packed and published, as well as on local `npm - install` without any arguments. (See below) -* `prepare`: - * Runs both BEFORE the package is packed and published, and on local - `npm install` without any arguments (See below). This is run AFTER - `prepublish`, but BEFORE `prepublishOnly`. - * If a package being installed through git contains a `prepare` script, its - `dependencies` and `devDependencies` will be installed, and the prepare - script will be run, before the package is packaged and installed. -* `prepublishOnly`: - * Runs BEFORE the package is prepared and packed, ONLY on `npm publish`. - (See below.) -* `prepack`: - * Runs BEFORE a tarball is packed (on `npm pack`, `npm publish`, and when - installing git dependencies) -* `postpack`: - * Runs AFTER the tarball has been generated and moved to its final destination. -* `publish`, `postpublish`: - * Runs AFTER the package is published. -* `preinstall`: - * Runs BEFORE the package is installed -* `install`, `postinstall`: - * Runs AFTER the package is installed. -* `preuninstall`, `uninstall`: - * Runs BEFORE the package is uninstalled. -* `postuninstall`: - * Runs AFTER the package is uninstalled. -* `preversion`: - * Runs BEFORE bumping the package version. -* `version`: - * Runs AFTER bumping the package version, but BEFORE commit. -* `postversion`: - * Runs AFTER bumping the package version, and AFTER commit. -* `pretest`, `test`, `posttest`: - * Run by the `npm test` command. -* `prestop`, `stop`, `poststop`: - * Run by the `npm stop` command. -* `prestart`, `start`, `poststart`: - * Run by the `npm start` command. -* `prerestart`, `restart`, `postrestart`: - * Run by the `npm restart` command. Note: `npm restart` will run the - stop and start scripts if no `restart` script is provided. -* `preshrinkwrap`, `shrinkwrap`, `postshrinkwrap`: - * Run by the `npm shrinkwrap` command. - -Additionally, arbitrary scripts can be executed by running -`npm run-script `. *Pre* and *post* commands with matching names will -be run for those as well (e.g. `premyscript`, `myscript`, `postmyscript`). -Scripts from dependencies can be run with -`npm explore -- npm run `. - -### Life Cycle - -npm commands such as `npm install` and `npm publish` will fire life cycle -hooks as specified in your `package.json` file. These hooks are as follows -for each command. +The `"scripts"` property of of your `package.json` file supports a number of built-in scripts and their preset life cycle events as well as arbitrary scripts. These all can be executed by running `npm run-script ` or `npm run ` for short. *Pre* and *post* commands with matching names will be run for those as well (e.g. `premyscript`, `myscript`, `postmyscript`). Scripts from dependencies can be run with `npm explore -- npm run `. -#### [`npm publish`](/cli-commands/npm-publish) +### Pre & Post Scripts -* `prepublishOnly` -* `prepare` +To create "pre" or "post" scripts for any scripts defined in the `"scripts"` section of the `package.json`, simply create another script *with a matching name* and add "pre" or "post" to the beginning of them. -#### [`npm pack`](/cli-commands/npm-pack) +```json +{ + "scripts": { + "precompress": "{{ executes BEFORE the `compress` script }}", + "compress": "{{ run command to compress files }}", + "postcompress": "{{ executes AFTER `compress` script }}" + } +} +``` -* `prepack` +### Life Cycle Scripts -#### [`npm install`](/cli-commands/npm-install) +There are some special life cycle scripts that happen only in certain situations. These scripts happen in addtion to the "pre" and "post" script. +* `prepare`, `prepublish`, `prepublishOnly`, `prepack`, `postpack` -* `preinstall` - * Run BEFORE the package is installed -* `install`, `postinstall` - * Run AFTER the package is installed. +**prepare** (since `npm@4.0.0`) +* Runs BEFORE the package is packed +* Runs BEFORE the package is published +* Runs on local `npm install` without any arguments +* Run AFTER `prepublish`, but BEFORE `prepublishOnly` +* NOTE: If a package being installed through git contains a `prepare` script, its `dependencies` and `devDependencies` will be installed, and the prepare script will be run, before the package is packaged and installed. -Also triggers +**prepublish** (DEPRECATED) +* Same as `prepare` -* `prepublish` (when on local) -* `prepare` (when on local) +**prepublishOnly** +* Runs BEFORE the package is prepared and packed, ONLY on `npm publish`. -#### `start` +**prepack** +* Runs BEFORE a tarball is packed (on "`npm pack`", "`npm publish`", and when installing a git dependencies). +* NOTE: "`npm run pack`" is NOT the same as "`npm pack`". "`npm run pack`" is an arbitrary user defined script name, where as, "`npm pack`" is a CLI defined command. -`npm run start` has an `npm start` shorthand. +**postpack** +* Runs AFTER the tarball has been generated and moved to its final destination. -* `prestart` -* `start` -* `poststart` +#### Prepare and Prepublish -#### Prepublish and Prepare +**Deprecation Note: prepublish** -#### Deprecation Note +Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm publish` and `npm install`, because it's a convenient way to prepare a package for use (some common use cases are described in the section below). It has also turned out to be, in practice, [very confusing](https://github.com/npm/npm/issues/10074). As of `npm@4.0.0`, a new event has been introduced, `prepare`, that preserves this existing behavior. A _new_ event, `prepublishOnly` has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on `npm publish` (for instance, running the tests one last time to ensure they're in good shape). -Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm -publish` and `npm install`, because it's a convenient way to prepare a package -for use (some common use cases are described in the section below). It has -also turned out to be, in practice, [very -confusing](https://github.com/npm/npm/issues/10074). As of `npm@4.0.0`, a new -event has been introduced, `prepare`, that preserves this existing behavior. A -_new_ event, `prepublishOnly` has been added as a transitional strategy to -allow users to avoid the confusing behavior of existing npm versions and only -run on `npm publish` (for instance, running the tests one last time to ensure -they're in good shape). +See for a much lengthier justification, with further reading, for this change. -See for a much lengthier -justification, with further reading, for this change. +**Use Cases** -#### Use Cases - -If you need to perform operations on your package before it is used, in a way -that is not dependent on the operating system or architecture of the -target system, use a `prepublish` script. This includes -tasks such as: +If you need to perform operations on your package before it is used, in a way that is not dependent on the operating system or architecture of the target system, use a `prepublish` script. This includes tasks such as: * Compiling CoffeeScript source code into JavaScript. * Creating minified versions of JavaScript source code. * Fetching remote resources that your package will use. -The advantage of doing these things at `prepublish` time is that they can be done once, in a -single place, thus reducing complexity and variability. -Additionally, this means that: +The advantage of doing these things at `prepublish` time is that they can be done once, in a single place, thus reducing complexity and variability. Additionally, this means that: * You can depend on `coffee-script` as a `devDependency`, and thus your users don't need to have it installed. @@ -142,8 +76,41 @@ Additionally, this means that: * You don't need to rely on your users having `curl` or `wget` or other system tools on the target machines. -### Default Values +### Life Cycle Operation Order + +#### [`npm publish`](/cli-commands/npm-publish) + +* `prepublishOnly` +* `prepare` +* `prepublish` +* `publish` +* `postpublish` + +#### [`npm pack`](/cli-commands/npm-pack) + +* `prepack` +* `postpack` + +#### [`npm install`](/cli-commands/npm-install) + +* `preinstall` +* `install` +* `postinstall` + +Also triggers +* `prepublish` (when on local) +* `prepare` (when on local) + +#### [`npm start`](/cli-commands/npm-start) + +`npm run start` has an `npm start` shorthand. + +* `prestart` +* `start` +* `poststart` + +### Default Values npm will default some script values based on package contents. * `"start": "node server.js"`: