1 .TH "NPM\-SCRIPTS" "7" "October 2016" "" ""
3 \fBnpm-scripts\fR \- How npm handles the "scripts" field
6 npm supports the "scripts" property of the package\.json script, for the
11 Run BEFORE the package is published\. (Also run on local \fBnpm
12 install\fP without any arguments\.)
15 Run AFTER the package is published\.
18 Run BEFORE the package is installed
21 Run AFTER the package is installed\.
23 preuninstall, uninstall:
24 Run BEFORE the package is uninstalled\.
27 Run AFTER the package is uninstalled\.
30 Run BEFORE bumping the package version\.
33 Run AFTER bumping the package version\.
35 pretest, test, posttest:
36 Run by the \fBnpm test\fP command\.
38 prestop, stop, poststop:
39 Run by the \fBnpm stop\fP command\.
41 prestart, start, poststart:
42 Run by the \fBnpm start\fP command\.
44 prerestart, restart, postrestart:
45 Run by the \fBnpm restart\fP command\. Note: \fBnpm restart\fP will run the
46 stop and start scripts if no \fBrestart\fP script is provided\.
50 Additionally, arbitrary scripts can be executed by running \fBnpm
51 run\-script <stage>\fP\|\. \fIPre\fR and \fIpost\fR commands with matching
52 names will be run for those as well (e\.g\. \fBpremyscript\fP, \fBmyscript\fP,
53 \fBpostmyscript\fP)\. Scripts from dependencies can be run with `npm explore
55 <pkg> \-\- npm run <stage>`\.
58 If you need to perform operations on your package before it is used, in a way
59 that is not dependent on the operating system or architecture of the
60 target system, use a \fBprepublish\fP script\. This includes
64 Compiling CoffeeScript source code into JavaScript\.
66 Creating minified versions of JavaScript source code\.
68 Fetching remote resources that your package will use\.
72 The advantage of doing these things at \fBprepublish\fP time is that they can be done once, in a
73 single place, thus reducing complexity and variability\.
74 Additionally, this means that:
77 You can depend on \fBcoffee\-script\fP as a \fBdevDependency\fP, and thus
78 your users don't need to have it installed\.
80 You don't need to include minifiers in your package, reducing
81 the size for your users\.
83 You don't need to rely on your users having \fBcurl\fP or \fBwget\fP or
84 other system tools on the target machines\.
89 npm will default some script values based on package contents\.
92 \fB"start": "node server\.js"\fP:
93 If there is a \fBserver\.js\fP file in the root of your package, then npm
94 will default the \fBstart\fP command to \fBnode server\.js\fP\|\.
96 \fB"install": "node\-gyp rebuild"\fP:
97 If there is a \fBbinding\.gyp\fP file in the root of your package and you
98 haven't defined your own \fBinstall\fP or \fBpreinstall\fP scripts, npm will
99 default the \fBinstall\fP command to compile using node\-gyp\.
104 If npm was invoked with root privileges, then it will change the uid
105 to the user account or uid specified by the \fBuser\fP config, which
106 defaults to \fBnobody\fP\|\. Set the \fBunsafe\-perm\fP flag to run scripts with
110 Package scripts run in an environment where many pieces of information
111 are made available regarding the setup of npm and the current state of
115 If you depend on modules that define executable scripts, like test
116 suites, then those executables will be added to the \fBPATH\fP for
117 executing the scripts\. So, if your package\.json has this:
122 , "dependencies" : { "bar" : "0\.1\.x" }
123 , "scripts": { "start" : "bar \./test" } }
127 then you could run \fBnpm start\fP to execute the \fBbar\fP script, which is
128 exported into the \fBnode_modules/\.bin\fP directory on \fBnpm install\fP\|\.
129 .SS package\.json vars
131 The package\.json fields are tacked onto the \fBnpm_package_\fP prefix\. So,
132 for instance, if you had \fB{"name":"foo", "version":"1\.2\.5"}\fP in your
133 package\.json file, then your package scripts would have the
134 \fBnpm_package_name\fP environment variable set to "foo", and the
135 \fBnpm_package_version\fP set to "1\.2\.5"
138 Configuration parameters are put in the environment with the
139 \fBnpm_config_\fP prefix\. For instance, you can view the effective \fBroot\fP
140 config by checking the \fBnpm_config_root\fP environment variable\.
141 .SS Special: package\.json "config" object
143 The package\.json "config" keys are overwritten in the environment if
144 there is a config param of \fB<name>[@<version>]:<key>\fP\|\. For example,
145 if the package\.json has this:
150 , "config" : { "port" : "8080" }
151 , "scripts" : { "start" : "node server\.js" } }
155 and the server\.js is this:
159 http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
163 then the user could change the behavior by doing:
167 npm config set foo:port 80
170 .SS current lifecycle event
172 Lastly, the \fBnpm_lifecycle_event\fP environment variable is set to
173 whichever stage of the cycle is being executed\. So, you could have a
174 single script used for different parts of the process which switches
175 based on what's currently happening\.
177 Objects are flattened following this format, so if you had
178 \fB{"scripts":{"install":"foo\.js"}}\fP in your package\.json, then you'd
179 see this in the script:
183 process\.env\.npm_package_scripts_install === "foo\.js"
188 For example, if your package\.json contains this:
193 { "install" : "scripts/install\.js"
194 , "postinstall" : "scripts/install\.js"
195 , "uninstall" : "scripts/uninstall\.js"
201 then \fBscripts/install\.js\fP will be called for the install
202 and post\-install stages of the lifecycle, and \fBscripts/uninstall\.js\fP
203 will be called when the package is uninstalled\. Since
204 \fBscripts/install\.js\fP is running for two different phases, it would
205 be wise in this case to look at the \fBnpm_lifecycle_event\fP environment
208 If you want to run a make command, you can do so\. This works just
214 { "preinstall" : "\./configure"
215 , "install" : "make && make install"
216 , "test" : "make test"
223 Scripts are run by passing the line as a script argument to \fBsh\fP\|\.
225 If the script exits with a code other than 0, then this will abort the
228 Note that these script files don't have to be nodejs or even
229 javascript programs\. They just have to be some kind of executable
233 If you want to run a specific script at a specific lifecycle event for
234 ALL packages, then you can use a hook script\.
236 Place an executable file at \fBnode_modules/\.hooks/{eventname}\fP, and
237 it'll get run for all packages when they are going through that point
238 in the package lifecycle for any packages installed in that root\.
240 Hook scripts are run exactly the same way as package\.json scripts\.
241 That is, they are in a separate child process, with the env described
246 Don't exit with a non\-zero error code unless you \fIreally\fR mean it\.
247 Except for uninstall scripts, this will cause the npm action to
248 fail, and potentially be rolled back\. If the failure is minor or
249 only will prevent some optional features, then it's better to just
250 print a warning and exit successfully\.
252 Try not to use scripts to do what npm can do for you\. Read through
253 npm help 5 \fBpackage\.json\fP to see all the things that you can specify and enable
254 by simply describing your package appropriately\. In general, this
255 will lead to a more robust and consistent state\.
257 Inspect the env to determine where to put things\. For instance, if
258 the \fBnpm_config_binroot\fP environment variable is set to \fB/home/user/bin\fP, then
259 don't try to install executables into \fB/usr/local/bin\fP\|\. The user
260 probably set it up that way for a reason\.
262 Don't prefix your script commands with "sudo"\. If root permissions
263 are required for some reason, then it'll fail with that error, and
264 the user will sudo the npm command in question\.
266 Don't use \fBinstall\fP\|\. Use a \fB\|\.gyp\fP file for compilation, and \fBprepublish\fP
267 for anything else\. You should almost never have to explicitly set a
268 preinstall or install script\. If you are doing this, please consider if
269 there is another option\. The only valid use of \fBinstall\fP or \fBpreinstall\fP
270 scripts is for compilation which must be done on the target architecture\.
278 npm help 5 package\.json
280 npm help 7 developers
Code Review / simantics / district.git / blob