mirror of
https://github.com/S2-/minifyfromhtml.git
synced 2025-08-03 20:30:04 +02:00
update packages to latest version
This commit is contained in:
187
node_modules/npm/html/doc/files/npm-folders.html
generated
vendored
Normal file
187
node_modules/npm/html/doc/files/npm-folders.html
generated
vendored
Normal file
@@ -0,0 +1,187 @@
|
||||
<!doctype html>
|
||||
<html>
|
||||
<title>npm-folders</title>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" type="text/css" href="../../static/style.css">
|
||||
<link rel="canonical" href="https://www.npmjs.org/doc/files/npm-folders.html">
|
||||
<script async=true src="../../static/toc.js"></script>
|
||||
|
||||
<body>
|
||||
<div id="wrapper">
|
||||
|
||||
<h1><a href="../files/npm-folders.html">npm-folders</a></h1> <p>Folder Structures Used by npm</p>
|
||||
<h2 id="description">DESCRIPTION</h2>
|
||||
<p>npm puts various things on your computer. That's its job.</p>
|
||||
<p>This document will tell you what it puts where.</p>
|
||||
<h3 id="tl-dr">tl;dr</h3>
|
||||
<ul>
|
||||
<li>Local install (default): puts stuff in <code>./node_modules</code> of the current
|
||||
package root.</li>
|
||||
<li>Global install (with <code>-g</code>): puts stuff in /usr/local or wherever node
|
||||
is installed.</li>
|
||||
<li>Install it <strong>locally</strong> if you're going to <code>require()</code> it.</li>
|
||||
<li>Install it <strong>globally</strong> if you're going to run it on the command line.</li>
|
||||
<li>If you need both, then install it in both places, or use <code>npm link</code>.</li>
|
||||
</ul>
|
||||
<h3 id="prefix-configuration">prefix Configuration</h3>
|
||||
<p>The <code>prefix</code> config defaults to the location where node is installed.
|
||||
On most systems, this is <code>/usr/local</code>. On windows, this is the exact
|
||||
location of the node.exe binary. On Unix systems, it's one level up,
|
||||
since node is typically installed at <code>{prefix}/bin/node</code> rather than
|
||||
<code>{prefix}/node.exe</code>.</p>
|
||||
<p>When the <code>global</code> flag is set, npm installs things into this prefix.
|
||||
When it is not set, it uses the root of the current package, or the
|
||||
current working directory if not in a package already.</p>
|
||||
<h3 id="node-modules">Node Modules</h3>
|
||||
<p>Packages are dropped into the <code>node_modules</code> folder under the <code>prefix</code>.
|
||||
When installing locally, this means that you can
|
||||
<code>require("packagename")</code> to load its main module, or
|
||||
<code>require("packagename/lib/path/to/sub/module")</code> to load other modules.</p>
|
||||
<p>Global installs on Unix systems go to <code>{prefix}/lib/node_modules</code>.
|
||||
Global installs on Windows go to <code>{prefix}/node_modules</code> (that is, no
|
||||
<code>lib</code> folder.)</p>
|
||||
<p>Scoped packages are installed the same way, except they are grouped together
|
||||
in a sub-folder of the relevant <code>node_modules</code> folder with the name of that
|
||||
scope prefix by the @ symbol, e.g. <code>npm install @myorg/package</code> would place
|
||||
the package in <code>{prefix}/node_modules/@myorg/package</code>. See <code><a href="../misc/scope.html">scope(7)</a></code> for
|
||||
more details.</p>
|
||||
<p>If you wish to <code>require()</code> a package, then install it locally.</p>
|
||||
<h3 id="executables">Executables</h3>
|
||||
<p>When in global mode, executables are linked into <code>{prefix}/bin</code> on Unix,
|
||||
or directly into <code>{prefix}</code> on Windows.</p>
|
||||
<p>When in local mode, executables are linked into
|
||||
<code>./node_modules/.bin</code> so that they can be made available to scripts run
|
||||
through npm. (For example, so that a test runner will be in the path
|
||||
when you run <code>npm test</code>.)</p>
|
||||
<h3 id="man-pages">Man Pages</h3>
|
||||
<p>When in global mode, man pages are linked into <code>{prefix}/share/man</code>.</p>
|
||||
<p>When in local mode, man pages are not installed.</p>
|
||||
<p>Man pages are not installed on Windows systems.</p>
|
||||
<h3 id="cache">Cache</h3>
|
||||
<p>See <code><a href="../cli/npm-cache.html">npm-cache(1)</a></code>. Cache files are stored in <code>~/.npm</code> on Posix, or
|
||||
<code>~/npm-cache</code> on Windows.</p>
|
||||
<p>This is controlled by the <code>cache</code> configuration param.</p>
|
||||
<h3 id="temp-files">Temp Files</h3>
|
||||
<p>Temporary files are stored by default in the folder specified by the
|
||||
<code>tmp</code> config, which defaults to the TMPDIR, TMP, or TEMP environment
|
||||
variables, or <code>/tmp</code> on Unix and <code>c:\windows\temp</code> on Windows.</p>
|
||||
<p>Temp files are given a unique folder under this root for each run of the
|
||||
program, and are deleted upon successful exit.</p>
|
||||
<h2 id="more-information">More Information</h2>
|
||||
<p>When installing locally, npm first tries to find an appropriate
|
||||
<code>prefix</code> folder. This is so that <code>npm install foo@1.2.3</code> will install
|
||||
to the sensible root of your package, even if you happen to have <code>cd</code>ed
|
||||
into some other folder.</p>
|
||||
<p>Starting at the $PWD, npm will walk up the folder tree checking for a
|
||||
folder that contains either a <code>package.json</code> file, or a <code>node_modules</code>
|
||||
folder. If such a thing is found, then that is treated as the effective
|
||||
"current directory" for the purpose of running npm commands. (This
|
||||
behavior is inspired by and similar to git's .git-folder seeking
|
||||
logic when running git commands in a working dir.)</p>
|
||||
<p>If no package root is found, then the current folder is used.</p>
|
||||
<p>When you run <code>npm install foo@1.2.3</code>, then the package is loaded into
|
||||
the cache, and then unpacked into <code>./node_modules/foo</code>. Then, any of
|
||||
foo's dependencies are similarly unpacked into
|
||||
<code>./node_modules/foo/node_modules/...</code>.</p>
|
||||
<p>Any bin files are symlinked to <code>./node_modules/.bin/</code>, so that they may
|
||||
be found by npm scripts when necessary.</p>
|
||||
<h3 id="global-installation">Global Installation</h3>
|
||||
<p>If the <code>global</code> configuration is set to true, then npm will
|
||||
install packages "globally".</p>
|
||||
<p>For global installation, packages are installed roughly the same way,
|
||||
but using the folders described above.</p>
|
||||
<h3 id="cycles-conflicts-and-folder-parsimony">Cycles, Conflicts, and Folder Parsimony</h3>
|
||||
<p>Cycles are handled using the property of node's module system that it
|
||||
walks up the directories looking for <code>node_modules</code> folders. So, at every
|
||||
stage, if a package is already installed in an ancestor <code>node_modules</code>
|
||||
folder, then it is not installed at the current location.</p>
|
||||
<p>Consider the case above, where <code>foo -> bar -> baz</code>. Imagine if, in
|
||||
addition to that, baz depended on bar, so you'd have:
|
||||
<code>foo -> bar -> baz -> bar -> baz ...</code>. However, since the folder
|
||||
structure is: <code>foo/node_modules/bar/node_modules/baz</code>, there's no need to
|
||||
put another copy of bar into <code>.../baz/node_modules</code>, since when it calls
|
||||
require("bar"), it will get the copy that is installed in
|
||||
<code>foo/node_modules/bar</code>.</p>
|
||||
<p>This shortcut is only used if the exact same
|
||||
version would be installed in multiple nested <code>node_modules</code> folders. It
|
||||
is still possible to have <code>a/node_modules/b/node_modules/a</code> if the two
|
||||
"a" packages are different versions. However, without repeating the
|
||||
exact same package multiple times, an infinite regress will always be
|
||||
prevented.</p>
|
||||
<p>Another optimization can be made by installing dependencies at the
|
||||
highest level possible, below the localized "target" folder.</p>
|
||||
<h4 id="example">Example</h4>
|
||||
<p>Consider this dependency graph:</p>
|
||||
<pre><code>foo
|
||||
+-- blerg@1.2.5
|
||||
+-- bar@1.2.3
|
||||
| +-- blerg@1.x (latest=1.3.7)
|
||||
| +-- baz@2.x
|
||||
| | `-- quux@3.x
|
||||
| | `-- bar@1.2.3 (cycle)
|
||||
| `-- asdf@*
|
||||
`-- baz@1.2.3
|
||||
`-- quux@3.x
|
||||
`-- bar
|
||||
</code></pre><p>In this case, we might expect a folder structure like this:</p>
|
||||
<pre><code>foo
|
||||
+-- node_modules
|
||||
+-- blerg (1.2.5) <---[A]
|
||||
+-- bar (1.2.3) <---[B]
|
||||
| `-- node_modules
|
||||
| +-- baz (2.0.2) <---[C]
|
||||
| | `-- node_modules
|
||||
| | `-- quux (3.2.0)
|
||||
| `-- asdf (2.3.4)
|
||||
`-- baz (1.2.3) <---[D]
|
||||
`-- node_modules
|
||||
`-- quux (3.2.0) <---[E]
|
||||
</code></pre><p>Since foo depends directly on <code>bar@1.2.3</code> and <code>baz@1.2.3</code>, those are
|
||||
installed in foo's <code>node_modules</code> folder.</p>
|
||||
<p>Even though the latest copy of blerg is 1.3.7, foo has a specific
|
||||
dependency on version 1.2.5. So, that gets installed at [A]. Since the
|
||||
parent installation of blerg satisfies bar's dependency on <code>blerg@1.x</code>,
|
||||
it does not install another copy under [B].</p>
|
||||
<p>Bar [B] also has dependencies on baz and asdf, so those are installed in
|
||||
bar's <code>node_modules</code> folder. Because it depends on <code>baz@2.x</code>, it cannot
|
||||
re-use the <code>baz@1.2.3</code> installed in the parent <code>node_modules</code> folder [D],
|
||||
and must install its own copy [C].</p>
|
||||
<p>Underneath bar, the <code>baz -> quux -> bar</code> dependency creates a cycle.
|
||||
However, because bar is already in quux's ancestry [B], it does not
|
||||
unpack another copy of bar into that folder.</p>
|
||||
<p>Underneath <code>foo -> baz</code> [D], quux's [E] folder tree is empty, because its
|
||||
dependency on bar is satisfied by the parent folder copy installed at [B].</p>
|
||||
<p>For a graphical breakdown of what is installed where, use <code>npm ls</code>.</p>
|
||||
<h3 id="publishing">Publishing</h3>
|
||||
<p>Upon publishing, npm will look in the <code>node_modules</code> folder. If any of
|
||||
the items there are not in the <code>bundledDependencies</code> array, then they will
|
||||
not be included in the package tarball.</p>
|
||||
<p>This allows a package maintainer to install all of their dependencies
|
||||
(and dev dependencies) locally, but only re-publish those items that
|
||||
cannot be found elsewhere. See <code><a href="../files/package.json.html">package.json(5)</a></code> for more information.</p>
|
||||
<h2 id="see-also">SEE ALSO</h2>
|
||||
<ul>
|
||||
<li><a href="../misc/npm-faq.html">npm-faq(7)</a></li>
|
||||
<li><a href="../files/package.json.html">package.json(5)</a></li>
|
||||
<li><a href="../cli/npm-install.html">npm-install(1)</a></li>
|
||||
<li><a href="../cli/npm-pack.html">npm-pack(1)</a></li>
|
||||
<li><a href="../cli/npm-cache.html">npm-cache(1)</a></li>
|
||||
<li><a href="../cli/npm-config.html">npm-config(1)</a></li>
|
||||
<li><a href="../files/npmrc.html">npmrc(5)</a></li>
|
||||
<li><a href="../misc/npm-config.html">npm-config(7)</a></li>
|
||||
<li><a href="../cli/npm-publish.html">npm-publish(1)</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
|
||||
<table border=0 cellspacing=0 cellpadding=0 id=npmlogo>
|
||||
<tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr>
|
||||
<tr><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td colspan=6 style="width:60px;height:10px;background:#fff"> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td></tr>
|
||||
<tr><td colspan=2 style="width:20px;height:30px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=4 colspan=2> </td><td style="width:10px;height:20px;background:rgb(237,127,127)" rowspan=2> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=3 colspan=2> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff"> </td></tr>
|
||||
<tr><td style="width:60px;height:10px;background:rgb(237,127,127)" colspan=6> </td><td colspan=10 style="width:10px;height:10px;background:rgb(237,127,127)"> </td></tr>
|
||||
<tr><td colspan=5 style="width:50px;height:10px;background:#fff"> </td><td style="width:40px;height:10px;background:rgb(237,127,127)" colspan=4> </td><td style="width:90px;height:10px;background:#fff" colspan=9> </td></tr>
|
||||
</table>
|
||||
<p id="footer">npm-folders — npm@2.15.12</p>
|
||||
|
||||
187
node_modules/npm/html/doc/files/npm-global.html
generated
vendored
Normal file
187
node_modules/npm/html/doc/files/npm-global.html
generated
vendored
Normal file
@@ -0,0 +1,187 @@
|
||||
<!doctype html>
|
||||
<html>
|
||||
<title>npm-folders</title>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" type="text/css" href="../../static/style.css">
|
||||
<link rel="canonical" href="https://www.npmjs.org/doc/files/npm-folders.html">
|
||||
<script async=true src="../../static/toc.js"></script>
|
||||
|
||||
<body>
|
||||
<div id="wrapper">
|
||||
|
||||
<h1><a href="../files/npm-folders.html">npm-folders</a></h1> <p>Folder Structures Used by npm</p>
|
||||
<h2 id="description">DESCRIPTION</h2>
|
||||
<p>npm puts various things on your computer. That's its job.</p>
|
||||
<p>This document will tell you what it puts where.</p>
|
||||
<h3 id="tl-dr">tl;dr</h3>
|
||||
<ul>
|
||||
<li>Local install (default): puts stuff in <code>./node_modules</code> of the current
|
||||
package root.</li>
|
||||
<li>Global install (with <code>-g</code>): puts stuff in /usr/local or wherever node
|
||||
is installed.</li>
|
||||
<li>Install it <strong>locally</strong> if you're going to <code>require()</code> it.</li>
|
||||
<li>Install it <strong>globally</strong> if you're going to run it on the command line.</li>
|
||||
<li>If you need both, then install it in both places, or use <code>npm link</code>.</li>
|
||||
</ul>
|
||||
<h3 id="prefix-configuration">prefix Configuration</h3>
|
||||
<p>The <code>prefix</code> config defaults to the location where node is installed.
|
||||
On most systems, this is <code>/usr/local</code>. On windows, this is the exact
|
||||
location of the node.exe binary. On Unix systems, it's one level up,
|
||||
since node is typically installed at <code>{prefix}/bin/node</code> rather than
|
||||
<code>{prefix}/node.exe</code>.</p>
|
||||
<p>When the <code>global</code> flag is set, npm installs things into this prefix.
|
||||
When it is not set, it uses the root of the current package, or the
|
||||
current working directory if not in a package already.</p>
|
||||
<h3 id="node-modules">Node Modules</h3>
|
||||
<p>Packages are dropped into the <code>node_modules</code> folder under the <code>prefix</code>.
|
||||
When installing locally, this means that you can
|
||||
<code>require("packagename")</code> to load its main module, or
|
||||
<code>require("packagename/lib/path/to/sub/module")</code> to load other modules.</p>
|
||||
<p>Global installs on Unix systems go to <code>{prefix}/lib/node_modules</code>.
|
||||
Global installs on Windows go to <code>{prefix}/node_modules</code> (that is, no
|
||||
<code>lib</code> folder.)</p>
|
||||
<p>Scoped packages are installed the same way, except they are grouped together
|
||||
in a sub-folder of the relevant <code>node_modules</code> folder with the name of that
|
||||
scope prefix by the @ symbol, e.g. <code>npm install @myorg/package</code> would place
|
||||
the package in <code>{prefix}/node_modules/@myorg/package</code>. See <code><a href="../misc/scope.html">scope(7)</a></code> for
|
||||
more details.</p>
|
||||
<p>If you wish to <code>require()</code> a package, then install it locally.</p>
|
||||
<h3 id="executables">Executables</h3>
|
||||
<p>When in global mode, executables are linked into <code>{prefix}/bin</code> on Unix,
|
||||
or directly into <code>{prefix}</code> on Windows.</p>
|
||||
<p>When in local mode, executables are linked into
|
||||
<code>./node_modules/.bin</code> so that they can be made available to scripts run
|
||||
through npm. (For example, so that a test runner will be in the path
|
||||
when you run <code>npm test</code>.)</p>
|
||||
<h3 id="man-pages">Man Pages</h3>
|
||||
<p>When in global mode, man pages are linked into <code>{prefix}/share/man</code>.</p>
|
||||
<p>When in local mode, man pages are not installed.</p>
|
||||
<p>Man pages are not installed on Windows systems.</p>
|
||||
<h3 id="cache">Cache</h3>
|
||||
<p>See <code><a href="../cli/npm-cache.html">npm-cache(1)</a></code>. Cache files are stored in <code>~/.npm</code> on Posix, or
|
||||
<code>~/npm-cache</code> on Windows.</p>
|
||||
<p>This is controlled by the <code>cache</code> configuration param.</p>
|
||||
<h3 id="temp-files">Temp Files</h3>
|
||||
<p>Temporary files are stored by default in the folder specified by the
|
||||
<code>tmp</code> config, which defaults to the TMPDIR, TMP, or TEMP environment
|
||||
variables, or <code>/tmp</code> on Unix and <code>c:\windows\temp</code> on Windows.</p>
|
||||
<p>Temp files are given a unique folder under this root for each run of the
|
||||
program, and are deleted upon successful exit.</p>
|
||||
<h2 id="more-information">More Information</h2>
|
||||
<p>When installing locally, npm first tries to find an appropriate
|
||||
<code>prefix</code> folder. This is so that <code>npm install foo@1.2.3</code> will install
|
||||
to the sensible root of your package, even if you happen to have <code>cd</code>ed
|
||||
into some other folder.</p>
|
||||
<p>Starting at the $PWD, npm will walk up the folder tree checking for a
|
||||
folder that contains either a <code>package.json</code> file, or a <code>node_modules</code>
|
||||
folder. If such a thing is found, then that is treated as the effective
|
||||
"current directory" for the purpose of running npm commands. (This
|
||||
behavior is inspired by and similar to git's .git-folder seeking
|
||||
logic when running git commands in a working dir.)</p>
|
||||
<p>If no package root is found, then the current folder is used.</p>
|
||||
<p>When you run <code>npm install foo@1.2.3</code>, then the package is loaded into
|
||||
the cache, and then unpacked into <code>./node_modules/foo</code>. Then, any of
|
||||
foo's dependencies are similarly unpacked into
|
||||
<code>./node_modules/foo/node_modules/...</code>.</p>
|
||||
<p>Any bin files are symlinked to <code>./node_modules/.bin/</code>, so that they may
|
||||
be found by npm scripts when necessary.</p>
|
||||
<h3 id="global-installation">Global Installation</h3>
|
||||
<p>If the <code>global</code> configuration is set to true, then npm will
|
||||
install packages "globally".</p>
|
||||
<p>For global installation, packages are installed roughly the same way,
|
||||
but using the folders described above.</p>
|
||||
<h3 id="cycles-conflicts-and-folder-parsimony">Cycles, Conflicts, and Folder Parsimony</h3>
|
||||
<p>Cycles are handled using the property of node's module system that it
|
||||
walks up the directories looking for <code>node_modules</code> folders. So, at every
|
||||
stage, if a package is already installed in an ancestor <code>node_modules</code>
|
||||
folder, then it is not installed at the current location.</p>
|
||||
<p>Consider the case above, where <code>foo -> bar -> baz</code>. Imagine if, in
|
||||
addition to that, baz depended on bar, so you'd have:
|
||||
<code>foo -> bar -> baz -> bar -> baz ...</code>. However, since the folder
|
||||
structure is: <code>foo/node_modules/bar/node_modules/baz</code>, there's no need to
|
||||
put another copy of bar into <code>.../baz/node_modules</code>, since when it calls
|
||||
require("bar"), it will get the copy that is installed in
|
||||
<code>foo/node_modules/bar</code>.</p>
|
||||
<p>This shortcut is only used if the exact same
|
||||
version would be installed in multiple nested <code>node_modules</code> folders. It
|
||||
is still possible to have <code>a/node_modules/b/node_modules/a</code> if the two
|
||||
"a" packages are different versions. However, without repeating the
|
||||
exact same package multiple times, an infinite regress will always be
|
||||
prevented.</p>
|
||||
<p>Another optimization can be made by installing dependencies at the
|
||||
highest level possible, below the localized "target" folder.</p>
|
||||
<h4 id="example">Example</h4>
|
||||
<p>Consider this dependency graph:</p>
|
||||
<pre><code>foo
|
||||
+-- blerg@1.2.5
|
||||
+-- bar@1.2.3
|
||||
| +-- blerg@1.x (latest=1.3.7)
|
||||
| +-- baz@2.x
|
||||
| | `-- quux@3.x
|
||||
| | `-- bar@1.2.3 (cycle)
|
||||
| `-- asdf@*
|
||||
`-- baz@1.2.3
|
||||
`-- quux@3.x
|
||||
`-- bar
|
||||
</code></pre><p>In this case, we might expect a folder structure like this:</p>
|
||||
<pre><code>foo
|
||||
+-- node_modules
|
||||
+-- blerg (1.2.5) <---[A]
|
||||
+-- bar (1.2.3) <---[B]
|
||||
| `-- node_modules
|
||||
| +-- baz (2.0.2) <---[C]
|
||||
| | `-- node_modules
|
||||
| | `-- quux (3.2.0)
|
||||
| `-- asdf (2.3.4)
|
||||
`-- baz (1.2.3) <---[D]
|
||||
`-- node_modules
|
||||
`-- quux (3.2.0) <---[E]
|
||||
</code></pre><p>Since foo depends directly on <code>bar@1.2.3</code> and <code>baz@1.2.3</code>, those are
|
||||
installed in foo's <code>node_modules</code> folder.</p>
|
||||
<p>Even though the latest copy of blerg is 1.3.7, foo has a specific
|
||||
dependency on version 1.2.5. So, that gets installed at [A]. Since the
|
||||
parent installation of blerg satisfies bar's dependency on <code>blerg@1.x</code>,
|
||||
it does not install another copy under [B].</p>
|
||||
<p>Bar [B] also has dependencies on baz and asdf, so those are installed in
|
||||
bar's <code>node_modules</code> folder. Because it depends on <code>baz@2.x</code>, it cannot
|
||||
re-use the <code>baz@1.2.3</code> installed in the parent <code>node_modules</code> folder [D],
|
||||
and must install its own copy [C].</p>
|
||||
<p>Underneath bar, the <code>baz -> quux -> bar</code> dependency creates a cycle.
|
||||
However, because bar is already in quux's ancestry [B], it does not
|
||||
unpack another copy of bar into that folder.</p>
|
||||
<p>Underneath <code>foo -> baz</code> [D], quux's [E] folder tree is empty, because its
|
||||
dependency on bar is satisfied by the parent folder copy installed at [B].</p>
|
||||
<p>For a graphical breakdown of what is installed where, use <code>npm ls</code>.</p>
|
||||
<h3 id="publishing">Publishing</h3>
|
||||
<p>Upon publishing, npm will look in the <code>node_modules</code> folder. If any of
|
||||
the items there are not in the <code>bundledDependencies</code> array, then they will
|
||||
not be included in the package tarball.</p>
|
||||
<p>This allows a package maintainer to install all of their dependencies
|
||||
(and dev dependencies) locally, but only re-publish those items that
|
||||
cannot be found elsewhere. See <code><a href="../files/package.json.html">package.json(5)</a></code> for more information.</p>
|
||||
<h2 id="see-also">SEE ALSO</h2>
|
||||
<ul>
|
||||
<li><a href="../misc/npm-faq.html">npm-faq(7)</a></li>
|
||||
<li><a href="../files/package.json.html">package.json(5)</a></li>
|
||||
<li><a href="../cli/npm-install.html">npm-install(1)</a></li>
|
||||
<li><a href="../cli/npm-pack.html">npm-pack(1)</a></li>
|
||||
<li><a href="../cli/npm-cache.html">npm-cache(1)</a></li>
|
||||
<li><a href="../cli/npm-config.html">npm-config(1)</a></li>
|
||||
<li><a href="../files/npmrc.html">npmrc(5)</a></li>
|
||||
<li><a href="../misc/npm-config.html">npm-config(7)</a></li>
|
||||
<li><a href="../cli/npm-publish.html">npm-publish(1)</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
|
||||
<table border=0 cellspacing=0 cellpadding=0 id=npmlogo>
|
||||
<tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr>
|
||||
<tr><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td colspan=6 style="width:60px;height:10px;background:#fff"> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td></tr>
|
||||
<tr><td colspan=2 style="width:20px;height:30px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=4 colspan=2> </td><td style="width:10px;height:20px;background:rgb(237,127,127)" rowspan=2> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=3 colspan=2> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff"> </td></tr>
|
||||
<tr><td style="width:60px;height:10px;background:rgb(237,127,127)" colspan=6> </td><td colspan=10 style="width:10px;height:10px;background:rgb(237,127,127)"> </td></tr>
|
||||
<tr><td colspan=5 style="width:50px;height:10px;background:#fff"> </td><td style="width:40px;height:10px;background:rgb(237,127,127)" colspan=4> </td><td style="width:90px;height:10px;background:#fff" colspan=9> </td></tr>
|
||||
</table>
|
||||
<p id="footer">npm-folders — npm@2.15.12</p>
|
||||
|
||||
589
node_modules/npm/html/doc/files/npm-json.html
generated
vendored
Normal file
589
node_modules/npm/html/doc/files/npm-json.html
generated
vendored
Normal file
@@ -0,0 +1,589 @@
|
||||
<!doctype html>
|
||||
<html>
|
||||
<title>package.json</title>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" type="text/css" href="../../static/style.css">
|
||||
<link rel="canonical" href="https://www.npmjs.org/doc/files/package.json.html">
|
||||
<script async=true src="../../static/toc.js"></script>
|
||||
|
||||
<body>
|
||||
<div id="wrapper">
|
||||
|
||||
<h1><a href="../files/package.json.html">package.json</a></h1> <p>Specifics of npm's package.json handling</p>
|
||||
<h2 id="description">DESCRIPTION</h2>
|
||||
<p>This document is all you need to know about what's required in your package.json
|
||||
file. It must be actual JSON, not just a JavaScript object literal.</p>
|
||||
<p>A lot of the behavior described in this document is affected by the config
|
||||
settings described in <code><a href="../misc/npm-config.html">npm-config(7)</a></code>.</p>
|
||||
<h2 id="name">name</h2>
|
||||
<p>The <em>most</em> important things in your package.json are the name and version fields.
|
||||
Those are actually required, and your package won't install without
|
||||
them. The name and version together form an identifier that is assumed
|
||||
to be completely unique. Changes to the package should come along with
|
||||
changes to the version.</p>
|
||||
<p>The name is what your thing is called.</p>
|
||||
<p>Some rules:</p>
|
||||
<ul>
|
||||
<li>The name must be less than or equal to 214 characters. This includes the scope for
|
||||
scoped packages.</li>
|
||||
<li>The name can't start with a dot or an underscore.</li>
|
||||
<li>New packages must not have uppercase letters in the name.</li>
|
||||
<li>The name ends up being part of a URL, an argument on the command line, and a
|
||||
folder name. Therefore, the name can't contain any non-URL-safe characters.</li>
|
||||
</ul>
|
||||
<p>Some tips:</p>
|
||||
<ul>
|
||||
<li>Don't use the same name as a core Node module.</li>
|
||||
<li>Don't put "js" or "node" in the name. It's assumed that it's js, since you're
|
||||
writing a package.json file, and you can specify the engine using the "engines"
|
||||
field. (See below.)</li>
|
||||
<li>The name will probably be passed as an argument to require(), so it should
|
||||
be something short, but also reasonably descriptive.</li>
|
||||
<li>You may want to check the npm registry to see if there's something by that name
|
||||
already, before you get too attached to it. <a href="https://www.npmjs.com/">https://www.npmjs.com/</a></li>
|
||||
</ul>
|
||||
<p>A name can be optionally prefixed by a scope, e.g. <code>@myorg/mypackage</code>. See
|
||||
<code><a href="../misc/npm-scope.html">npm-scope(7)</a></code> for more detail.</p>
|
||||
<h2 id="version">version</h2>
|
||||
<p>The <em>most</em> important things in your package.json are the name and version fields.
|
||||
Those are actually required, and your package won't install without
|
||||
them. The name and version together form an identifier that is assumed
|
||||
to be completely unique. Changes to the package should come along with
|
||||
changes to the version.</p>
|
||||
<p>Version must be parseable by
|
||||
<a href="https://github.com/isaacs/node-semver">node-semver</a>, which is bundled
|
||||
with npm as a dependency. (<code>npm install semver</code> to use it yourself.)</p>
|
||||
<p>More on version numbers and ranges at <a href="../misc/semver.html">semver(7)</a>.</p>
|
||||
<h2 id="description">description</h2>
|
||||
<p>Put a description in it. It's a string. This helps people discover your
|
||||
package, as it's listed in <code>npm search</code>.</p>
|
||||
<h2 id="keywords">keywords</h2>
|
||||
<p>Put keywords in it. It's an array of strings. This helps people
|
||||
discover your package as it's listed in <code>npm search</code>.</p>
|
||||
<h2 id="homepage">homepage</h2>
|
||||
<p>The url to the project homepage.</p>
|
||||
<p><strong>NOTE</strong>: This is <em>not</em> the same as "url". If you put a "url" field,
|
||||
then the registry will think it's a redirection to your package that has
|
||||
been published somewhere else, and spit at you.</p>
|
||||
<p>Literally. Spit. I'm so not kidding.</p>
|
||||
<h2 id="bugs">bugs</h2>
|
||||
<p>The url to your project's issue tracker and / or the email address to which
|
||||
issues should be reported. These are helpful for people who encounter issues
|
||||
with your package.</p>
|
||||
<p>It should look like this:</p>
|
||||
<pre><code>{ "url" : "https://github.com/owner/project/issues"
|
||||
, "email" : "project@hostname.com"
|
||||
}
|
||||
</code></pre><p>You can specify either one or both values. If you want to provide only a url,
|
||||
you can specify the value for "bugs" as a simple string instead of an object.</p>
|
||||
<p>If a url is provided, it will be used by the <code>npm bugs</code> command.</p>
|
||||
<h2 id="license">license</h2>
|
||||
<p>You should specify a license for your package so that people know how they are
|
||||
permitted to use it, and any restrictions you're placing on it.</p>
|
||||
<p>If you're using a common license such as BSD-2-Clause or MIT, add a
|
||||
current SPDX license identifier for the license you're using, like this:</p>
|
||||
<pre><code>{ "license" : "BSD-3-Clause" }
|
||||
</code></pre><p>You can check <a href="https://spdx.org/licenses/">the full list of SPDX license IDs</a>.
|
||||
Ideally you should pick one that is
|
||||
<a href="https://opensource.org/licenses/alphabetical">OSI</a> approved.</p>
|
||||
<p>If your package is licensed under multiple common licenses, use an <a href="https://npmjs.com/package/spdx">SPDX license
|
||||
expression syntax version 2.0 string</a>, like this:</p>
|
||||
<pre><code>{ "license" : "(ISC OR GPL-3.0)" }
|
||||
</code></pre><p>If you are using a license that hasn't been assigned an SPDX identifier, or if
|
||||
you are using a custom license, use a string value like this one:</p>
|
||||
<pre><code>{ "license" : "SEE LICENSE IN <filename>" }
|
||||
</code></pre><p>Then include a file named <code><filename></code> at the top level of the package.</p>
|
||||
<p>Some old packages used license objects or a "licenses" property containing an
|
||||
array of license objects:</p>
|
||||
<pre><code>// Not valid metadata
|
||||
{ "license" :
|
||||
{ "type" : "ISC"
|
||||
, "url" : "http://opensource.org/licenses/ISC"
|
||||
}
|
||||
}
|
||||
|
||||
// Not valid metadata
|
||||
{ "licenses" :
|
||||
[
|
||||
{ "type": "MIT"
|
||||
, "url": "http://www.opensource.org/licenses/mit-license.php"
|
||||
}
|
||||
, { "type": "Apache-2.0"
|
||||
, "url": "http://opensource.org/licenses/apache2.0.php"
|
||||
}
|
||||
]
|
||||
}
|
||||
</code></pre><p>Those styles are now deprecated. Instead, use SPDX expressions, like this:</p>
|
||||
<pre><code>{ "license": "ISC" }
|
||||
|
||||
{ "license": "(MIT OR Apache-2.0)" }
|
||||
</code></pre><p>Finally, if you do not wish to grant others the right to use a private or
|
||||
unpublished package under any terms:</p>
|
||||
<pre><code>{ "license": "UNLICENSED"}
|
||||
</code></pre><p>Consider also setting <code>"private": true</code> to prevent accidental publication.</p>
|
||||
<h2 id="people-fields-author-contributors">people fields: author, contributors</h2>
|
||||
<p>The "author" is one person. "contributors" is an array of people. A "person"
|
||||
is an object with a "name" field and optionally "url" and "email", like this:</p>
|
||||
<pre><code>{ "name" : "Barney Rubble"
|
||||
, "email" : "b@rubble.com"
|
||||
, "url" : "http://barnyrubble.tumblr.com/"
|
||||
}
|
||||
</code></pre><p>Or you can shorten that all into a single string, and npm will parse it for you:</p>
|
||||
<pre><code>"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"
|
||||
</code></pre><p>Both email and url are optional either way.</p>
|
||||
<p>npm also sets a top-level "maintainers" field with your npm user info.</p>
|
||||
<h2 id="files">files</h2>
|
||||
<p>The "files" field is an array of files to include in your project. If
|
||||
you name a folder in the array, then it will also include the files
|
||||
inside that folder. (Unless they would be ignored by another rule.)</p>
|
||||
<p>You can also provide a ".npmignore" file in the root of your package or
|
||||
in subdirectories, which will keep files from being included, even
|
||||
if they would be picked up by the files array. The <code>.npmignore</code> file
|
||||
works just like a <code>.gitignore</code>.</p>
|
||||
<p>Certain files are always included, regardless of settings:</p>
|
||||
<ul>
|
||||
<li><code>package.json</code></li>
|
||||
<li><code><a href="../../doc/README.html">README</a></code></li>
|
||||
<li><code>CHANGES</code> / <code>CHANGELOG</code> / <code>HISTORY</code> (any casing and file extension)</li>
|
||||
<li><code>LICENSE</code> / <code>LICENCE</code></li>
|
||||
<li>The file in the "main" field</li>
|
||||
</ul>
|
||||
<p>Conversely, some files are always ignored:</p>
|
||||
<ul>
|
||||
<li><code>.git</code></li>
|
||||
<li><code>CVS</code></li>
|
||||
<li><code>.svn</code></li>
|
||||
<li><code>.hg</code></li>
|
||||
<li><code>.lock-wscript</code></li>
|
||||
<li><code>.wafpickle-N</code></li>
|
||||
<li><code>.*.swp</code></li>
|
||||
<li><code>.DS_Store</code></li>
|
||||
<li><code>._*</code></li>
|
||||
<li><code>npm-debug.log</code></li>
|
||||
<li><code>.npmrc</code></li>
|
||||
<li><code>node_modules</code></li>
|
||||
</ul>
|
||||
<h2 id="main">main</h2>
|
||||
<p>The main field is a module ID that is the primary entry point to your program.
|
||||
That is, if your package is named <code>foo</code>, and a user installs it, and then does
|
||||
<code>require("foo")</code>, then your main module's exports object will be returned.</p>
|
||||
<p>This should be a module ID relative to the root of your package folder.</p>
|
||||
<p>For most modules, it makes the most sense to have a main script and often not
|
||||
much else.</p>
|
||||
<h2 id="bin">bin</h2>
|
||||
<p>A lot of packages have one or more executable files that they'd like to
|
||||
install into the PATH. npm makes this pretty easy (in fact, it uses this
|
||||
feature to install the "npm" executable.)</p>
|
||||
<p>To use this, supply a <code>bin</code> field in your package.json which is a map of
|
||||
command name to local file name. On install, npm will symlink that file into
|
||||
<code>prefix/bin</code> for global installs, or <code>./node_modules/.bin/</code> for local
|
||||
installs.</p>
|
||||
<p>For example, myapp could have this:</p>
|
||||
<pre><code>{ "bin" : { "myapp" : "./cli.js" } }
|
||||
</code></pre><p>So, when you install myapp, it'll create a symlink from the <code>cli.js</code> script to
|
||||
<code>/usr/local/bin/myapp</code>.</p>
|
||||
<p>If you have a single executable, and its name should be the name
|
||||
of the package, then you can just supply it as a string. For example:</p>
|
||||
<pre><code>{ "name": "my-program"
|
||||
, "version": "1.2.5"
|
||||
, "bin": "./path/to/program" }
|
||||
</code></pre><p>would be the same as this:</p>
|
||||
<pre><code>{ "name": "my-program"
|
||||
, "version": "1.2.5"
|
||||
, "bin" : { "my-program" : "./path/to/program" } }
|
||||
</code></pre><p>Please make sure that your file(s) referenced in <code>bin</code> starts with
|
||||
<code>#!/usr/bin/env node</code>, otherwise the scripts are started without the node
|
||||
executable!</p>
|
||||
<h2 id="man">man</h2>
|
||||
<p>Specify either a single file or an array of filenames to put in place for the
|
||||
<code>man</code> program to find.</p>
|
||||
<p>If only a single file is provided, then it's installed such that it is the
|
||||
result from <code>man <pkgname></code>, regardless of its actual filename. For example:</p>
|
||||
<pre><code>{ "name" : "foo"
|
||||
, "version" : "1.2.3"
|
||||
, "description" : "A packaged foo fooer for fooing foos"
|
||||
, "main" : "foo.js"
|
||||
, "man" : "./man/doc.1"
|
||||
}
|
||||
</code></pre><p>would link the <code>./man/doc.1</code> file in such that it is the target for <code>man foo</code></p>
|
||||
<p>If the filename doesn't start with the package name, then it's prefixed.
|
||||
So, this:</p>
|
||||
<pre><code>{ "name" : "foo"
|
||||
, "version" : "1.2.3"
|
||||
, "description" : "A packaged foo fooer for fooing foos"
|
||||
, "main" : "foo.js"
|
||||
, "man" : [ "./man/foo.1", "./man/bar.1" ]
|
||||
}
|
||||
</code></pre><p>will create files to do <code>man foo</code> and <code>man foo-bar</code>.</p>
|
||||
<p>Man files must end with a number, and optionally a <code>.gz</code> suffix if they are
|
||||
compressed. The number dictates which man section the file is installed into.</p>
|
||||
<pre><code>{ "name" : "foo"
|
||||
, "version" : "1.2.3"
|
||||
, "description" : "A packaged foo fooer for fooing foos"
|
||||
, "main" : "foo.js"
|
||||
, "man" : [ "./man/foo.1", "./man/foo.2" ]
|
||||
}
|
||||
</code></pre><p>will create entries for <code>man foo</code> and <code>man 2 foo</code></p>
|
||||
<h2 id="directories">directories</h2>
|
||||
<p>The CommonJS <a href="http://wiki.commonjs.org/wiki/Packages/1.0">Packages</a> spec details a
|
||||
few ways that you can indicate the structure of your package using a <code>directories</code>
|
||||
object. If you look at <a href="https://registry.npmjs.org/npm/latest">npm's package.json</a>,
|
||||
you'll see that it has directories for doc, lib, and man.</p>
|
||||
<p>In the future, this information may be used in other creative ways.</p>
|
||||
<h3 id="directories-lib">directories.lib</h3>
|
||||
<p>Tell people where the bulk of your library is. Nothing special is done
|
||||
with the lib folder in any way, but it's useful meta info.</p>
|
||||
<h3 id="directories-bin">directories.bin</h3>
|
||||
<p>If you specify a <code>bin</code> directory in <code>directories.bin</code>, all the files in
|
||||
that folder will be added.</p>
|
||||
<p>Because of the way the <code>bin</code> directive works, specifying both a
|
||||
<code>bin</code> path and setting <code>directories.bin</code> is an error. If you want to
|
||||
specify individual files, use <code>bin</code>, and for all the files in an
|
||||
existing <code>bin</code> directory, use <code>directories.bin</code>.</p>
|
||||
<h3 id="directories-man">directories.man</h3>
|
||||
<p>A folder that is full of man pages. Sugar to generate a "man" array by
|
||||
walking the folder.</p>
|
||||
<h3 id="directories-doc">directories.doc</h3>
|
||||
<p>Put markdown files in here. Eventually, these will be displayed nicely,
|
||||
maybe, someday.</p>
|
||||
<h3 id="directories-example">directories.example</h3>
|
||||
<p>Put example scripts in here. Someday, it might be exposed in some clever way.</p>
|
||||
<h3 id="directories-test">directories.test</h3>
|
||||
<p>Put your tests in here. It is currently not exposed, but it might be in the
|
||||
future.</p>
|
||||
<h2 id="repository">repository</h2>
|
||||
<p>Specify the place where your code lives. This is helpful for people who
|
||||
want to contribute. If the git repo is on GitHub, then the <code>npm docs</code>
|
||||
command will be able to find you.</p>
|
||||
<p>Do it like this:</p>
|
||||
<pre><code>"repository" :
|
||||
{ "type" : "git"
|
||||
, "url" : "https://github.com/npm/npm.git"
|
||||
}
|
||||
|
||||
"repository" :
|
||||
{ "type" : "svn"
|
||||
, "url" : "https://v8.googlecode.com/svn/trunk/"
|
||||
}
|
||||
</code></pre><p>The URL should be a publicly available (perhaps read-only) url that can be handed
|
||||
directly to a VCS program without any modification. It should not be a url to an
|
||||
html project page that you put in your browser. It's for computers.</p>
|
||||
<p>For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same
|
||||
shortcut syntax you use for <code>npm install</code>:</p>
|
||||
<pre><code>"repository": "npm/npm"
|
||||
|
||||
"repository": "gist:11081aaa281"
|
||||
|
||||
"repository": "bitbucket:example/repo"
|
||||
|
||||
"repository": "gitlab:another/repo"
|
||||
</code></pre><h2 id="scripts">scripts</h2>
|
||||
<p>The "scripts" property is a dictionary containing script commands that are run
|
||||
at various times in the lifecycle of your package. The key is the lifecycle
|
||||
event, and the value is the command to run at that point.</p>
|
||||
<p>See <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code> to find out more about writing package scripts.</p>
|
||||
<h2 id="config">config</h2>
|
||||
<p>A "config" object can be used to set configuration parameters used in package
|
||||
scripts that persist across upgrades. For instance, if a package had the
|
||||
following:</p>
|
||||
<pre><code>{ "name" : "foo"
|
||||
, "config" : { "port" : "8080" } }
|
||||
</code></pre><p>and then had a "start" command that then referenced the
|
||||
<code>npm_package_config_port</code> environment variable, then the user could
|
||||
override that by doing <code>npm config set foo:port 8001</code>.</p>
|
||||
<p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> and <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code> for more on package
|
||||
configs.</p>
|
||||
<h2 id="dependencies">dependencies</h2>
|
||||
<p>Dependencies are specified in a simple object that maps a package name to a
|
||||
version range. The version range is a string which has one or more
|
||||
space-separated descriptors. Dependencies can also be identified with a
|
||||
tarball or git URL.</p>
|
||||
<p><strong>Please do not put test harnesses or transpilers in your
|
||||
<code>dependencies</code> object.</strong> See <code>devDependencies</code>, below.</p>
|
||||
<p>See <a href="../misc/semver.html">semver(7)</a> for more details about specifying version ranges.</p>
|
||||
<ul>
|
||||
<li><code>version</code> Must match <code>version</code> exactly</li>
|
||||
<li><code>>version</code> Must be greater than <code>version</code></li>
|
||||
<li><code>>=version</code> etc</li>
|
||||
<li><code><version</code></li>
|
||||
<li><code><=version</code></li>
|
||||
<li><code>~version</code> "Approximately equivalent to version" See <a href="../misc/semver.html">semver(7)</a></li>
|
||||
<li><code>^version</code> "Compatible with version" See <a href="../misc/semver.html">semver(7)</a></li>
|
||||
<li><code>1.2.x</code> 1.2.0, 1.2.1, etc., but not 1.3.0</li>
|
||||
<li><code>http://...</code> See 'URLs as Dependencies' below</li>
|
||||
<li><code>*</code> Matches any version</li>
|
||||
<li><code>""</code> (just an empty string) Same as <code>*</code></li>
|
||||
<li><code>version1 - version2</code> Same as <code>>=version1 <=version2</code>.</li>
|
||||
<li><code>range1 || range2</code> Passes if either range1 or range2 are satisfied.</li>
|
||||
<li><code>git...</code> See 'Git URLs as Dependencies' below</li>
|
||||
<li><code>user/repo</code> See 'GitHub URLs' below</li>
|
||||
<li><code>tag</code> A specific version tagged and published as <code>tag</code> See <code><a href="../cli/npm-tag.html">npm-tag(1)</a></code></li>
|
||||
<li><code>path/path/path</code> See <a href="#local-paths">Local Paths</a> below</li>
|
||||
</ul>
|
||||
<p>For example, these are all valid:</p>
|
||||
<pre><code>{ "dependencies" :
|
||||
{ "foo" : "1.0.0 - 2.9999.9999"
|
||||
, "bar" : ">=1.0.2 <2.1.2"
|
||||
, "baz" : ">1.0.2 <=2.3.4"
|
||||
, "boo" : "2.0.1"
|
||||
, "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
|
||||
, "asd" : "http://asdf.com/asdf.tar.gz"
|
||||
, "til" : "~1.2"
|
||||
, "elf" : "~1.2.3"
|
||||
, "two" : "2.x"
|
||||
, "thr" : "3.3.x"
|
||||
, "lat" : "latest"
|
||||
, "dyl" : "file:../dyl"
|
||||
}
|
||||
}
|
||||
</code></pre><h3 id="urls-as-dependencies">URLs as Dependencies</h3>
|
||||
<p>You may specify a tarball URL in place of a version range.</p>
|
||||
<p>This tarball will be downloaded and installed locally to your package at
|
||||
install time.</p>
|
||||
<h3 id="git-urls-as-dependencies">Git URLs as Dependencies</h3>
|
||||
<p>Git urls can be of the form:</p>
|
||||
<pre><code>git://github.com/user/project.git#commit-ish
|
||||
git+ssh://user@hostname:project.git#commit-ish
|
||||
git+ssh://user@hostname/project.git#commit-ish
|
||||
git+http://user@hostname/project/blah.git#commit-ish
|
||||
git+https://user@hostname/project/blah.git#commit-ish
|
||||
</code></pre><p>The <code>commit-ish</code> can be any tag, sha, or branch which can be supplied as
|
||||
an argument to <code>git checkout</code>. The default is <code>master</code>.</p>
|
||||
<h2 id="github-urls">GitHub URLs</h2>
|
||||
<p>As of version 1.1.65, you can refer to GitHub urls as just "foo":
|
||||
"user/foo-project". Just as with git URLs, a <code>commit-ish</code> suffix can be
|
||||
included. For example:</p>
|
||||
<pre><code>{
|
||||
"name": "foo",
|
||||
"version": "0.0.0",
|
||||
"dependencies": {
|
||||
"express": "visionmedia/express",
|
||||
"mocha": "visionmedia/mocha#4727d357ea"
|
||||
}
|
||||
}
|
||||
</code></pre><h2 id="local-paths">Local Paths</h2>
|
||||
<p>As of version 2.0.0 you can provide a path to a local directory that contains a
|
||||
package. Local paths can be saved using <code>npm install --save</code>, using any of
|
||||
these forms:</p>
|
||||
<pre><code>../foo/bar
|
||||
~/foo/bar
|
||||
./foo/bar
|
||||
/foo/bar
|
||||
</code></pre><p>in which case they will be normalized to a relative path and added to your
|
||||
<code>package.json</code>. For example:</p>
|
||||
<pre><code>{
|
||||
"name": "baz",
|
||||
"dependencies": {
|
||||
"bar": "file:../foo/bar"
|
||||
}
|
||||
}
|
||||
</code></pre><p>This feature is helpful for local offline development and creating
|
||||
tests that require npm installing where you don't want to hit an
|
||||
external server, but should not be used when publishing packages
|
||||
to the public registry.</p>
|
||||
<h2 id="devdependencies">devDependencies</h2>
|
||||
<p>If someone is planning on downloading and using your module in their
|
||||
program, then they probably don't want or need to download and build
|
||||
the external test or documentation framework that you use.</p>
|
||||
<p>In this case, it's best to map these additional items in a <code>devDependencies</code>
|
||||
object.</p>
|
||||
<p>These things will be installed when doing <code>npm link</code> or <code>npm install</code>
|
||||
from the root of a package, and can be managed like any other npm
|
||||
configuration param. See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> for more on the topic.</p>
|
||||
<p>For build steps that are not platform-specific, such as compiling
|
||||
CoffeeScript or other languages to JavaScript, use the <code>prepublish</code>
|
||||
script to do this, and make the required package a devDependency.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code>{ "name": "ethopia-waza",
|
||||
"description": "a delightfully fruity coffee varietal",
|
||||
"version": "1.2.3",
|
||||
"devDependencies": {
|
||||
"coffee-script": "~1.6.3"
|
||||
},
|
||||
"scripts": {
|
||||
"prepublish": "coffee -o lib/ -c src/waza.coffee"
|
||||
},
|
||||
"main": "lib/waza.js"
|
||||
}
|
||||
</code></pre><p>The <code>prepublish</code> script will be run before publishing, so that users
|
||||
can consume the functionality without requiring them to compile it
|
||||
themselves. In dev mode (ie, locally running <code>npm install</code>), it'll
|
||||
run this script as well, so that you can test it easily.</p>
|
||||
<h2 id="peerdependencies">peerDependencies</h2>
|
||||
<p>In some cases, you want to express the compatibility of your package with a
|
||||
host tool or library, while not necessarily doing a <code>require</code> of this host.
|
||||
This is usually referred to as a <em>plugin</em>. Notably, your module may be exposing
|
||||
a specific interface, expected and specified by the host documentation.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code>{
|
||||
"name": "tea-latte",
|
||||
"version": "1.3.5",
|
||||
"peerDependencies": {
|
||||
"tea": "2.x"
|
||||
}
|
||||
}
|
||||
</code></pre><p>This ensures your package <code>tea-latte</code> can be installed <em>along</em> with the second
|
||||
major version of the host package <code>tea</code> only. <code>npm install tea-latte</code> could
|
||||
possibly yield the following dependency graph:</p>
|
||||
<pre><code>├── tea-latte@1.3.5
|
||||
└── tea@2.2.0
|
||||
</code></pre><p><strong>NOTE: npm versions 1 and 2 will automatically install <code>peerDependencies</code> if
|
||||
they are not explicitly depended upon higher in the dependency tree. In the
|
||||
next major version of npm (npm@3), this will no longer be the case. You will
|
||||
receive a warning that the peerDependency is not installed instead.</strong> The
|
||||
behavior in npms 1 & 2 was frequently confusing and could easily put you into
|
||||
dependency hell, a situation that npm is designed to avoid as much as possible.</p>
|
||||
<p>Trying to install another plugin with a conflicting requirement will cause an
|
||||
error. For this reason, make sure your plugin requirement is as broad as
|
||||
possible, and not to lock it down to specific patch versions.</p>
|
||||
<p>Assuming the host complies with <a href="http://semver.org/">semver</a>, only changes in
|
||||
the host package's major version will break your plugin. Thus, if you've worked
|
||||
with every 1.x version of the host package, use <code>"^1.0"</code> or <code>"1.x"</code> to express
|
||||
this. If you depend on features introduced in 1.5.2, use <code>">= 1.5.2 < 2"</code>.</p>
|
||||
<h2 id="bundleddependencies">bundledDependencies</h2>
|
||||
<p>This defines an array of package names that will be bundled when publishing the package.</p>
|
||||
<p>In cases where you need to preserve npm packages locally or have them available through a single file download, you can bundle the packages in a tarball file by specifying the package names in the <code>bundledDependencies</code> array and executing <code>npm pack</code>.</p>
|
||||
<p>For example:
|
||||
If we define a package.json like this:</p>
|
||||
<pre><code>{
|
||||
"name": "awesome-web-framework",
|
||||
"version": "1.0.0",
|
||||
"bundledDependencies": [
|
||||
'renderized', 'super-streams'
|
||||
]
|
||||
}
|
||||
</code></pre><p>we can obtain <code>awesome-web-framework-1.0.0.tgz</code> file by running <code>npm pack</code>. This file contains the dependencies <code>renderized</code> and <code>super-streams</code> which can be installed in a new project by executing <code>npm install awesome-web-framework-1.0.0.tgz</code>.</p>
|
||||
<p>If this is spelled <code>"bundleDependencies"</code>, then that is also honored.</p>
|
||||
<h2 id="optionaldependencies">optionalDependencies</h2>
|
||||
<p>If a dependency can be used, but you would like npm to proceed if it cannot be
|
||||
found or fails to install, then you may put it in the <code>optionalDependencies</code>
|
||||
object. This is a map of package name to version or url, just like the
|
||||
<code>dependencies</code> object. The difference is that build failures do not cause
|
||||
installation to fail.</p>
|
||||
<p>It is still your program's responsibility to handle the lack of the
|
||||
dependency. For example, something like this:</p>
|
||||
<pre><code>try {
|
||||
var foo = require('foo')
|
||||
var fooVersion = require('foo/package.json').version
|
||||
} catch (er) {
|
||||
foo = null
|
||||
}
|
||||
if ( notGoodFooVersion(fooVersion) ) {
|
||||
foo = null
|
||||
}
|
||||
|
||||
// .. then later in your program ..
|
||||
|
||||
if (foo) {
|
||||
foo.doFooThings()
|
||||
}
|
||||
</code></pre><p>Entries in <code>optionalDependencies</code> will override entries of the same name in
|
||||
<code>dependencies</code>, so it's usually best to only put in one place.</p>
|
||||
<h2 id="engines">engines</h2>
|
||||
<p>You can specify the version of node that your stuff works on:</p>
|
||||
<pre><code>{ "engines" : { "node" : ">=0.10.3 <0.12" } }
|
||||
</code></pre><p>And, like with dependencies, if you don't specify the version (or if you
|
||||
specify "*" as the version), then any version of node will do.</p>
|
||||
<p>If you specify an "engines" field, then npm will require that "node" be
|
||||
somewhere on that list. If "engines" is omitted, then npm will just assume
|
||||
that it works on node.</p>
|
||||
<p>You can also use the "engines" field to specify which versions of npm
|
||||
are capable of properly installing your program. For example:</p>
|
||||
<pre><code>{ "engines" : { "npm" : "~1.0.20" } }
|
||||
</code></pre><p>Unless the user has set the <code>engine-strict</code> config flag, this
|
||||
field is advisory only will produce warnings when your package is installed as a dependency.</p>
|
||||
<h2 id="enginestrict">engineStrict</h2>
|
||||
<p><strong>NOTE: This feature is deprecated and will be removed in npm 3.0.0.</strong></p>
|
||||
<p>If you are sure that your module will <em>definitely not</em> run properly on
|
||||
versions of Node/npm other than those specified in the <code>engines</code> object,
|
||||
then you can set <code>"engineStrict": true</code> in your package.json file.
|
||||
This will override the user's <code>engine-strict</code> config setting.</p>
|
||||
<p>Please do not do this unless you are really very very sure. If your
|
||||
engines object is something overly restrictive, you can quite easily and
|
||||
inadvertently lock yourself into obscurity and prevent your users from
|
||||
updating to new versions of Node. Consider this choice carefully.</p>
|
||||
<h2 id="os">os</h2>
|
||||
<p>You can specify which operating systems your
|
||||
module will run on:</p>
|
||||
<pre><code>"os" : [ "darwin", "linux" ]
|
||||
</code></pre><p>You can also blacklist instead of whitelist operating systems,
|
||||
just prepend the blacklisted os with a '!':</p>
|
||||
<pre><code>"os" : [ "!win32" ]
|
||||
</code></pre><p>The host operating system is determined by <code>process.platform</code></p>
|
||||
<p>It is allowed to both blacklist, and whitelist, although there isn't any
|
||||
good reason to do this.</p>
|
||||
<h2 id="cpu">cpu</h2>
|
||||
<p>If your code only runs on certain cpu architectures,
|
||||
you can specify which ones.</p>
|
||||
<pre><code>"cpu" : [ "x64", "ia32" ]
|
||||
</code></pre><p>Like the <code>os</code> option, you can also blacklist architectures:</p>
|
||||
<pre><code>"cpu" : [ "!arm", "!mips" ]
|
||||
</code></pre><p>The host architecture is determined by <code>process.arch</code></p>
|
||||
<h2 id="preferglobal">preferGlobal</h2>
|
||||
<p>If your package is primarily a command-line application that should be
|
||||
installed globally, then set this value to <code>true</code> to provide a warning
|
||||
if it is installed locally.</p>
|
||||
<p>It doesn't actually prevent users from installing it locally, but it
|
||||
does help prevent some confusion if it doesn't work as expected.</p>
|
||||
<h2 id="private">private</h2>
|
||||
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse
|
||||
to publish it.</p>
|
||||
<p>This is a way to prevent accidental publication of private repositories. If
|
||||
you would like to ensure that a given package is only ever published to a
|
||||
specific registry (for example, an internal registry), then use the
|
||||
<code>publishConfig</code> dictionary described below to override the <code>registry</code> config
|
||||
param at publish-time.</p>
|
||||
<h2 id="publishconfig">publishConfig</h2>
|
||||
<p>This is a set of config values that will be used at publish-time. It's
|
||||
especially handy if you want to set the tag, registry or access, so that
|
||||
you can ensure that a given package is not tagged with "latest", published
|
||||
to the global public registry or that a scoped module is private by default.</p>
|
||||
<p>Any config values can be overridden, but of course only "tag", "registry" and
|
||||
"access" probably matter for the purposes of publishing.</p>
|
||||
<p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> to see the list of config options that can be
|
||||
overridden.</p>
|
||||
<h2 id="default-values">DEFAULT VALUES</h2>
|
||||
<p>npm will default some values based on package contents.</p>
|
||||
<ul>
|
||||
<li><p><code>"scripts": {"start": "node server.js"}</code></p>
|
||||
<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>.</p>
|
||||
</li>
|
||||
<li><p><code>"scripts":{"install": "node-gyp rebuild"}</code></p>
|
||||
<p>If there is a <code>binding.gyp</code> file in the root of your package and you have not defined an <code>install</code> or <code>preinstall</code> script, npm will
|
||||
default the <code>install</code> command to compile using node-gyp.</p>
|
||||
</li>
|
||||
<li><p><code>"contributors": [...]</code></p>
|
||||
<p>If there is an <code>AUTHORS</code> file in the root of your package, npm will
|
||||
treat each line as a <code>Name <email> (url)</code> format, where email and url
|
||||
are optional. Lines which start with a <code>#</code> or are blank, will be
|
||||
ignored.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<h2 id="see-also">SEE ALSO</h2>
|
||||
<ul>
|
||||
<li><a href="../misc/semver.html">semver(7)</a></li>
|
||||
<li><a href="../cli/npm-init.html">npm-init(1)</a></li>
|
||||
<li><a href="../cli/npm-version.html">npm-version(1)</a></li>
|
||||
<li><a href="../cli/npm-config.html">npm-config(1)</a></li>
|
||||
<li><a href="../misc/npm-config.html">npm-config(7)</a></li>
|
||||
<li><a href="../cli/npm-help.html">npm-help(1)</a></li>
|
||||
<li><a href="../misc/npm-faq.html">npm-faq(7)</a></li>
|
||||
<li><a href="../cli/npm-install.html">npm-install(1)</a></li>
|
||||
<li><a href="../cli/npm-publish.html">npm-publish(1)</a></li>
|
||||
<li><a href="../cli/npm-uninstall.html">npm-uninstall(1)</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
|
||||
<table border=0 cellspacing=0 cellpadding=0 id=npmlogo>
|
||||
<tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr>
|
||||
<tr><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td colspan=6 style="width:60px;height:10px;background:#fff"> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td></tr>
|
||||
<tr><td colspan=2 style="width:20px;height:30px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=4 colspan=2> </td><td style="width:10px;height:20px;background:rgb(237,127,127)" rowspan=2> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=3 colspan=2> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff"> </td></tr>
|
||||
<tr><td style="width:60px;height:10px;background:rgb(237,127,127)" colspan=6> </td><td colspan=10 style="width:10px;height:10px;background:rgb(237,127,127)"> </td></tr>
|
||||
<tr><td colspan=5 style="width:50px;height:10px;background:#fff"> </td><td style="width:40px;height:10px;background:rgb(237,127,127)" colspan=4> </td><td style="width:90px;height:10px;background:#fff" colspan=9> </td></tr>
|
||||
</table>
|
||||
<p id="footer">package.json — npm@2.15.12</p>
|
||||
|
||||
93
node_modules/npm/html/doc/files/npmrc.html
generated
vendored
Normal file
93
node_modules/npm/html/doc/files/npmrc.html
generated
vendored
Normal file
@@ -0,0 +1,93 @@
|
||||
<!doctype html>
|
||||
<html>
|
||||
<title>npmrc</title>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" type="text/css" href="../../static/style.css">
|
||||
<link rel="canonical" href="https://www.npmjs.org/doc/files/npmrc.html">
|
||||
<script async=true src="../../static/toc.js"></script>
|
||||
|
||||
<body>
|
||||
<div id="wrapper">
|
||||
|
||||
<h1><a href="../files/npmrc.html">npmrc</a></h1> <p>The npm config files</p>
|
||||
<h2 id="description">DESCRIPTION</h2>
|
||||
<p>npm gets its config settings from the command line, environment
|
||||
variables, and <code>npmrc</code> files.</p>
|
||||
<p>The <code>npm config</code> command can be used to update and edit the contents
|
||||
of the user and global npmrc files.</p>
|
||||
<p>For a list of available configuration options, see <a href="../misc/npm-config.html">npm-config(7)</a>.</p>
|
||||
<h2 id="files">FILES</h2>
|
||||
<p>The four relevant files are:</p>
|
||||
<ul>
|
||||
<li>per-project config file (/path/to/my/project/.npmrc)</li>
|
||||
<li>per-user config file (~/.npmrc)</li>
|
||||
<li>global config file ($PREFIX/etc/npmrc)</li>
|
||||
<li>npm builtin config file (/path/to/npm/npmrc)</li>
|
||||
</ul>
|
||||
<p>All npm config files are an ini-formatted list of <code>key = value</code>
|
||||
parameters. Environment variables can be replaced using
|
||||
<code>${VARIABLE_NAME}</code>. For example:</p>
|
||||
<pre><code>prefix = ${HOME}/.npm-packages
|
||||
</code></pre><p>Each of these files is loaded, and config options are resolved in
|
||||
priority order. For example, a setting in the userconfig file would
|
||||
override the setting in the globalconfig file.</p>
|
||||
<p>Array values are specified by adding "[]" after the key name. For
|
||||
example:</p>
|
||||
<pre><code>key[] = "first value"
|
||||
key[] = "second value"
|
||||
</code></pre><p><strong>NOTE:</strong> Because local (per-project or per-user) <code>.npmrc</code> files can contain
|
||||
sensitive credentials, they must be readable and writable <em>only</em> by your user
|
||||
account (i.e. must have a mode of <code>0600</code>), otherwise they <em>will be ignored by
|
||||
npm!</em></p>
|
||||
<h4 id="comments">Comments</h4>
|
||||
<p>Lines in <code>.npmrc</code> files are interpreted as comments when they begin with a <code>;</code> or <code>#</code> character. <code>.npmrc</code> files are parsed by <a href="https://github.com/npm/ini">npm/ini</a>, which specifies this comment syntax.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code># last modified: 01 Jan 2016
|
||||
; Set a new registry for a scoped package
|
||||
@myscope:registry=https://mycustomregistry.example.org
|
||||
</code></pre><h3 id="per-project-config-file">Per-project config file</h3>
|
||||
<p>When working locally in a project, a <code>.npmrc</code> file in the root of the
|
||||
project (ie, a sibling of <code>node_modules</code> and <code>package.json</code>) will set
|
||||
config values specific to this project.</p>
|
||||
<p>Note that this only applies to the root of the project that you're
|
||||
running npm in. It has no effect when your module is published. For
|
||||
example, you can't publish a module that forces itself to install
|
||||
globally, or in a different location.</p>
|
||||
<p>Additionally, this file is not read in global mode, such as when running
|
||||
<code>npm install -g</code>.</p>
|
||||
<h3 id="per-user-config-file">Per-user config file</h3>
|
||||
<p><code>$HOME/.npmrc</code> (or the <code>userconfig</code> param, if set in the environment
|
||||
or on the command line)</p>
|
||||
<h3 id="global-config-file">Global config file</h3>
|
||||
<p><code>$PREFIX/etc/npmrc</code> (or the <code>globalconfig</code> param, if set above):
|
||||
This file is an ini-file formatted list of <code>key = value</code> parameters.
|
||||
Environment variables can be replaced as above.</p>
|
||||
<h3 id="built-in-config-file">Built-in config file</h3>
|
||||
<p><code>path/to/npm/itself/npmrc</code></p>
|
||||
<p>This is an unchangeable "builtin" configuration file that npm keeps
|
||||
consistent across updates. Set fields in here using the <code>./configure</code>
|
||||
script that comes with npm. This is primarily for distribution
|
||||
maintainers to override default configs in a standard and consistent
|
||||
manner.</p>
|
||||
<h2 id="see-also">SEE ALSO</h2>
|
||||
<ul>
|
||||
<li><a href="../files/npm-folders.html">npm-folders(5)</a></li>
|
||||
<li><a href="../cli/npm-config.html">npm-config(1)</a></li>
|
||||
<li><a href="../misc/npm-config.html">npm-config(7)</a></li>
|
||||
<li><a href="../files/package.json.html">package.json(5)</a></li>
|
||||
<li><a href="../cli/npm.html">npm(1)</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
|
||||
<table border=0 cellspacing=0 cellpadding=0 id=npmlogo>
|
||||
<tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr>
|
||||
<tr><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td colspan=6 style="width:60px;height:10px;background:#fff"> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td></tr>
|
||||
<tr><td colspan=2 style="width:20px;height:30px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=4 colspan=2> </td><td style="width:10px;height:20px;background:rgb(237,127,127)" rowspan=2> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=3 colspan=2> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff"> </td></tr>
|
||||
<tr><td style="width:60px;height:10px;background:rgb(237,127,127)" colspan=6> </td><td colspan=10 style="width:10px;height:10px;background:rgb(237,127,127)"> </td></tr>
|
||||
<tr><td colspan=5 style="width:50px;height:10px;background:#fff"> </td><td style="width:40px;height:10px;background:rgb(237,127,127)" colspan=4> </td><td style="width:90px;height:10px;background:#fff" colspan=9> </td></tr>
|
||||
</table>
|
||||
<p id="footer">npmrc — npm@2.15.12</p>
|
||||
|
||||
589
node_modules/npm/html/doc/files/package.json.html
generated
vendored
Normal file
589
node_modules/npm/html/doc/files/package.json.html
generated
vendored
Normal file
@@ -0,0 +1,589 @@
|
||||
<!doctype html>
|
||||
<html>
|
||||
<title>package.json</title>
|
||||
<meta charset="utf-8">
|
||||
<link rel="stylesheet" type="text/css" href="../../static/style.css">
|
||||
<link rel="canonical" href="https://www.npmjs.org/doc/files/package.json.html">
|
||||
<script async=true src="../../static/toc.js"></script>
|
||||
|
||||
<body>
|
||||
<div id="wrapper">
|
||||
|
||||
<h1><a href="../files/package.json.html">package.json</a></h1> <p>Specifics of npm's package.json handling</p>
|
||||
<h2 id="description">DESCRIPTION</h2>
|
||||
<p>This document is all you need to know about what's required in your package.json
|
||||
file. It must be actual JSON, not just a JavaScript object literal.</p>
|
||||
<p>A lot of the behavior described in this document is affected by the config
|
||||
settings described in <code><a href="../misc/npm-config.html">npm-config(7)</a></code>.</p>
|
||||
<h2 id="name">name</h2>
|
||||
<p>The <em>most</em> important things in your package.json are the name and version fields.
|
||||
Those are actually required, and your package won't install without
|
||||
them. The name and version together form an identifier that is assumed
|
||||
to be completely unique. Changes to the package should come along with
|
||||
changes to the version.</p>
|
||||
<p>The name is what your thing is called.</p>
|
||||
<p>Some rules:</p>
|
||||
<ul>
|
||||
<li>The name must be less than or equal to 214 characters. This includes the scope for
|
||||
scoped packages.</li>
|
||||
<li>The name can't start with a dot or an underscore.</li>
|
||||
<li>New packages must not have uppercase letters in the name.</li>
|
||||
<li>The name ends up being part of a URL, an argument on the command line, and a
|
||||
folder name. Therefore, the name can't contain any non-URL-safe characters.</li>
|
||||
</ul>
|
||||
<p>Some tips:</p>
|
||||
<ul>
|
||||
<li>Don't use the same name as a core Node module.</li>
|
||||
<li>Don't put "js" or "node" in the name. It's assumed that it's js, since you're
|
||||
writing a package.json file, and you can specify the engine using the "engines"
|
||||
field. (See below.)</li>
|
||||
<li>The name will probably be passed as an argument to require(), so it should
|
||||
be something short, but also reasonably descriptive.</li>
|
||||
<li>You may want to check the npm registry to see if there's something by that name
|
||||
already, before you get too attached to it. <a href="https://www.npmjs.com/">https://www.npmjs.com/</a></li>
|
||||
</ul>
|
||||
<p>A name can be optionally prefixed by a scope, e.g. <code>@myorg/mypackage</code>. See
|
||||
<code><a href="../misc/npm-scope.html">npm-scope(7)</a></code> for more detail.</p>
|
||||
<h2 id="version">version</h2>
|
||||
<p>The <em>most</em> important things in your package.json are the name and version fields.
|
||||
Those are actually required, and your package won't install without
|
||||
them. The name and version together form an identifier that is assumed
|
||||
to be completely unique. Changes to the package should come along with
|
||||
changes to the version.</p>
|
||||
<p>Version must be parseable by
|
||||
<a href="https://github.com/isaacs/node-semver">node-semver</a>, which is bundled
|
||||
with npm as a dependency. (<code>npm install semver</code> to use it yourself.)</p>
|
||||
<p>More on version numbers and ranges at <a href="../misc/semver.html">semver(7)</a>.</p>
|
||||
<h2 id="description">description</h2>
|
||||
<p>Put a description in it. It's a string. This helps people discover your
|
||||
package, as it's listed in <code>npm search</code>.</p>
|
||||
<h2 id="keywords">keywords</h2>
|
||||
<p>Put keywords in it. It's an array of strings. This helps people
|
||||
discover your package as it's listed in <code>npm search</code>.</p>
|
||||
<h2 id="homepage">homepage</h2>
|
||||
<p>The url to the project homepage.</p>
|
||||
<p><strong>NOTE</strong>: This is <em>not</em> the same as "url". If you put a "url" field,
|
||||
then the registry will think it's a redirection to your package that has
|
||||
been published somewhere else, and spit at you.</p>
|
||||
<p>Literally. Spit. I'm so not kidding.</p>
|
||||
<h2 id="bugs">bugs</h2>
|
||||
<p>The url to your project's issue tracker and / or the email address to which
|
||||
issues should be reported. These are helpful for people who encounter issues
|
||||
with your package.</p>
|
||||
<p>It should look like this:</p>
|
||||
<pre><code>{ "url" : "https://github.com/owner/project/issues"
|
||||
, "email" : "project@hostname.com"
|
||||
}
|
||||
</code></pre><p>You can specify either one or both values. If you want to provide only a url,
|
||||
you can specify the value for "bugs" as a simple string instead of an object.</p>
|
||||
<p>If a url is provided, it will be used by the <code>npm bugs</code> command.</p>
|
||||
<h2 id="license">license</h2>
|
||||
<p>You should specify a license for your package so that people know how they are
|
||||
permitted to use it, and any restrictions you're placing on it.</p>
|
||||
<p>If you're using a common license such as BSD-2-Clause or MIT, add a
|
||||
current SPDX license identifier for the license you're using, like this:</p>
|
||||
<pre><code>{ "license" : "BSD-3-Clause" }
|
||||
</code></pre><p>You can check <a href="https://spdx.org/licenses/">the full list of SPDX license IDs</a>.
|
||||
Ideally you should pick one that is
|
||||
<a href="https://opensource.org/licenses/alphabetical">OSI</a> approved.</p>
|
||||
<p>If your package is licensed under multiple common licenses, use an <a href="https://npmjs.com/package/spdx">SPDX license
|
||||
expression syntax version 2.0 string</a>, like this:</p>
|
||||
<pre><code>{ "license" : "(ISC OR GPL-3.0)" }
|
||||
</code></pre><p>If you are using a license that hasn't been assigned an SPDX identifier, or if
|
||||
you are using a custom license, use a string value like this one:</p>
|
||||
<pre><code>{ "license" : "SEE LICENSE IN <filename>" }
|
||||
</code></pre><p>Then include a file named <code><filename></code> at the top level of the package.</p>
|
||||
<p>Some old packages used license objects or a "licenses" property containing an
|
||||
array of license objects:</p>
|
||||
<pre><code>// Not valid metadata
|
||||
{ "license" :
|
||||
{ "type" : "ISC"
|
||||
, "url" : "http://opensource.org/licenses/ISC"
|
||||
}
|
||||
}
|
||||
|
||||
// Not valid metadata
|
||||
{ "licenses" :
|
||||
[
|
||||
{ "type": "MIT"
|
||||
, "url": "http://www.opensource.org/licenses/mit-license.php"
|
||||
}
|
||||
, { "type": "Apache-2.0"
|
||||
, "url": "http://opensource.org/licenses/apache2.0.php"
|
||||
}
|
||||
]
|
||||
}
|
||||
</code></pre><p>Those styles are now deprecated. Instead, use SPDX expressions, like this:</p>
|
||||
<pre><code>{ "license": "ISC" }
|
||||
|
||||
{ "license": "(MIT OR Apache-2.0)" }
|
||||
</code></pre><p>Finally, if you do not wish to grant others the right to use a private or
|
||||
unpublished package under any terms:</p>
|
||||
<pre><code>{ "license": "UNLICENSED"}
|
||||
</code></pre><p>Consider also setting <code>"private": true</code> to prevent accidental publication.</p>
|
||||
<h2 id="people-fields-author-contributors">people fields: author, contributors</h2>
|
||||
<p>The "author" is one person. "contributors" is an array of people. A "person"
|
||||
is an object with a "name" field and optionally "url" and "email", like this:</p>
|
||||
<pre><code>{ "name" : "Barney Rubble"
|
||||
, "email" : "b@rubble.com"
|
||||
, "url" : "http://barnyrubble.tumblr.com/"
|
||||
}
|
||||
</code></pre><p>Or you can shorten that all into a single string, and npm will parse it for you:</p>
|
||||
<pre><code>"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"
|
||||
</code></pre><p>Both email and url are optional either way.</p>
|
||||
<p>npm also sets a top-level "maintainers" field with your npm user info.</p>
|
||||
<h2 id="files">files</h2>
|
||||
<p>The "files" field is an array of files to include in your project. If
|
||||
you name a folder in the array, then it will also include the files
|
||||
inside that folder. (Unless they would be ignored by another rule.)</p>
|
||||
<p>You can also provide a ".npmignore" file in the root of your package or
|
||||
in subdirectories, which will keep files from being included, even
|
||||
if they would be picked up by the files array. The <code>.npmignore</code> file
|
||||
works just like a <code>.gitignore</code>.</p>
|
||||
<p>Certain files are always included, regardless of settings:</p>
|
||||
<ul>
|
||||
<li><code>package.json</code></li>
|
||||
<li><code><a href="../../doc/README.html">README</a></code></li>
|
||||
<li><code>CHANGES</code> / <code>CHANGELOG</code> / <code>HISTORY</code> (any casing and file extension)</li>
|
||||
<li><code>LICENSE</code> / <code>LICENCE</code></li>
|
||||
<li>The file in the "main" field</li>
|
||||
</ul>
|
||||
<p>Conversely, some files are always ignored:</p>
|
||||
<ul>
|
||||
<li><code>.git</code></li>
|
||||
<li><code>CVS</code></li>
|
||||
<li><code>.svn</code></li>
|
||||
<li><code>.hg</code></li>
|
||||
<li><code>.lock-wscript</code></li>
|
||||
<li><code>.wafpickle-N</code></li>
|
||||
<li><code>.*.swp</code></li>
|
||||
<li><code>.DS_Store</code></li>
|
||||
<li><code>._*</code></li>
|
||||
<li><code>npm-debug.log</code></li>
|
||||
<li><code>.npmrc</code></li>
|
||||
<li><code>node_modules</code></li>
|
||||
</ul>
|
||||
<h2 id="main">main</h2>
|
||||
<p>The main field is a module ID that is the primary entry point to your program.
|
||||
That is, if your package is named <code>foo</code>, and a user installs it, and then does
|
||||
<code>require("foo")</code>, then your main module's exports object will be returned.</p>
|
||||
<p>This should be a module ID relative to the root of your package folder.</p>
|
||||
<p>For most modules, it makes the most sense to have a main script and often not
|
||||
much else.</p>
|
||||
<h2 id="bin">bin</h2>
|
||||
<p>A lot of packages have one or more executable files that they'd like to
|
||||
install into the PATH. npm makes this pretty easy (in fact, it uses this
|
||||
feature to install the "npm" executable.)</p>
|
||||
<p>To use this, supply a <code>bin</code> field in your package.json which is a map of
|
||||
command name to local file name. On install, npm will symlink that file into
|
||||
<code>prefix/bin</code> for global installs, or <code>./node_modules/.bin/</code> for local
|
||||
installs.</p>
|
||||
<p>For example, myapp could have this:</p>
|
||||
<pre><code>{ "bin" : { "myapp" : "./cli.js" } }
|
||||
</code></pre><p>So, when you install myapp, it'll create a symlink from the <code>cli.js</code> script to
|
||||
<code>/usr/local/bin/myapp</code>.</p>
|
||||
<p>If you have a single executable, and its name should be the name
|
||||
of the package, then you can just supply it as a string. For example:</p>
|
||||
<pre><code>{ "name": "my-program"
|
||||
, "version": "1.2.5"
|
||||
, "bin": "./path/to/program" }
|
||||
</code></pre><p>would be the same as this:</p>
|
||||
<pre><code>{ "name": "my-program"
|
||||
, "version": "1.2.5"
|
||||
, "bin" : { "my-program" : "./path/to/program" } }
|
||||
</code></pre><p>Please make sure that your file(s) referenced in <code>bin</code> starts with
|
||||
<code>#!/usr/bin/env node</code>, otherwise the scripts are started without the node
|
||||
executable!</p>
|
||||
<h2 id="man">man</h2>
|
||||
<p>Specify either a single file or an array of filenames to put in place for the
|
||||
<code>man</code> program to find.</p>
|
||||
<p>If only a single file is provided, then it's installed such that it is the
|
||||
result from <code>man <pkgname></code>, regardless of its actual filename. For example:</p>
|
||||
<pre><code>{ "name" : "foo"
|
||||
, "version" : "1.2.3"
|
||||
, "description" : "A packaged foo fooer for fooing foos"
|
||||
, "main" : "foo.js"
|
||||
, "man" : "./man/doc.1"
|
||||
}
|
||||
</code></pre><p>would link the <code>./man/doc.1</code> file in such that it is the target for <code>man foo</code></p>
|
||||
<p>If the filename doesn't start with the package name, then it's prefixed.
|
||||
So, this:</p>
|
||||
<pre><code>{ "name" : "foo"
|
||||
, "version" : "1.2.3"
|
||||
, "description" : "A packaged foo fooer for fooing foos"
|
||||
, "main" : "foo.js"
|
||||
, "man" : [ "./man/foo.1", "./man/bar.1" ]
|
||||
}
|
||||
</code></pre><p>will create files to do <code>man foo</code> and <code>man foo-bar</code>.</p>
|
||||
<p>Man files must end with a number, and optionally a <code>.gz</code> suffix if they are
|
||||
compressed. The number dictates which man section the file is installed into.</p>
|
||||
<pre><code>{ "name" : "foo"
|
||||
, "version" : "1.2.3"
|
||||
, "description" : "A packaged foo fooer for fooing foos"
|
||||
, "main" : "foo.js"
|
||||
, "man" : [ "./man/foo.1", "./man/foo.2" ]
|
||||
}
|
||||
</code></pre><p>will create entries for <code>man foo</code> and <code>man 2 foo</code></p>
|
||||
<h2 id="directories">directories</h2>
|
||||
<p>The CommonJS <a href="http://wiki.commonjs.org/wiki/Packages/1.0">Packages</a> spec details a
|
||||
few ways that you can indicate the structure of your package using a <code>directories</code>
|
||||
object. If you look at <a href="https://registry.npmjs.org/npm/latest">npm's package.json</a>,
|
||||
you'll see that it has directories for doc, lib, and man.</p>
|
||||
<p>In the future, this information may be used in other creative ways.</p>
|
||||
<h3 id="directories-lib">directories.lib</h3>
|
||||
<p>Tell people where the bulk of your library is. Nothing special is done
|
||||
with the lib folder in any way, but it's useful meta info.</p>
|
||||
<h3 id="directories-bin">directories.bin</h3>
|
||||
<p>If you specify a <code>bin</code> directory in <code>directories.bin</code>, all the files in
|
||||
that folder will be added.</p>
|
||||
<p>Because of the way the <code>bin</code> directive works, specifying both a
|
||||
<code>bin</code> path and setting <code>directories.bin</code> is an error. If you want to
|
||||
specify individual files, use <code>bin</code>, and for all the files in an
|
||||
existing <code>bin</code> directory, use <code>directories.bin</code>.</p>
|
||||
<h3 id="directories-man">directories.man</h3>
|
||||
<p>A folder that is full of man pages. Sugar to generate a "man" array by
|
||||
walking the folder.</p>
|
||||
<h3 id="directories-doc">directories.doc</h3>
|
||||
<p>Put markdown files in here. Eventually, these will be displayed nicely,
|
||||
maybe, someday.</p>
|
||||
<h3 id="directories-example">directories.example</h3>
|
||||
<p>Put example scripts in here. Someday, it might be exposed in some clever way.</p>
|
||||
<h3 id="directories-test">directories.test</h3>
|
||||
<p>Put your tests in here. It is currently not exposed, but it might be in the
|
||||
future.</p>
|
||||
<h2 id="repository">repository</h2>
|
||||
<p>Specify the place where your code lives. This is helpful for people who
|
||||
want to contribute. If the git repo is on GitHub, then the <code>npm docs</code>
|
||||
command will be able to find you.</p>
|
||||
<p>Do it like this:</p>
|
||||
<pre><code>"repository" :
|
||||
{ "type" : "git"
|
||||
, "url" : "https://github.com/npm/npm.git"
|
||||
}
|
||||
|
||||
"repository" :
|
||||
{ "type" : "svn"
|
||||
, "url" : "https://v8.googlecode.com/svn/trunk/"
|
||||
}
|
||||
</code></pre><p>The URL should be a publicly available (perhaps read-only) url that can be handed
|
||||
directly to a VCS program without any modification. It should not be a url to an
|
||||
html project page that you put in your browser. It's for computers.</p>
|
||||
<p>For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same
|
||||
shortcut syntax you use for <code>npm install</code>:</p>
|
||||
<pre><code>"repository": "npm/npm"
|
||||
|
||||
"repository": "gist:11081aaa281"
|
||||
|
||||
"repository": "bitbucket:example/repo"
|
||||
|
||||
"repository": "gitlab:another/repo"
|
||||
</code></pre><h2 id="scripts">scripts</h2>
|
||||
<p>The "scripts" property is a dictionary containing script commands that are run
|
||||
at various times in the lifecycle of your package. The key is the lifecycle
|
||||
event, and the value is the command to run at that point.</p>
|
||||
<p>See <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code> to find out more about writing package scripts.</p>
|
||||
<h2 id="config">config</h2>
|
||||
<p>A "config" object can be used to set configuration parameters used in package
|
||||
scripts that persist across upgrades. For instance, if a package had the
|
||||
following:</p>
|
||||
<pre><code>{ "name" : "foo"
|
||||
, "config" : { "port" : "8080" } }
|
||||
</code></pre><p>and then had a "start" command that then referenced the
|
||||
<code>npm_package_config_port</code> environment variable, then the user could
|
||||
override that by doing <code>npm config set foo:port 8001</code>.</p>
|
||||
<p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> and <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code> for more on package
|
||||
configs.</p>
|
||||
<h2 id="dependencies">dependencies</h2>
|
||||
<p>Dependencies are specified in a simple object that maps a package name to a
|
||||
version range. The version range is a string which has one or more
|
||||
space-separated descriptors. Dependencies can also be identified with a
|
||||
tarball or git URL.</p>
|
||||
<p><strong>Please do not put test harnesses or transpilers in your
|
||||
<code>dependencies</code> object.</strong> See <code>devDependencies</code>, below.</p>
|
||||
<p>See <a href="../misc/semver.html">semver(7)</a> for more details about specifying version ranges.</p>
|
||||
<ul>
|
||||
<li><code>version</code> Must match <code>version</code> exactly</li>
|
||||
<li><code>>version</code> Must be greater than <code>version</code></li>
|
||||
<li><code>>=version</code> etc</li>
|
||||
<li><code><version</code></li>
|
||||
<li><code><=version</code></li>
|
||||
<li><code>~version</code> "Approximately equivalent to version" See <a href="../misc/semver.html">semver(7)</a></li>
|
||||
<li><code>^version</code> "Compatible with version" See <a href="../misc/semver.html">semver(7)</a></li>
|
||||
<li><code>1.2.x</code> 1.2.0, 1.2.1, etc., but not 1.3.0</li>
|
||||
<li><code>http://...</code> See 'URLs as Dependencies' below</li>
|
||||
<li><code>*</code> Matches any version</li>
|
||||
<li><code>""</code> (just an empty string) Same as <code>*</code></li>
|
||||
<li><code>version1 - version2</code> Same as <code>>=version1 <=version2</code>.</li>
|
||||
<li><code>range1 || range2</code> Passes if either range1 or range2 are satisfied.</li>
|
||||
<li><code>git...</code> See 'Git URLs as Dependencies' below</li>
|
||||
<li><code>user/repo</code> See 'GitHub URLs' below</li>
|
||||
<li><code>tag</code> A specific version tagged and published as <code>tag</code> See <code><a href="../cli/npm-tag.html">npm-tag(1)</a></code></li>
|
||||
<li><code>path/path/path</code> See <a href="#local-paths">Local Paths</a> below</li>
|
||||
</ul>
|
||||
<p>For example, these are all valid:</p>
|
||||
<pre><code>{ "dependencies" :
|
||||
{ "foo" : "1.0.0 - 2.9999.9999"
|
||||
, "bar" : ">=1.0.2 <2.1.2"
|
||||
, "baz" : ">1.0.2 <=2.3.4"
|
||||
, "boo" : "2.0.1"
|
||||
, "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
|
||||
, "asd" : "http://asdf.com/asdf.tar.gz"
|
||||
, "til" : "~1.2"
|
||||
, "elf" : "~1.2.3"
|
||||
, "two" : "2.x"
|
||||
, "thr" : "3.3.x"
|
||||
, "lat" : "latest"
|
||||
, "dyl" : "file:../dyl"
|
||||
}
|
||||
}
|
||||
</code></pre><h3 id="urls-as-dependencies">URLs as Dependencies</h3>
|
||||
<p>You may specify a tarball URL in place of a version range.</p>
|
||||
<p>This tarball will be downloaded and installed locally to your package at
|
||||
install time.</p>
|
||||
<h3 id="git-urls-as-dependencies">Git URLs as Dependencies</h3>
|
||||
<p>Git urls can be of the form:</p>
|
||||
<pre><code>git://github.com/user/project.git#commit-ish
|
||||
git+ssh://user@hostname:project.git#commit-ish
|
||||
git+ssh://user@hostname/project.git#commit-ish
|
||||
git+http://user@hostname/project/blah.git#commit-ish
|
||||
git+https://user@hostname/project/blah.git#commit-ish
|
||||
</code></pre><p>The <code>commit-ish</code> can be any tag, sha, or branch which can be supplied as
|
||||
an argument to <code>git checkout</code>. The default is <code>master</code>.</p>
|
||||
<h2 id="github-urls">GitHub URLs</h2>
|
||||
<p>As of version 1.1.65, you can refer to GitHub urls as just "foo":
|
||||
"user/foo-project". Just as with git URLs, a <code>commit-ish</code> suffix can be
|
||||
included. For example:</p>
|
||||
<pre><code>{
|
||||
"name": "foo",
|
||||
"version": "0.0.0",
|
||||
"dependencies": {
|
||||
"express": "visionmedia/express",
|
||||
"mocha": "visionmedia/mocha#4727d357ea"
|
||||
}
|
||||
}
|
||||
</code></pre><h2 id="local-paths">Local Paths</h2>
|
||||
<p>As of version 2.0.0 you can provide a path to a local directory that contains a
|
||||
package. Local paths can be saved using <code>npm install --save</code>, using any of
|
||||
these forms:</p>
|
||||
<pre><code>../foo/bar
|
||||
~/foo/bar
|
||||
./foo/bar
|
||||
/foo/bar
|
||||
</code></pre><p>in which case they will be normalized to a relative path and added to your
|
||||
<code>package.json</code>. For example:</p>
|
||||
<pre><code>{
|
||||
"name": "baz",
|
||||
"dependencies": {
|
||||
"bar": "file:../foo/bar"
|
||||
}
|
||||
}
|
||||
</code></pre><p>This feature is helpful for local offline development and creating
|
||||
tests that require npm installing where you don't want to hit an
|
||||
external server, but should not be used when publishing packages
|
||||
to the public registry.</p>
|
||||
<h2 id="devdependencies">devDependencies</h2>
|
||||
<p>If someone is planning on downloading and using your module in their
|
||||
program, then they probably don't want or need to download and build
|
||||
the external test or documentation framework that you use.</p>
|
||||
<p>In this case, it's best to map these additional items in a <code>devDependencies</code>
|
||||
object.</p>
|
||||
<p>These things will be installed when doing <code>npm link</code> or <code>npm install</code>
|
||||
from the root of a package, and can be managed like any other npm
|
||||
configuration param. See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> for more on the topic.</p>
|
||||
<p>For build steps that are not platform-specific, such as compiling
|
||||
CoffeeScript or other languages to JavaScript, use the <code>prepublish</code>
|
||||
script to do this, and make the required package a devDependency.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code>{ "name": "ethopia-waza",
|
||||
"description": "a delightfully fruity coffee varietal",
|
||||
"version": "1.2.3",
|
||||
"devDependencies": {
|
||||
"coffee-script": "~1.6.3"
|
||||
},
|
||||
"scripts": {
|
||||
"prepublish": "coffee -o lib/ -c src/waza.coffee"
|
||||
},
|
||||
"main": "lib/waza.js"
|
||||
}
|
||||
</code></pre><p>The <code>prepublish</code> script will be run before publishing, so that users
|
||||
can consume the functionality without requiring them to compile it
|
||||
themselves. In dev mode (ie, locally running <code>npm install</code>), it'll
|
||||
run this script as well, so that you can test it easily.</p>
|
||||
<h2 id="peerdependencies">peerDependencies</h2>
|
||||
<p>In some cases, you want to express the compatibility of your package with a
|
||||
host tool or library, while not necessarily doing a <code>require</code> of this host.
|
||||
This is usually referred to as a <em>plugin</em>. Notably, your module may be exposing
|
||||
a specific interface, expected and specified by the host documentation.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code>{
|
||||
"name": "tea-latte",
|
||||
"version": "1.3.5",
|
||||
"peerDependencies": {
|
||||
"tea": "2.x"
|
||||
}
|
||||
}
|
||||
</code></pre><p>This ensures your package <code>tea-latte</code> can be installed <em>along</em> with the second
|
||||
major version of the host package <code>tea</code> only. <code>npm install tea-latte</code> could
|
||||
possibly yield the following dependency graph:</p>
|
||||
<pre><code>├── tea-latte@1.3.5
|
||||
└── tea@2.2.0
|
||||
</code></pre><p><strong>NOTE: npm versions 1 and 2 will automatically install <code>peerDependencies</code> if
|
||||
they are not explicitly depended upon higher in the dependency tree. In the
|
||||
next major version of npm (npm@3), this will no longer be the case. You will
|
||||
receive a warning that the peerDependency is not installed instead.</strong> The
|
||||
behavior in npms 1 & 2 was frequently confusing and could easily put you into
|
||||
dependency hell, a situation that npm is designed to avoid as much as possible.</p>
|
||||
<p>Trying to install another plugin with a conflicting requirement will cause an
|
||||
error. For this reason, make sure your plugin requirement is as broad as
|
||||
possible, and not to lock it down to specific patch versions.</p>
|
||||
<p>Assuming the host complies with <a href="http://semver.org/">semver</a>, only changes in
|
||||
the host package's major version will break your plugin. Thus, if you've worked
|
||||
with every 1.x version of the host package, use <code>"^1.0"</code> or <code>"1.x"</code> to express
|
||||
this. If you depend on features introduced in 1.5.2, use <code>">= 1.5.2 < 2"</code>.</p>
|
||||
<h2 id="bundleddependencies">bundledDependencies</h2>
|
||||
<p>This defines an array of package names that will be bundled when publishing the package.</p>
|
||||
<p>In cases where you need to preserve npm packages locally or have them available through a single file download, you can bundle the packages in a tarball file by specifying the package names in the <code>bundledDependencies</code> array and executing <code>npm pack</code>.</p>
|
||||
<p>For example:
|
||||
If we define a package.json like this:</p>
|
||||
<pre><code>{
|
||||
"name": "awesome-web-framework",
|
||||
"version": "1.0.0",
|
||||
"bundledDependencies": [
|
||||
'renderized', 'super-streams'
|
||||
]
|
||||
}
|
||||
</code></pre><p>we can obtain <code>awesome-web-framework-1.0.0.tgz</code> file by running <code>npm pack</code>. This file contains the dependencies <code>renderized</code> and <code>super-streams</code> which can be installed in a new project by executing <code>npm install awesome-web-framework-1.0.0.tgz</code>.</p>
|
||||
<p>If this is spelled <code>"bundleDependencies"</code>, then that is also honored.</p>
|
||||
<h2 id="optionaldependencies">optionalDependencies</h2>
|
||||
<p>If a dependency can be used, but you would like npm to proceed if it cannot be
|
||||
found or fails to install, then you may put it in the <code>optionalDependencies</code>
|
||||
object. This is a map of package name to version or url, just like the
|
||||
<code>dependencies</code> object. The difference is that build failures do not cause
|
||||
installation to fail.</p>
|
||||
<p>It is still your program's responsibility to handle the lack of the
|
||||
dependency. For example, something like this:</p>
|
||||
<pre><code>try {
|
||||
var foo = require('foo')
|
||||
var fooVersion = require('foo/package.json').version
|
||||
} catch (er) {
|
||||
foo = null
|
||||
}
|
||||
if ( notGoodFooVersion(fooVersion) ) {
|
||||
foo = null
|
||||
}
|
||||
|
||||
// .. then later in your program ..
|
||||
|
||||
if (foo) {
|
||||
foo.doFooThings()
|
||||
}
|
||||
</code></pre><p>Entries in <code>optionalDependencies</code> will override entries of the same name in
|
||||
<code>dependencies</code>, so it's usually best to only put in one place.</p>
|
||||
<h2 id="engines">engines</h2>
|
||||
<p>You can specify the version of node that your stuff works on:</p>
|
||||
<pre><code>{ "engines" : { "node" : ">=0.10.3 <0.12" } }
|
||||
</code></pre><p>And, like with dependencies, if you don't specify the version (or if you
|
||||
specify "*" as the version), then any version of node will do.</p>
|
||||
<p>If you specify an "engines" field, then npm will require that "node" be
|
||||
somewhere on that list. If "engines" is omitted, then npm will just assume
|
||||
that it works on node.</p>
|
||||
<p>You can also use the "engines" field to specify which versions of npm
|
||||
are capable of properly installing your program. For example:</p>
|
||||
<pre><code>{ "engines" : { "npm" : "~1.0.20" } }
|
||||
</code></pre><p>Unless the user has set the <code>engine-strict</code> config flag, this
|
||||
field is advisory only will produce warnings when your package is installed as a dependency.</p>
|
||||
<h2 id="enginestrict">engineStrict</h2>
|
||||
<p><strong>NOTE: This feature is deprecated and will be removed in npm 3.0.0.</strong></p>
|
||||
<p>If you are sure that your module will <em>definitely not</em> run properly on
|
||||
versions of Node/npm other than those specified in the <code>engines</code> object,
|
||||
then you can set <code>"engineStrict": true</code> in your package.json file.
|
||||
This will override the user's <code>engine-strict</code> config setting.</p>
|
||||
<p>Please do not do this unless you are really very very sure. If your
|
||||
engines object is something overly restrictive, you can quite easily and
|
||||
inadvertently lock yourself into obscurity and prevent your users from
|
||||
updating to new versions of Node. Consider this choice carefully.</p>
|
||||
<h2 id="os">os</h2>
|
||||
<p>You can specify which operating systems your
|
||||
module will run on:</p>
|
||||
<pre><code>"os" : [ "darwin", "linux" ]
|
||||
</code></pre><p>You can also blacklist instead of whitelist operating systems,
|
||||
just prepend the blacklisted os with a '!':</p>
|
||||
<pre><code>"os" : [ "!win32" ]
|
||||
</code></pre><p>The host operating system is determined by <code>process.platform</code></p>
|
||||
<p>It is allowed to both blacklist, and whitelist, although there isn't any
|
||||
good reason to do this.</p>
|
||||
<h2 id="cpu">cpu</h2>
|
||||
<p>If your code only runs on certain cpu architectures,
|
||||
you can specify which ones.</p>
|
||||
<pre><code>"cpu" : [ "x64", "ia32" ]
|
||||
</code></pre><p>Like the <code>os</code> option, you can also blacklist architectures:</p>
|
||||
<pre><code>"cpu" : [ "!arm", "!mips" ]
|
||||
</code></pre><p>The host architecture is determined by <code>process.arch</code></p>
|
||||
<h2 id="preferglobal">preferGlobal</h2>
|
||||
<p>If your package is primarily a command-line application that should be
|
||||
installed globally, then set this value to <code>true</code> to provide a warning
|
||||
if it is installed locally.</p>
|
||||
<p>It doesn't actually prevent users from installing it locally, but it
|
||||
does help prevent some confusion if it doesn't work as expected.</p>
|
||||
<h2 id="private">private</h2>
|
||||
<p>If you set <code>"private": true</code> in your package.json, then npm will refuse
|
||||
to publish it.</p>
|
||||
<p>This is a way to prevent accidental publication of private repositories. If
|
||||
you would like to ensure that a given package is only ever published to a
|
||||
specific registry (for example, an internal registry), then use the
|
||||
<code>publishConfig</code> dictionary described below to override the <code>registry</code> config
|
||||
param at publish-time.</p>
|
||||
<h2 id="publishconfig">publishConfig</h2>
|
||||
<p>This is a set of config values that will be used at publish-time. It's
|
||||
especially handy if you want to set the tag, registry or access, so that
|
||||
you can ensure that a given package is not tagged with "latest", published
|
||||
to the global public registry or that a scoped module is private by default.</p>
|
||||
<p>Any config values can be overridden, but of course only "tag", "registry" and
|
||||
"access" probably matter for the purposes of publishing.</p>
|
||||
<p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> to see the list of config options that can be
|
||||
overridden.</p>
|
||||
<h2 id="default-values">DEFAULT VALUES</h2>
|
||||
<p>npm will default some values based on package contents.</p>
|
||||
<ul>
|
||||
<li><p><code>"scripts": {"start": "node server.js"}</code></p>
|
||||
<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>.</p>
|
||||
</li>
|
||||
<li><p><code>"scripts":{"install": "node-gyp rebuild"}</code></p>
|
||||
<p>If there is a <code>binding.gyp</code> file in the root of your package and you have not defined an <code>install</code> or <code>preinstall</code> script, npm will
|
||||
default the <code>install</code> command to compile using node-gyp.</p>
|
||||
</li>
|
||||
<li><p><code>"contributors": [...]</code></p>
|
||||
<p>If there is an <code>AUTHORS</code> file in the root of your package, npm will
|
||||
treat each line as a <code>Name <email> (url)</code> format, where email and url
|
||||
are optional. Lines which start with a <code>#</code> or are blank, will be
|
||||
ignored.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<h2 id="see-also">SEE ALSO</h2>
|
||||
<ul>
|
||||
<li><a href="../misc/semver.html">semver(7)</a></li>
|
||||
<li><a href="../cli/npm-init.html">npm-init(1)</a></li>
|
||||
<li><a href="../cli/npm-version.html">npm-version(1)</a></li>
|
||||
<li><a href="../cli/npm-config.html">npm-config(1)</a></li>
|
||||
<li><a href="../misc/npm-config.html">npm-config(7)</a></li>
|
||||
<li><a href="../cli/npm-help.html">npm-help(1)</a></li>
|
||||
<li><a href="../misc/npm-faq.html">npm-faq(7)</a></li>
|
||||
<li><a href="../cli/npm-install.html">npm-install(1)</a></li>
|
||||
<li><a href="../cli/npm-publish.html">npm-publish(1)</a></li>
|
||||
<li><a href="../cli/npm-uninstall.html">npm-uninstall(1)</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
|
||||
<table border=0 cellspacing=0 cellpadding=0 id=npmlogo>
|
||||
<tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr>
|
||||
<tr><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td colspan=6 style="width:60px;height:10px;background:#fff"> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td></tr>
|
||||
<tr><td colspan=2 style="width:20px;height:30px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=4 colspan=2> </td><td style="width:10px;height:20px;background:rgb(237,127,127)" rowspan=2> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=3 colspan=2> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr>
|
||||
<tr><td style="width:10px;height:10px;background:#fff"> </td></tr>
|
||||
<tr><td style="width:60px;height:10px;background:rgb(237,127,127)" colspan=6> </td><td colspan=10 style="width:10px;height:10px;background:rgb(237,127,127)"> </td></tr>
|
||||
<tr><td colspan=5 style="width:50px;height:10px;background:#fff"> </td><td style="width:40px;height:10px;background:rgb(237,127,127)" colspan=4> </td><td style="width:90px;height:10px;background:#fff" colspan=9> </td></tr>
|
||||
</table>
|
||||
<p id="footer">package.json — npm@2.15.12</p>
|
||||
|
||||
Reference in New Issue
Block a user