mirror of https://github.com/lukechilds/node.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
276 lines
8.5 KiB
276 lines
8.5 KiB
.TH "NPM\-SCRIPTS" "7" "March 2015" "" ""
|
|
.SH "NAME"
|
|
\fBnpm-scripts\fR \- How npm handles the "scripts" field
|
|
.SH DESCRIPTION
|
|
.P
|
|
npm supports the "scripts" property of the package\.json script, for the
|
|
following scripts:
|
|
.RS 0
|
|
.IP \(bu 2
|
|
prepublish:
|
|
Run BEFORE the package is published\. (Also run on local \fBnpm
|
|
install\fR without any arguments\.)
|
|
.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
|
|
pretest, test, posttest:
|
|
Run by the \fBnpm test\fR command\.
|
|
.IP \(bu 2
|
|
prestop, stop, poststop:
|
|
Run by the \fBnpm stop\fR command\.
|
|
.IP \(bu 2
|
|
prestart, start, poststart:
|
|
Run by the \fBnpm start\fR command\.
|
|
.IP \(bu 2
|
|
prerestart, restart, postrestart:
|
|
Run by the \fBnpm restart\fR command\. Note: \fBnpm restart\fR will run the
|
|
stop and start scripts if no \fBrestart\fR script is provided\.
|
|
|
|
.RE
|
|
.P
|
|
Additionally, arbitrary scripts can be executed by running \fBnpm
|
|
run\-script <pkg> <stage>\fR\|\. \fIPre\fR and \fIpost\fR commands with matching
|
|
names will be run for those as well (e\.g\. \fBpremyscript\fR, \fBmyscript\fR,
|
|
\fBpostmyscript\fR)\.
|
|
.SH COMMON USES
|
|
.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\fR 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\fR 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\fR as a \fBdevDependency\fR, 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\fR or \fBwget\fR 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"\fR:
|
|
If there is a \fBserver\.js\fR file in the root of your package, then npm
|
|
will default the \fBstart\fR command to \fBnode server\.js\fR\|\.
|
|
.IP \(bu 2
|
|
\fB"preinstall": "node\-waf clean || true; node\-waf configure build"\fR:
|
|
If there is a \fBwscript\fR file in the root of your package, npm will
|
|
default the \fBpreinstall\fR command to compile using node\-waf\.
|
|
|
|
.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\fR config, which
|
|
defaults to \fBnobody\fR\|\. Set the \fBunsafe\-perm\fR 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\fR 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\fR to execute the \fBbar\fR script, which is
|
|
exported into the \fBnode_modules/\.bin\fR directory on \fBnpm install\fR\|\.
|
|
.SS package\.json vars
|
|
.P
|
|
The package\.json fields are tacked onto the \fBnpm_package_\fR prefix\. So,
|
|
for instance, if you had \fB{"name":"foo", "version":"1\.2\.5"}\fR in your
|
|
package\.json file, then your package scripts would have the
|
|
\fBnpm_package_name\fR environment variable set to "foo", and the
|
|
\fBnpm_package_version\fR set to "1\.2\.5"
|
|
.SS configuration
|
|
.P
|
|
Configuration parameters are put in the environment with the
|
|
\fBnpm_config_\fR prefix\. For instance, you can view the effective \fBroot\fR
|
|
config by checking the \fBnpm_config_root\fR 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>\fR\|\. 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\fR 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"}}\fR 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 the \fBscripts/install\.js\fR will be called for the install,
|
|
post\-install, stages of the lifecycle, and the \fBscripts/uninstall\.js\fR
|
|
would be called when the package is uninstalled\. Since
|
|
\fBscripts/install\.js\fR is running for three different phases, it would
|
|
be wise in this case to look at the \fBnpm_lifecycle_event\fR 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\fR\|\.
|
|
.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}\fR, 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\fR 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\fR environ is set to \fB/home/user/bin\fR, then
|
|
don't try to install executables into \fB/usr/local/bin\fR\|\. 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\fR\|\. Use a \fB\|\.gyp\fR file for compilation, and \fBprepublish\fR
|
|
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\fR or \fBpreinstall\fR
|
|
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
|
|
|
|
|