Skip to content

Commit 284c1c0

Browse files
Michael Perrottedarcyclarke
authored andcommitted
docs: updated scripts docs in using-npm section
- A continuation of @seanhealy's work PR-URL: #729 Credit: @ Close: #729 Reviewed-by: @darcy Clarke
1 parent fbb5f0e commit 284c1c0

File tree

1 file changed

+71
-104
lines changed

1 file changed

+71
-104
lines changed

docs/content/using-npm/scripts.md

Lines changed: 71 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -10,130 +10,64 @@ description: How npm handles the "scripts" field
1010

1111
### Description
1212

13-
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 <stage>`. *Pre* and *post* commands with matching names will be run for those as well (e.g. `premyscript`, `myscript`,
14-
`postmyscript`). Scripts from dependencies can be run with `npm explore
15-
<pkg> -- npm run <stage>`.
16-
17-
* `prepublish` (_as of npm@5, `prepublish` is deprecated. Use `prepare` for
18-
build steps and `prepublishOnly` for upload-only._):
19-
* Runs BEFORE the package is packed and published, as well as on local `npm
20-
install` without any arguments. (See below)
21-
* `prepare`:
22-
* Runs both BEFORE the package is packed and published, and on local
23-
`npm install` without any arguments (See below). This is run AFTER
24-
`prepublish`, but BEFORE `prepublishOnly`.
25-
* If a package being installed through git contains a `prepare` script, its
26-
`dependencies` and `devDependencies` will be installed, and the prepare
27-
script will be run, before the package is packaged and installed.
28-
* `prepublishOnly`:
29-
* Runs BEFORE the package is prepared and packed, ONLY on `npm publish`.
30-
(See below.)
31-
* `prepack`:
32-
* Runs BEFORE a tarball is packed (on `npm pack`, `npm publish`, and when
33-
installing git dependencies)
34-
* `postpack`:
35-
* Runs AFTER the tarball has been generated and moved to its final destination.
36-
* `publish`, `postpublish`:
37-
* Runs AFTER the package is published.
38-
* `preinstall`:
39-
* Runs BEFORE the package is installed
40-
* `install`, `postinstall`:
41-
* Runs AFTER the package is installed.
42-
* `preuninstall`, `uninstall`:
43-
* Runs BEFORE the package is uninstalled.
44-
* `postuninstall`:
45-
* Runs AFTER the package is uninstalled.
46-
* `preversion`:
47-
* Runs BEFORE bumping the package version.
48-
* `version`:
49-
* Runs AFTER bumping the package version, but BEFORE commit.
50-
* `postversion`:
51-
* Runs AFTER bumping the package version, and AFTER commit.
52-
* `pretest`, `test`, `posttest`:
53-
* Run by the `npm test` command.
54-
* `prestop`, `stop`, `poststop`:
55-
* Run by the `npm stop` command.
56-
* `prestart`, `start`, `poststart`:
57-
* Run by the `npm start` command.
58-
* `prerestart`, `restart`, `postrestart`:
59-
* Run by the `npm restart` command. Note: `npm restart` will run the
60-
stop and start scripts if no `restart` script is provided.
61-
* `preshrinkwrap`, `shrinkwrap`, `postshrinkwrap`:
62-
* Run by the `npm shrinkwrap` command.
63-
64-
Additionally, arbitrary scripts can be executed by running
65-
`npm run-script <stage>`. *Pre* and *post* commands with matching names will
66-
be run for those as well (e.g. `premyscript`, `myscript`, `postmyscript`).
67-
Scripts from dependencies can be run with
68-
`npm explore <pkg> -- npm run <stage>`.
69-
70-
### Life Cycle
71-
72-
npm commands such as `npm install` and `npm publish` will fire life cycle
73-
hooks as specified in your `package.json` file. These hooks are as follows
74-
for each command.
13+
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 <stage>` or `npm run <stage>` 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 <pkg> -- npm run <stage>`.
7514

76-
#### [`npm publish`](/cli-commands/npm-publish)
15+
### Pre & Post Scripts
7716

78-
* `prepublishOnly`
79-
* `prepare`
17+
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.
8018

81-
#### [`npm pack`](/cli-commands/npm-pack)
19+
```json
20+
{
21+
"scripts": {
22+
"precompress": "{{ executes BEFORE the `compress` script }}",
23+
"compress": "{{ run command to compress files }}",
24+
"postcompress": "{{ executes AFTER `compress` script }}"
25+
}
26+
}
27+
```
8228

83-
* `prepack`
29+
### Life Cycle Scripts
8430

85-
#### [`npm install`](/cli-commands/npm-install)
31+
There are some special life cycle scripts that happen only in certain situations. These scripts happen in addtion to the "pre" and "post" script.
32+
* `prepare`, `prepublish`, `prepublishOnly`, `prepack`, `postpack`
8633

87-
* `preinstall`
88-
* Run BEFORE the package is installed
89-
* `install`, `postinstall`
90-
* Run AFTER the package is installed.
34+
**prepare** (since `npm@4.0.0`)
35+
* Runs BEFORE the package is packed
36+
* Runs BEFORE the package is published
37+
* Runs on local `npm install` without any arguments
38+
* Run AFTER `prepublish`, but BEFORE `prepublishOnly`
39+
* 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.
9140

92-
Also triggers
41+
**prepublish** (DEPRECATED)
42+
* Same as `prepare`
9343

94-
* `prepublish` (when on local)
95-
* `prepare` (when on local)
44+
**prepublishOnly**
45+
* Runs BEFORE the package is prepared and packed, ONLY on `npm publish`.
9646

97-
#### `start`
47+
**prepack**
48+
* Runs BEFORE a tarball is packed (on "`npm pack`", "`npm publish`", and when installing a git dependencies).
49+
* 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.
9850

99-
`npm run start` has an `npm start` shorthand.
51+
**postpack**
52+
* Runs AFTER the tarball has been generated and moved to its final destination.
10053

101-
* `prestart`
102-
* `start`
103-
* `poststart`
54+
#### Prepare and Prepublish
10455

105-
#### Prepublish and Prepare
56+
**Deprecation Note: prepublish**
10657

107-
#### Deprecation Note
58+
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).
10859

109-
Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm
110-
publish` and `npm install`, because it's a convenient way to prepare a package
111-
for use (some common use cases are described in the section below). It has
112-
also turned out to be, in practice, [very
113-
confusing](https://github.com/npm/npm/issues/10074). As of `npm@4.0.0`, a new
114-
event has been introduced, `prepare`, that preserves this existing behavior. A
115-
_new_ event, `prepublishOnly` has been added as a transitional strategy to
116-
allow users to avoid the confusing behavior of existing npm versions and only
117-
run on `npm publish` (for instance, running the tests one last time to ensure
118-
they're in good shape).
60+
See <https://github.com/npm/npm/issues/10074> for a much lengthier justification, with further reading, for this change.
11961

120-
See <https://github.com/npm/npm/issues/10074> for a much lengthier
121-
justification, with further reading, for this change.
62+
**Use Cases**
12263

123-
#### Use Cases
124-
125-
If you need to perform operations on your package before it is used, in a way
126-
that is not dependent on the operating system or architecture of the
127-
target system, use a `prepublish` script. This includes
128-
tasks such as:
64+
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:
12965

13066
* Compiling CoffeeScript source code into JavaScript.
13167
* Creating minified versions of JavaScript source code.
13268
* Fetching remote resources that your package will use.
13369

134-
The advantage of doing these things at `prepublish` time is that they can be done once, in a
135-
single place, thus reducing complexity and variability.
136-
Additionally, this means that:
70+
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:
13771

13872
* You can depend on `coffee-script` as a `devDependency`, and thus
13973
your users don't need to have it installed.
@@ -142,8 +76,41 @@ Additionally, this means that:
14276
* You don't need to rely on your users having `curl` or `wget` or
14377
other system tools on the target machines.
14478

145-
### Default Values
79+
### Life Cycle Operation Order
80+
81+
#### [`npm publish`](/cli-commands/npm-publish)
82+
83+
* `prepublishOnly`
84+
* `prepare`
85+
* `prepublish`
86+
* `publish`
87+
* `postpublish`
88+
89+
#### [`npm pack`](/cli-commands/npm-pack)
90+
91+
* `prepack`
92+
* `postpack`
93+
94+
#### [`npm install`](/cli-commands/npm-install)
95+
96+
* `preinstall`
97+
* `install`
98+
* `postinstall`
99+
100+
Also triggers
146101

102+
* `prepublish` (when on local)
103+
* `prepare` (when on local)
104+
105+
#### [`npm start`](/cli-commands/npm-start)
106+
107+
`npm run start` has an `npm start` shorthand.
108+
109+
* `prestart`
110+
* `start`
111+
* `poststart`
112+
113+
### Default Values
147114
npm will default some script values based on package contents.
148115

149116
* `"start": "node server.js"`:

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy