📁 File Manager Pro
v10.0.3 | PHP: 8.1.34
Server: Apache
2026-06-22 23:38:34
📂
/ (Root)
/
opt
/
alt
/
alt-nodejs22
/
root
/
usr
/
share
/
doc
/
alt-nodejs22-nodejs-docs-22.22.3
/
npm
/
docs
/
output
/
using-npm
📍 /opt/alt/alt-nodejs22/root/usr/share/doc/alt-nodejs22-nodejs-docs-22.22.3/npm/docs/output/using-npm
🔄 Refresh
✏️
Editing: scripts.html
Read Only
<!DOCTYPE html><html><head> <meta charset="utf-8"> <title>scripts</title> <style> body { background-color: #ffffff; color: #24292e; margin: 0; line-height: 1.5; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; } #rainbar { height: 10px; background-image: linear-gradient(139deg, #fb8817, #ff4b01, #c12127, #e02aff); } a { text-decoration: none; color: #0366d6; } a:hover { text-decoration: underline; } pre { margin: 1em 0px; padding: 1em; border: solid 1px #e1e4e8; border-radius: 6px; display: block; overflow: auto; white-space: pre; background-color: #f6f8fa; color: #393a34; } code { font-family: SFMono-Regular, Consolas, "Liberation Mono", Menlo, Courier, monospace; font-size: 85%; padding: 0.2em 0.4em; background-color: #f6f8fa; color: #393a34; } pre > code { padding: 0; background-color: inherit; color: inherit; } h1, h2, h3 { font-weight: 600; } #logobar { background-color: #333333; margin: 0 auto; padding: 1em 4em; } #logobar .logo { float: left; } #logobar .title { font-weight: 600; color: #dddddd; float: left; margin: 5px 0 0 1em; } #logobar:after { content: ""; display: block; clear: both; } #content { margin: 0 auto; padding: 0 4em; } #table_of_contents > h2 { font-size: 1.17em; } #table_of_contents ul:first-child { border: solid 1px #e1e4e8; border-radius: 6px; padding: 1em; background-color: #f6f8fa; color: #393a34; } #table_of_contents ul { list-style-type: none; padding-left: 1.5em; } #table_of_contents li { font-size: 0.9em; } #table_of_contents li a { color: #000000; } header.title { border-bottom: solid 1px #e1e4e8; } header.title > h1 { margin-bottom: 0.25em; } header.title > .description { display: block; margin-bottom: 0.5em; line-height: 1; } header.title .version { font-size: 0.8em; color: #666666; } footer#edit { border-top: solid 1px #e1e4e8; margin: 3em 0 4em 0; padding-top: 2em; } </style> </head> <body> <div id="banner"> <div id="rainbar"></div> <div id="logobar"> <svg class="logo" role="img" height="32" width="32" viewBox="0 0 700 700"> <polygon fill="#cb0000" points="0,700 700,700 700,0 0,0"></polygon> <polygon fill="#ffffff" points="150,550 350,550 350,250 450,250 450,550 550,550 550,150 150,150"></polygon> </svg> <div class="title"> npm command-line interface </div> </div> </div> <section id="content"> <header class="title"> <h1 id="----scripts----1098"> <span>scripts</span> <span class="version">@10.9.8</span> </h1> <span class="description">How npm handles the "scripts" field</span> </header> <section id="table_of_contents"> <h2 id="table-of-contents">Table of contents</h2> <div id="_table_of_contents"><ul><li><a href="#description">Description</a></li><li><a href="#pre--post-scripts">Pre & Post Scripts</a></li><li><a href="#life-cycle-scripts">Life Cycle Scripts</a></li><ul><li><a href="#prepare-and-prepublish">Prepare and Prepublish</a></li><li><a href="#dependencies">Dependencies</a></li></ul><li><a href="#life-cycle-operation-order">Life Cycle Operation Order</a></li><ul><li><a href="#npm-cache-add"><a href="../commands/npm-cache.html"><code>npm cache add</code></a></a></li><li><a href="#npm-ci"><a href="../commands/npm-ci.html"><code>npm ci</code></a></a></li><li><a href="#npm-diff"><a href="../commands/npm-diff.html"><code>npm diff</code></a></a></li><li><a href="#npm-install"><a href="../commands/npm-install.html"><code>npm install</code></a></a></li><li><a href="#npm-pack"><a href="../commands/npm-pack.html"><code>npm pack</code></a></a></li><li><a href="#npm-publish"><a href="../commands/npm-publish.html"><code>npm publish</code></a></a></li><li><a href="#npm-rebuild"><a href="../commands/npm-rebuild.html"><code>npm rebuild</code></a></a></li><li><a href="#npm-restart"><a href="../commands/npm-restart.html"><code>npm restart</code></a></a></li><li><a href="#npm-run-user-defined"><a href="../commands/npm-run-script.html"><code>npm run <user defined></code></a></a></li><li><a href="#npm-start"><a href="../commands/npm-start.html"><code>npm start</code></a></a></li><li><a href="#npm-stop"><a href="../commands/npm-stop.html"><code>npm stop</code></a></a></li><li><a href="#npm-test"><a href="../commands/npm-test.html"><code>npm test</code></a></a></li><li><a href="#npm-version"><a href="../commands/npm-version.html"><code>npm version</code></a></a></li><li><a href="#a-note-on-a-lack-of-npm-uninstall-scripts">A Note on a lack of <a href="../commands/npm-uninstall.html"><code>npm uninstall</code></a> scripts</a></li></ul><li><a href="#user">User</a></li><li><a href="#environment">Environment</a></li><ul><li><a href="#path">path</a></li><li><a href="#packagejson-vars">package.json vars</a></li><li><a href="#current-lifecycle-event">current lifecycle event</a></li></ul><li><a href="#examples">Examples</a></li><li><a href="#exiting">Exiting</a></li><li><a href="#best-practices">Best Practices</a></li><li><a href="#see-also">See Also</a></li></ul></div> </section> <div id="_content"><h3 id="description">Description</h3> <p>The <code>"scripts"</code> property of your <code>package.json</code> 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 <code>npm run-script <stage></code> or <code>npm run <stage></code> for short. <em>Pre</em> and <em>post</em> commands with matching names will be run for those as well (e.g. <code>premyscript</code>, <code>myscript</code>, <code>postmyscript</code>). Scripts from dependencies can be run with <code>npm explore <pkg> -- npm run <stage></code>.</p> <h3 id="pre--post-scripts">Pre & Post Scripts</h3> <p>To create "pre" or "post" scripts for any scripts defined in the <code>"scripts"</code> section of the <code>package.json</code>, simply create another script <em>with a matching name</em> and add "pre" or "post" to the beginning of them.</p> <pre><code class="language-json">{ "scripts": { "precompress": "{{ executes BEFORE the `compress` script }}", "compress": "{{ run command to compress files }}", "postcompress": "{{ executes AFTER `compress` script }}" } } </code></pre> <p>In this example <code>npm run compress</code> would execute these scripts as described.</p> <h3 id="life-cycle-scripts">Life Cycle Scripts</h3> <p>There are some special life cycle scripts that happen only in certain situations. These scripts happen in addition to the <code>pre<event></code>, <code>post<event></code>, and <code><event></code> scripts.</p> <ul> <li><code>prepare</code>, <code>prepublish</code>, <code>prepublishOnly</code>, <code>prepack</code>, <code>postpack</code>, <code>dependencies</code></li> </ul> <p><strong>prepare</strong> (since <code>npm@4.0.0</code>)</p> <ul> <li> <p>Runs BEFORE the package is packed, i.e. during <code>npm publish</code> and <code>npm pack</code></p> </li> <li> <p>Runs on local <code>npm install</code> without any arguments</p> </li> <li> <p>Runs AFTER <code>prepublish</code>, but BEFORE <code>prepublishOnly</code></p> </li> <li> <p>NOTE: If a package being installed through git contains a <code>prepare</code> script, its <code>dependencies</code> and <code>devDependencies</code> will be installed, and the prepare script will be run, before the package is packaged and installed.</p> </li> <li> <p>As of <code>npm@7</code> these scripts run in the background. To see the output, run with: <code>--foreground-scripts</code>.</p> </li> </ul> <p><strong>prepublish</strong> (DEPRECATED)</p> <ul> <li>Does not run during <code>npm publish</code>, but does run during <code>npm ci</code> and <code>npm install</code>. See below for more info.</li> </ul> <p><strong>prepublishOnly</strong></p> <ul> <li>Runs BEFORE the package is prepared and packed, ONLY on <code>npm publish</code>.</li> </ul> <p><strong>prepack</strong></p> <ul> <li>Runs BEFORE a tarball is packed (on "<code>npm pack</code>", "<code>npm publish</code>", and when installing a git dependency).</li> <li>NOTE: "<code>npm run pack</code>" is NOT the same as "<code>npm pack</code>". "<code>npm run pack</code>" is an arbitrary user defined script name, where as, "<code>npm pack</code>" is a CLI defined command.</li> </ul> <p><strong>postpack</strong></p> <ul> <li>Runs AFTER the tarball has been generated but before it is moved to its final destination (if at all, publish does not save the tarball locally)</li> </ul> <p><strong>dependencies</strong></p> <ul> <li>Runs AFTER any operations that modify the <code>node_modules</code> directory IF changes occurred.</li> <li>Does NOT run in global mode</li> </ul> <h4 id="prepare-and-prepublish">Prepare and Prepublish</h4> <p><strong>Deprecation Note: prepublish</strong></p> <p>Since <code>npm@1.1.71</code>, the npm CLI has run the <code>prepublish</code> script for both <code>npm publish</code> and <code>npm install</code>, 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, <a href="https://github.com/npm/npm/issues/10074">very confusing</a>. As of <code>npm@4.0.0</code>, a new event has been introduced, <code>prepare</code>, that preserves this existing behavior. A <em>new</em> event, <code>prepublishOnly</code> has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on <code>npm publish</code> (for instance, running the tests one last time to ensure they're in good shape).</p> <p>See <a href="https://github.com/npm/npm/issues/10074">https://github.com/npm/npm/issues/10074</a> for a much lengthier justification, with further reading, for this change.</p> <p><strong>Use Cases</strong></p> <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 <code>prepublish</code> script. This includes tasks such as:</p> <ul> <li>Compiling CoffeeScript source code into JavaScript.</li> <li>Creating minified versions of JavaScript source code.</li> <li>Fetching remote resources that your package will use.</li> </ul> <p>The advantage of doing these things at <code>prepublish</code> time is that they can be done once, in a single place, thus reducing complexity and variability. Additionally, this means that:</p> <ul> <li>You can depend on <code>coffee-script</code> as a <code>devDependency</code>, and thus your users don't need to have it installed.</li> <li>You don't need to include minifiers in your package, reducing the size for your users.</li> <li>You don't need to rely on your users having <code>curl</code> or <code>wget</code> or other system tools on the target machines.</li> </ul> <h4 id="dependencies">Dependencies</h4> <p>The <code>dependencies</code> script is run any time an <code>npm</code> command causes changes to the <code>node_modules</code> directory. It is run AFTER the changes have been applied and the <code>package.json</code> and <code>package-lock.json</code> files have been updated.</p> <h3 id="life-cycle-operation-order">Life Cycle Operation Order</h3> <h4 id="npm-cache-add"><a href="../commands/npm-cache.html"><code>npm cache add</code></a></h4> <ul> <li><code>prepare</code></li> </ul> <h4 id="npm-ci"><a href="../commands/npm-ci.html"><code>npm ci</code></a></h4> <ul> <li><code>preinstall</code></li> <li><code>install</code></li> <li><code>postinstall</code></li> <li><code>prepublish</code></li> <li><code>preprepare</code></li> <li><code>prepare</code></li> <li><code>postprepare</code></li> </ul> <p>These all run after the actual installation of modules into <code>node_modules</code>, in order, with no internal actions happening in between</p> <h4 id="npm-diff"><a href="../commands/npm-diff.html"><code>npm diff</code></a></h4> <ul> <li><code>prepare</code></li> </ul> <h4 id="npm-install"><a href="../commands/npm-install.html"><code>npm install</code></a></h4> <p>These also run when you run <code>npm install -g <pkg-name></code></p> <ul> <li><code>preinstall</code></li> <li><code>install</code></li> <li><code>postinstall</code></li> <li><code>prepublish</code></li> <li><code>preprepare</code></li> <li><code>prepare</code></li> <li><code>postprepare</code></li> </ul> <p>If there is a <code>binding.gyp</code> file in the root of your package and you haven't defined your own <code>install</code> or <code>preinstall</code> scripts, npm will default the <code>install</code> command to compile using node-gyp via <code>node-gyp rebuild</code></p> <p>These are run from the scripts of <code><pkg-name></code></p> <h4 id="npm-pack"><a href="../commands/npm-pack.html"><code>npm pack</code></a></h4> <ul> <li><code>prepack</code></li> <li><code>prepare</code></li> <li><code>postpack</code></li> </ul> <h4 id="npm-publish"><a href="../commands/npm-publish.html"><code>npm publish</code></a></h4> <ul> <li><code>prepublishOnly</code></li> <li><code>prepack</code></li> <li><code>prepare</code></li> <li><code>postpack</code></li> <li><code>publish</code></li> <li><code>postpublish</code></li> </ul> <h4 id="npm-rebuild"><a href="../commands/npm-rebuild.html"><code>npm rebuild</code></a></h4> <ul> <li><code>preinstall</code></li> <li><code>install</code></li> <li><code>postinstall</code></li> <li><code>prepare</code></li> </ul> <p><code>prepare</code> is only run if the current directory is a symlink (e.g. with linked packages)</p> <h4 id="npm-restart"><a href="../commands/npm-restart.html"><code>npm restart</code></a></h4> <p>If there is a <code>restart</code> script defined, these events are run, otherwise <code>stop</code> and <code>start</code> are both run if present, including their <code>pre</code> and <code>post</code> iterations)</p> <ul> <li><code>prerestart</code></li> <li><code>restart</code></li> <li><code>postrestart</code></li> </ul> <h4 id="npm-run-user-defined"><a href="../commands/npm-run-script.html"><code>npm run <user defined></code></a></h4> <ul> <li><code>pre<user-defined></code></li> <li><code><user-defined></code></li> <li><code>post<user-defined></code></li> </ul> <h4 id="npm-start"><a href="../commands/npm-start.html"><code>npm start</code></a></h4> <ul> <li><code>prestart</code></li> <li><code>start</code></li> <li><code>poststart</code></li> </ul> <p>If there is a <code>server.js</code> file in the root of your package, then npm will default the <code>start</code> command to <code>node server.js</code>. <code>prestart</code> and <code>poststart</code> will still run in this case.</p> <h4 id="npm-stop"><a href="../commands/npm-stop.html"><code>npm stop</code></a></h4> <ul> <li><code>prestop</code></li> <li><code>stop</code></li> <li><code>poststop</code></li> </ul> <h4 id="npm-test"><a href="../commands/npm-test.html"><code>npm test</code></a></h4> <ul> <li><code>pretest</code></li> <li><code>test</code></li> <li><code>posttest</code></li> </ul> <h4 id="npm-version"><a href="../commands/npm-version.html"><code>npm version</code></a></h4> <ul> <li><code>preversion</code></li> <li><code>version</code></li> <li><code>postversion</code></li> </ul> <h4 id="a-note-on-a-lack-of-npm-uninstall-scripts">A Note on a lack of <a href="../commands/npm-uninstall.html"><code>npm uninstall</code></a> scripts</h4> <p>While npm v6 had <code>uninstall</code> lifecycle scripts, npm v7 does not. Removal of a package can happen for a wide variety of reasons, and there's no clear way to currently give the script enough context to be useful.</p> <p>Reasons for a package removal include:</p> <ul> <li>a user directly uninstalled this package</li> <li>a user uninstalled a dependant package and so this dependency is being uninstalled</li> <li>a user uninstalled a dependant package but another package also depends on this version</li> <li>this version has been merged as a duplicate with another version</li> <li>etc.</li> </ul> <p>Due to the lack of necessary context, <code>uninstall</code> lifecycle scripts are not implemented and will not function.</p> <h3 id="user">User</h3> <p>When npm is run as root, scripts are always run with the effective uid and gid of the working directory owner.</p> <h3 id="environment">Environment</h3> <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.</p> <h4 id="path">path</h4> <p>If you depend on modules that define executable scripts, like test suites, then those executables will be added to the <code>PATH</code> for executing the scripts. So, if your package.json has this:</p> <pre><code class="language-json">{ "name" : "foo", "dependencies" : { "bar" : "0.1.x" }, "scripts": { "start" : "bar ./test" } } </code></pre> <p>then you could run <code>npm start</code> to execute the <code>bar</code> script, which is exported into the <code>node_modules/.bin</code> directory on <code>npm install</code>.</p> <h4 id="packagejson-vars">package.json vars</h4> <p>The package.json fields are tacked onto the <code>npm_package_</code> prefix. So, for instance, if you had <code>{"name":"foo", "version":"1.2.5"}</code> in your package.json file, then your package scripts would have the <code>npm_package_name</code> environment variable set to "foo", and the <code>npm_package_version</code> set to "1.2.5". You can access these variables in your code with <code>process.env.npm_package_name</code> and <code>process.env.npm_package_version</code>, and so on for other fields.</p> <p>See <a href="../configuring-npm/package-json.html"><code>package.json</code></a> for more on package configs.</p> <h4 id="current-lifecycle-event">current lifecycle event</h4> <p>Lastly, the <code>npm_lifecycle_event</code> 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> <p>Objects are flattened following this format, so if you had <code>{"scripts":{"install":"foo.js"}}</code> in your package.json, then you'd see this in the script:</p> <pre><code class="language-bash">process.env.npm_package_scripts_install === "foo.js" </code></pre> <h3 id="examples">Examples</h3> <p>For example, if your package.json contains this:</p> <pre><code class="language-json">{ "scripts" : { "install" : "scripts/install.js", "postinstall" : "scripts/install.js" } } </code></pre> <p>then <code>scripts/install.js</code> will be called for the install and post-install stages of the lifecycle. Since <code>scripts/install.js</code> is running for two different phases, it would be wise in this case to look at the <code>npm_lifecycle_event</code> environment variable.</p> <p>If you want to run a make command, you can do so. This works just fine:</p> <pre><code class="language-json">{ "scripts" : { "preinstall" : "./configure", "install" : "make && make install", "test" : "make test" } } </code></pre> <h3 id="exiting">Exiting</h3> <p>Scripts are run by passing the line as a script argument to <code>sh</code>.</p> <p>If the script exits with a code other than 0, then this will abort the process.</p> <p>Note that these script files don't have to be Node.js or even JavaScript programs. They just have to be some kind of executable file.</p> <h3 id="best-practices">Best Practices</h3> <ul> <li>Don't exit with a non-zero error code unless you <em>really</em> mean it. If the failure is minor or only will prevent some optional features, then it's better to just print a warning and exit successfully.</li> <li>Try not to use scripts to do what npm can do for you. Read through <a href="../configuring-npm/package-json.html"><code>package.json</code></a> 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.</li> <li>Inspect the env to determine where to put things. For instance, if the <code>npm_config_binroot</code> environment variable is set to <code>/home/user/bin</code>, then don't try to install executables into <code>/usr/local/bin</code>. The user probably set it up that way for a reason.</li> <li>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.</li> <li>Don't use <code>install</code>. Use a <code>.gyp</code> file for compilation, and <code>prepare</code> 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 <code>install</code> or <code>preinstall</code> scripts is for compilation which must be done on the target architecture.</li> <li>Scripts are run from the root of the package folder, regardless of what the current working directory is when <code>npm</code> is invoked. If you want your script to use different behavior based on what subdirectory you're in, you can use the <code>INIT_CWD</code> environment variable, which holds the full path you were in when you ran <code>npm run</code>.</li> </ul> <h3 id="see-also">See Also</h3> <ul> <li><a href="../commands/npm-run-script.html">npm run-script</a></li> <li><a href="../configuring-npm/package-json.html">package.json</a></li> <li><a href="../using-npm/developers.html">npm developers</a></li> <li><a href="../commands/npm-install.html">npm install</a></li> </ul></div> <footer id="edit"> <a href="https://github.com/npm/cli/edit/latest/docs/content/using-npm/scripts.md"> <svg role="img" viewBox="0 0 16 16" width="16" height="16" fill="currentcolor" style="vertical-align: text-bottom; margin-right: 0.3em;"> <path fill-rule="evenodd" d="M11.013 1.427a1.75 1.75 0 012.474 0l1.086 1.086a1.75 1.75 0 010 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 01-.927-.928l.929-3.25a1.75 1.75 0 01.445-.758l8.61-8.61zm1.414 1.06a.25.25 0 00-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 000-.354l-1.086-1.086zM11.189 6.25L9.75 4.81l-6.286 6.287a.25.25 0 00-.064.108l-.558 1.953 1.953-.558a.249.249 0 00.108-.064l6.286-6.286z"></path> </svg> Edit this page on GitHub </a> </footer> </section> </body></html>
💾 Save Changes
❌ Cancel