Skip to content

Commit e95987c

Browse files
author
Michael Perrotte
committed
docs: updated scripts docs in using-npm section
- A continuation of @seanhealy's work
1 parent 2012f52 commit e95987c

File tree

1 file changed

+71
-104
lines changed

1 file changed

+71
-104
lines changed

Diff for: ‎docs/content/using-npm/scripts.md

+71-104
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 `[email protected]`)
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 `[email protected]`, 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 `[email protected]`, 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 `[email protected]`, 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 `[email protected]`, 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)