Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       npm-scripts - How npm handles the "scripts" field

       npm  supports  the "scripts" property of	the package.json file, for the
       following scripts:

       o prepublish: Run BEFORE	the package is packed and published,  as  well
	 as on local npm install without any arguments.	(See below)

       o prepare:  Run both BEFORE the package is packed and published,	on lo-
	 cal npm install without any arguments,	and when installing git	depen-
	 dencies (See below). This is run AFTER	prepublish, but	BEFORE prepub-

       o prepublishOnly: Run BEFORE the	package	is prepared and	 packed,  ONLY
	 on npm	publish. (See below.)

       o prepack:  run	BEFORE	a tarball is packed (on	npm pack, npm publish,
	 and when installing git dependencies)

       o postpack: Run AFTER the tarball has been generated and	moved  to  its
	 final destination.

       o publish, postpublish: Run AFTER the package is	published.

       o preinstall: Run BEFORE	the package is installed

       o install, postinstall: Run AFTER the package is	installed.

       o preuninstall, uninstall: Run BEFORE the package is uninstalled.

       o postuninstall:	Run AFTER the package is uninstalled.

       o preversion: Run BEFORE	bumping	the package version.

       o version: Run AFTER bumping the	package	version, but BEFORE commit.

       o postversion: Run AFTER	bumping	the package version, and AFTER commit.

       o pretest, test,	posttest: Run by the npm test command.

       o prestop, stop,	poststop: Run by the npm stop command.

       o prestart, start, poststart: Run by the	npm start command.

       o 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.

       o preshrinkwrap,	 shrinkwrap, postshrinkwrap: Run by the	npm shrinkwrap

       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

       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 be-
       low).   It  has	also  turned  out  to  be, in practice,	very confusing	 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 for a much lengthier	justi-
       fication, with further reading, for this	change.

       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

       o Compiling CoffeeScript	source code into JavaScript.

       o Creating minified versions of JavaScript source code.

       o 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 variabil-
       ity.  Additionally, this	means that:

       o You  can  depend  on  coffee-script as	a devDependency, and thus your
	 users don't need to have it installed.

       o You don't need	to include minifiers in	 your  package,	 reducing  the
	 size for your users.

       o You  don't  need  to  rely on your users having curl or wget or other
	 system	tools on the target machines.

       npm will	default	some script values based on package contents.

       o "start": "node	server.js": If there is	a server.js file in  the  root
	 of  your  package,  then  npm	will default the start command to node

       o "install": "node-gyp rebuild":	If there is a binding.gyp file in  the
	 root of your package and you haven't defined your own install or pre-
	 install scripts, npm will default the install command to compile  us-
	 ing node-gyp.

       If npm was invoked with root privileges,	then it	will change the	uid to
       the user	account	or uid specified by the	user config, which defaults to
       nobody.	Set the	unsafe-perm flag to run	scripts	with root privileges.

       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.

       If  you	depend	on  modules  that define executable scripts, like test
       suites, then those executables will be added to the PATH	for  executing
       the scripts.  So, if your package.json has this:

	 { "name" : "foo"
	 , "dependencies" : { "bar" : "0.1.x" }
	 , "scripts": {	"start"	: "bar ./test" } }

       then  you  could	 run npm start to execute the bar script, which	is ex-
       ported into the node_modules/.bin directory on npm install.

   package.json	vars
       The package.json	fields are tacked onto the  npm_package_  prefix.  So,
       for  instance,  if  you	had  {"name":"foo", "version":"1.2.5"} in your
       package.json file, then your package scripts would have	the  npm_pack-
       age_name	environment variable set to "foo", and the npm_package_version
       set to "1.2.5".	You can	access	these  variables  in  your  code  with
       process.env.npm_package_name  and  process.env.npm_package_version, and
       so on for other fields.

       Configuration parameters	are put	in the environment with	 the  npm_con-
       fig_  prefix.  For  instance, you can view the effective	root config by
       checking	the npm_config_root environment	variable.

   Special: package.json config	object
       The package.json	"config" keys are overwritten in  the  environment  if
       there  is  a config param of <name>[@<version>]:<key>.  For example, if
       the package.json	has this:

	 { "name" : "foo"
	 , "config" : {	"port" : "8080"	}
	 , "scripts" : { "start" : "node server.js" } }

       and the server.js is this:


       then the	user could change the behavior by doing:

	 npm config set	foo:port 80

   current lifecycle event
       Lastly, the npm_lifecycle_event environment variable is set  to	which-
       ever  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.

       Objects	 are   flattened   following   this  format,  so  if  you  had
       {"scripts":{"install":"foo.js"}}	in your	package.json, then  you'd  see
       this in the script:

	 process.env.npm_package_scripts_install === "foo.js"

       For example, if your package.json contains this:

	 { "scripts" :
	   { "install" : "scripts/install.js"
	   , "postinstall" : "scripts/install.js"
	   , "uninstall" : "scripts/uninstall.js"

       then scripts/install.js will be called for the install and post-install
       stages of the lifecycle,	and scripts/uninstall.js will be  called  when
       the  package  is	 uninstalled.  Since scripts/install.js	is running for
       two different phases, it	would be wise in this  case  to	 look  at  the
       npm_lifecycle_event environment variable.

       If  you	want  to  run  a make command, you can do so.  This works just

	 { "scripts" :
	   { "preinstall" : "./configure"
	   , "install" : "make && make install"
	   , "test" : "make test"

       Scripts are run by passing the line as a	script argument	to sh.

       If the script exits with	a code other than 0, then this will abort  the

       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.

       If you want to run a specific script at a specific lifecycle event  for
       ALL packages, then you can use a	hook script.

       Place  an executable file at node_modules/.hooks/{eventname}, 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.

       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

       o Don't exit with a non-zero error code unless you really mean it.  Ex-
	 cept 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.

       o Try  not  to use scripts to do	what npm can do	for you.  Read through
	 npm help 5 package.json to see	all the	things that  you  can  specify
	 and  enable by	simply describing your package appropriately.  In gen-
	 eral, this will lead to a more	robust and consistent state.

       o Inspect the env to determine where to put things.  For	 instance,  if
	 the npm_config_binroot	environment variable is	set to /home/user/bin,
	 then don't try	to install executables into /usr/local/bin.  The  user
	 probably set it up that way for a reason.

       o 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.

       o Don't	use  install.  Use a .gyp file for compilation,	and prepublish
	 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 install  or	prein-
	 stall scripts is for compilation which	must be	done on	the target ar-

       o npm help run-script

       o npm help 5 package.json

       o npm help 7 developers

       o npm help install

				 October 2019			NPM-SCRIPTS(7)


Want to link to this manual page? Use this URL:

home | help