-
Notifications
You must be signed in to change notification settings - Fork 3.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[DOCS] npm scripts update #729
Closed
+87
−80
Closed
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev
Previous commit
docs: updated scripts docs in using-npm section
- A continuation of @seanhealy's work
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 <stage>`. *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>`. | ||
|
||
* `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 <stage>`. *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>`. | ||
|
||
### 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 <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>`. | ||
|
||
#### [`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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Typo in 'addtion'. |
||
* `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 <https://github.com/npm/npm/issues/10074> for a much lengthier justification, with further reading, for this change. | ||
|
||
See <https://github.com/npm/npm/issues/10074> 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"`: | ||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it might be worth noting that although "test" can be user-defined/overridden, "install" can't be (and probably others, like "publish" etc)?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a great point, same with
pack
. I'll add a "caveats" section. Does that sound right?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Rather than a caveats section I think what I mean is that we have some shorthands for scripts.
npm run test
->npm test
npm run start
->npm start
npm run build
->npm build
npm run restart
->npm restart
I can't think of any others, can you @ljharb ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shorthands that can be overridden for user scripts would also include
version
, but I can't think of any others.It'd be great to exhaustively list BOTH sets - ie, one list of "shorthand commands that run user scripts when present" and "shorthand commands that ignore user scripts even if present" (noting that they all invoke pre/post scripts)