From c8b73db82f0f2445c20a0a64110586253accd66b Mon Sep 17 00:00:00 2001 From: Gar Date: Fri, 12 Feb 2021 15:58:47 -0800 Subject: [PATCH] fix(docs): update scripts docs The lifecycle events section was very out of date, and lots of other cleanup needed to happen too PR-URL: https://github.com/npm/cli/pull/2690 Credit: @wraithgar Close: #2690 Reviewed-by: @ruyadorno --- docs/content/using-npm/scripts.md | 191 ++++++++++++++++++++++-------- 1 file changed, 139 insertions(+), 52 deletions(-) diff --git a/docs/content/using-npm/scripts.md b/docs/content/using-npm/scripts.md index db7bd56b5123c..00ef822bf9001 100644 --- a/docs/content/using-npm/scripts.md +++ b/docs/content/using-npm/scripts.md @@ -6,11 +6,19 @@ description: How npm handles the "scripts" field ### Description -The `"scripts"` property 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 `. +The `"scripts"` property 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 `. ### Pre & Post Scripts -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. +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. ```json { @@ -22,20 +30,35 @@ To create "pre" or "post" scripts for any scripts defined in the `"scripts"` sec } ``` +In this example `npm run compress` would execute these scripts as +described. + ### Life Cycle Scripts -There are some special life cycle scripts that happen only in certain situations. These scripts happen in addition to the "pre" and "post" script. +There are some special life cycle scripts that happen only in certain +situations. These scripts happen in addition to the `pre`, `post`, and +`` scripts. + * `prepare`, `prepublish`, `prepublishOnly`, `prepack`, `postpack` **prepare** (since `npm@4.0.0`) +* Runs any time before the package is packed, i.e. during `npm publish` + and `npm pack` * 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. + +* 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. + +* As of `npm@7` these scripts run in the background **prepublish** (DEPRECATED) -* Same as `prepare` +* Does not run during `npm publish`, but does run during `npm ci` + and `npm install`. See below for more info. **prepublishOnly** * Runs BEFORE the package is prepared and packed, ONLY on `npm publish`. @@ -45,7 +68,7 @@ There are some special life cycle scripts that happen only in certain situations * 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. **postpack** -* Runs AFTER the tarball has been generated and moved to its final destination. +* Runs AFTER the tarball has been generated but before it is moved to its final destination (if at all, publish does not save the tarball locally) #### Prepare and Prepublish @@ -74,51 +97,116 @@ The advantage of doing these things at `prepublish` time is that they can be don ### Life Cycle Operation Order -#### [`npm publish`](/commands/npm-publish) +#### [`npm cache add`](/commands/npm-cache) -* `prepublishOnly` * `prepare` + +#### [`npm ci`](/commands/npm-ci) + +* `preinstall` +* `install` +* `postinstall` * `prepublish` -* `publish` -* `postpublish` +* `preprepare` +* `prepare` +* `postprepare` + + These all run after the actual installation of modules into + `node_modules`, in order, with no internal actions happening in between + +#### [`npm diff`](/commands/npm-diff) + +* `prepare` + +#### [`npm env`](/commands/npm-env) + +* `env` (You can override the default behavior of `npm env` by defining + a custom `env` entry in your `scripts` object) + +#### [`npm install`](/commands/npm-install) + +These also run when you run `npm install -g ` + +* `preinstall` +* `install` +* `postinstall` +* `prepublish` +* `preprepare` +* `prepare` +* `postprepare` + +If there is a `binding.gyp` file in the root of your package and you +haven't defined your own `install` or `preinstall` scripts, npm will +default the `install` command to compile using node-gyp via `node-gyp +rebuild` + +These are run from the scripts of `` #### [`npm pack`](/commands/npm-pack) * `prepack` +* `prepare` * `postpack` -#### [`npm install`](/commands/npm-install) +#### [`npm publish`](/commands/npm-publish) + +* `prepublishOnly` +* `prepack` +* `prepare` +* `postpack` +* `publish` +* `postpublish` + +`prepare` will not run during `--dry-run` + +#### [`npm rebuild`](/commands/npm-rebuild) * `preinstall` * `install` * `postinstall` +* `prepare` -Also triggers +`prepare` is only run if the current directory is a symlink (e.g. with +linked packages) -* `prepublish` (when on local) -* `prepare` (when on local or workspaces) +#### [`npm restart`](/commands/npm-restart) -#### [`npm start`](/commands/npm-start) +If there is a `restart` script defined, these events are run, otherwise +`stop` and `start` are both run if present, including their `pre` and +`post` iterations) + +* `prerestart` +* `restart` +* `postrestart` -`npm run start` has an `npm start` shorthand. +#### [`npm run `](/commands/npm-run) + +* `pre` +* `` +* `post` + +#### [`npm start`](/commands/npm-start) * `prestart` * `start` * `poststart` -### Default Values -npm will default some script values based on package contents. +If there is a `server.js` file in the root of your package, then npm +will default the `start` command to `node server.js`. `prestart` and +`poststart` will still run in this case. + +#### [`npm stop`](/commands/npm-stop) -* `"start": "node server.js"`: +* `prestop` +* `stop` +* `poststop` - If there is a `server.js` file in the root of your package, then npm - will default the `start` command to `node server.js`. +#### [`npm test`](/commands/npm-test) -* `"install": "node-gyp rebuild"`: +* `pretest` +* `test` +* `posttest` - If there is a `binding.gyp` file in the root of your package and you - haven't defined your own `install` or `preinstall` scripts, npm will - default the `install` command to compile using node-gyp. ### User @@ -131,7 +219,6 @@ Package scripts run in an environment where many pieces of information are made available regarding the setup of npm and the current state of the process. - #### path If you depend on modules that define executable scripts, like test @@ -139,14 +226,14 @@ suites, then those executables will be added to the `PATH` for executing the scripts. So, if your package.json has this: ```json -{ - "name" : "foo", - "dependencies" : { - "bar" : "0.1.x" - }, - "scripts": { - "start" : "bar ./test" - } +{ + "name" : "foo", + "dependencies" : { + "bar" : "0.1.x" + }, + "scripts": { + "start" : "bar ./test" + } } ``` @@ -159,8 +246,8 @@ The package.json fields are tacked onto the `npm_package_` prefix. So, for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json file, then your package scripts would have the `npm_package_name` environment variable set to "foo", and the -`npm_package_version` set to "1.2.5". You can access these variables -in your code with `process.env.npm_package_name` and +`npm_package_version` set to "1.2.5". You can access these variables +in your code with `process.env.npm_package_name` and `process.env.npm_package_version`, and so on for other fields. #### configuration @@ -176,14 +263,14 @@ there is a config param of `[@]:`. For example, if the package.json has this: ```json -{ - "name" : "foo", - "config" : { - "port" : "8080" - }, - "scripts" : { - "start" : "node server.js" - } +{ + "name" : "foo", + "config" : { + "port" : "8080" + }, + "scripts" : { + "start" : "node server.js" + } } ``` @@ -219,10 +306,10 @@ process.env.npm_package_scripts_install === "foo.js" For example, if your package.json contains this: ```json -{ - "scripts" : { - "install" : "scripts/install.js", - "postinstall" : "scripts/postinstall.js", +{ + "scripts" : { + "install" : "scripts/install.js", + "postinstall" : "scripts/postinstall.js", "uninstall" : "scripts/uninstall.js" } } @@ -239,10 +326,10 @@ If you want to run a make command, you can do so. This works just fine: ```json -{ - "scripts" : { - "preinstall" : "./configure", - "install" : "make && make install", +{ + "scripts" : { + "preinstall" : "./configure", + "install" : "make && make install", "test" : "make test" } }