diff options
Diffstat (limited to 'deps/node/deps/npm/man/man7/npm-scripts.7')
| -rw-r--r-- | deps/node/deps/npm/man/man7/npm-scripts.7 | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/deps/node/deps/npm/man/man7/npm-scripts.7 b/deps/node/deps/npm/man/man7/npm-scripts.7 new file mode 100644 index 00000000..9f5462e8 --- /dev/null +++ b/deps/node/deps/npm/man/man7/npm-scripts.7 @@ -0,0 +1,324 @@ +.TH "NPM\-SCRIPTS" "7" "January 2019" "" "" +.SH "NAME" +\fBnpm-scripts\fR \- How npm handles the "scripts" field +.SH DESCRIPTION +.P +npm supports the "scripts" property of the package\.json file, for the +following scripts: +.RS 0 +.IP \(bu 2 +prepublish: +Run BEFORE the package is packed and published, as well as on local \fBnpm +install\fP without any arguments\. (See below) +.IP \(bu 2 +prepare: +Run both BEFORE the package is packed and published, on local \fBnpm +install\fP without any arguments, and when installing git dependencies (See +below)\. This is run AFTER \fBprepublish\fP, but BEFORE \fBprepublishOnly\fP\|\. +.IP \(bu 2 +prepublishOnly: +Run BEFORE the package is prepared and packed, ONLY on \fBnpm publish\fP\|\. (See +below\.) +.IP \(bu 2 +prepack: +run BEFORE a tarball is packed (on \fBnpm pack\fP, \fBnpm publish\fP, and when +installing git dependencies) +.IP \(bu 2 +postpack: +Run AFTER the tarball has been generated and moved to its final destination\. +.IP \(bu 2 +publish, postpublish: +Run AFTER the package is published\. +.IP \(bu 2 +preinstall: +Run BEFORE the package is installed +.IP \(bu 2 +install, postinstall: +Run AFTER the package is installed\. +.IP \(bu 2 +preuninstall, uninstall: +Run BEFORE the package is uninstalled\. +.IP \(bu 2 +postuninstall: +Run AFTER the package is uninstalled\. +.IP \(bu 2 +preversion: +Run BEFORE bumping the package version\. +.IP \(bu 2 +version: +Run AFTER bumping the package version, but BEFORE commit\. +.IP \(bu 2 +postversion: +Run AFTER bumping the package version, and AFTER commit\. +.IP \(bu 2 +pretest, test, posttest: +Run by the \fBnpm test\fP command\. +.IP \(bu 2 +prestop, stop, poststop: +Run by the \fBnpm stop\fP command\. +.IP \(bu 2 +prestart, start, poststart: +Run by the \fBnpm start\fP command\. +.IP \(bu 2 +prerestart, restart, postrestart: +Run by the \fBnpm restart\fP command\. Note: \fBnpm restart\fP will run the +stop and start scripts if no \fBrestart\fP script is provided\. +.IP \(bu 2 +preshrinkwrap, shrinkwrap, postshrinkwrap: +Run by the \fBnpm shrinkwrap\fP command\. + +.RE +.P +Additionally, arbitrary scripts can be executed by running \fBnpm +run\-script <stage>\fP\|\. \fIPre\fR and \fIpost\fR commands with matching +names will be run for those as well (e\.g\. \fBpremyscript\fP, \fBmyscript\fP, +\fBpostmyscript\fP)\. Scripts from dependencies can be run with +\fBnpm explore <pkg> \-\- npm run <stage>\fP\|\. +.SH PREPUBLISH AND PREPARE +.SS DEPRECATION NOTE +.P +Since \fB, the npm CLI has run the\fPprepublish\fBscript for both\fPnpm +publish\fBand\fPnpm install\fB, 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\fP\fB, a new +event has been introduced,\fPprepare\fB, that preserves this existing behavior\. A +_new_ event,\fPprepublishOnly\fBhas been added as a transitional strategy to +allow users to avoid the confusing behavior of existing npm versions and only +run on\fPnpm publish` (for instance, running the tests one last time to ensure +they're in good shape)\. +.P +See https://github\.com/npm/npm/issues/10074 for a much lengthier +justification, with further reading, for this change\. +.SS USE CASES +.P +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 \fBprepublish\fP script\. This includes +tasks such as: +.RS 0 +.IP \(bu 2 +Compiling CoffeeScript source code into JavaScript\. +.IP \(bu 2 +Creating minified versions of JavaScript source code\. +.IP \(bu 2 +Fetching remote resources that your package will use\. + +.RE +.P +The advantage of doing these things at \fBprepublish\fP time is that they can be done once, in a +single place, thus reducing complexity and variability\. +Additionally, this means that: +.RS 0 +.IP \(bu 2 +You can depend on \fBcoffee\-script\fP as a \fBdevDependency\fP, and thus +your users don't need to have it installed\. +.IP \(bu 2 +You don't need to include minifiers in your package, reducing +the size for your users\. +.IP \(bu 2 +You don't need to rely on your users having \fBcurl\fP or \fBwget\fP or +other system tools on the target machines\. + +.RE +.SH DEFAULT VALUES +.P +npm will default some script values based on package contents\. +.RS 0 +.IP \(bu 2 +\fB"start": "node server\.js"\fP: +If there is a \fBserver\.js\fP file in the root of your package, then npm +will default the \fBstart\fP command to \fBnode server\.js\fP\|\. +.IP \(bu 2 +\fB"install": "node\-gyp rebuild"\fP: +If there is a \fBbinding\.gyp\fP file in the root of your package and you +haven't defined your own \fBinstall\fP or \fBpreinstall\fP scripts, npm will +default the \fBinstall\fP command to compile using node\-gyp\. + +.RE +.SH USER +.P +If npm was invoked with root privileges, then it will change the uid +to the user account or uid specified by the \fBuser\fP config, which +defaults to \fBnobody\fP\|\. Set the \fBunsafe\-perm\fP flag to run scripts with +root privileges\. +.SH ENVIRONMENT +.P +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\. +.SS path +.P +If you depend on modules that define executable scripts, like test +suites, then those executables will be added to the \fBPATH\fP for +executing the scripts\. So, if your package\.json has this: +.P +.RS 2 +.nf +{ "name" : "foo" +, "dependencies" : { "bar" : "0\.1\.x" } +, "scripts": { "start" : "bar \./test" } } +.fi +.RE +.P +then you could run \fBnpm start\fP to execute the \fBbar\fP script, which is +exported into the \fBnode_modules/\.bin\fP directory on \fBnpm install\fP\|\. +.SS package\.json vars +.P +The package\.json fields are tacked onto the \fBnpm_package_\fP prefix\. So, +for instance, if you had \fB{"name":"foo", "version":"1\.2\.5"}\fP in your +package\.json file, then your package scripts would have the +\fBnpm_package_name\fP environment variable set to "foo", and the +\fBnpm_package_version\fP set to "1\.2\.5"\. You can access these variables +in your code with \fBprocess\.env\.npm_package_name\fP and +\fBprocess\.env\.npm_package_version\fP, and so on for other fields\. +.SS configuration +.P +Configuration parameters are put in the environment with the +\fBnpm_config_\fP prefix\. For instance, you can view the effective \fBroot\fP +config by checking the \fBnpm_config_root\fP environment variable\. +.SS Special: package\.json "config" object +.P +The package\.json "config" keys are overwritten in the environment if +there is a config param of \fB<name>[@<version>]:<key>\fP\|\. For example, +if the package\.json has this: +.P +.RS 2 +.nf +{ "name" : "foo" +, "config" : { "port" : "8080" } +, "scripts" : { "start" : "node server\.js" } } +.fi +.RE +.P +and the server\.js is this: +.P +.RS 2 +.nf +http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port) +.fi +.RE +.P +then the user could change the behavior by doing: +.P +.RS 2 +.nf +npm config set foo:port 80 +.fi +.RE +.SS current lifecycle event +.P +Lastly, the \fBnpm_lifecycle_event\fP environment variable is set to +whichever stage of the cycle is being executed\. So, you could have a +single script used for different parts of the process which switches +based on what's currently happening\. +.P +Objects are flattened following this format, so if you had +\fB{"scripts":{"install":"foo\.js"}}\fP in your package\.json, then you'd +see this in the script: +.P +.RS 2 +.nf +process\.env\.npm_package_scripts_install === "foo\.js" +.fi +.RE +.SH EXAMPLES +.P +For example, if your package\.json contains this: +.P +.RS 2 +.nf +{ "scripts" : + { "install" : "scripts/install\.js" + , "postinstall" : "scripts/install\.js" + , "uninstall" : "scripts/uninstall\.js" + } +} +.fi +.RE +.P +then \fBscripts/install\.js\fP will be called for the install +and post\-install stages of the lifecycle, and \fBscripts/uninstall\.js\fP +will be called when the package is uninstalled\. Since +\fBscripts/install\.js\fP is running for two different phases, it would +be wise in this case to look at the \fBnpm_lifecycle_event\fP environment +variable\. +.P +If you want to run a make command, you can do so\. This works just +fine: +.P +.RS 2 +.nf +{ "scripts" : + { "preinstall" : "\./configure" + , "install" : "make && make install" + , "test" : "make test" + } +} +.fi +.RE +.SH EXITING +.P +Scripts are run by passing the line as a script argument to \fBsh\fP\|\. +.P +If the script exits with a code other than 0, then this will abort the +process\. +.P +Note that these script files don't have to be nodejs or even +javascript programs\. They just have to be some kind of executable +file\. +.SH HOOK SCRIPTS +.P +If you want to run a specific script at a specific lifecycle event for +ALL packages, then you can use a hook script\. +.P +Place an executable file at \fBnode_modules/\.hooks/{eventname}\fP, and +it'll get run for all packages when they are going through that point +in the package lifecycle for any packages installed in that root\. +.P +Hook scripts are run exactly the same way as package\.json scripts\. +That is, they are in a separate child process, with the env described +above\. +.SH BEST PRACTICES +.RS 0 +.IP \(bu 2 +Don't exit with a non\-zero error code unless you \fIreally\fR mean it\. +Except for uninstall scripts, this will cause the npm action to +fail, and potentially be rolled back\. If the failure is minor or +only will prevent some optional features, then it's better to just +print a warning and exit successfully\. +.IP \(bu 2 +Try not to use scripts to do what npm can do for you\. Read through +npm help 5 \fBpackage\.json\fP to see all the things that you can specify and enable +by simply describing your package appropriately\. In general, this +will lead to a more robust and consistent state\. +.IP \(bu 2 +Inspect the env to determine where to put things\. For instance, if +the \fBnpm_config_binroot\fP environment variable is set to \fB/home/user/bin\fP, then +don't try to install executables into \fB/usr/local/bin\fP\|\. The user +probably set it up that way for a reason\. +.IP \(bu 2 +Don't prefix your script commands with "sudo"\. If root permissions +are required for some reason, then it'll fail with that error, and +the user will sudo the npm command in question\. +.IP \(bu 2 +Don't use \fBinstall\fP\|\. Use a \fB\|\.gyp\fP file for compilation, and \fBprepublish\fP +for anything else\. You should almost never have to explicitly set a +preinstall or install script\. If you are doing this, please consider if +there is another option\. The only valid use of \fBinstall\fP or \fBpreinstall\fP +scripts is for compilation which must be done on the target architecture\. + +.RE +.SH SEE ALSO +.RS 0 +.IP \(bu 2 +npm help run\-script +.IP \(bu 2 +npm help 5 package\.json +.IP \(bu 2 +npm help 7 developers +.IP \(bu 2 +npm help install + +.RE + |