@ -30,7 +31,7 @@ by that. See <a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a>.</p>
<p>A <code>package</code> is:</p>
<p>A <code>package</code> is:</p>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code><git remote url></code> that resolves to (b)</li></ul>
<ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code><name>@<version></code> that is published on the registry (see <code><ahref="../misc/npm-registry.html">npm-registry(7)</a></code>) with (c)</li><li>e) a <code><name>@<tag></code> that points to (d)</li><li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li><li>g) a <code><git remote url></code> that resolves to (b)</li></ul>
<p>Even if you never publish your package, you can still get a lot of
<p>Even if you never publish your package, you can still get a lot of
benefits of using npm if you just want to write a node program (a), and
benefits of using npm if you just want to write a node program (a), and
@ -153,7 +154,7 @@ affects a real use-case, it will be investigated.</p>
<p>See <ahref="../misc/semver.html">semver(7)</a> for more details about specifying version ranges.</p>
<p>See <ahref="../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 <ahref="../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></ul>
<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 <ahref="../misc/semver.html">semver(7)</a></li><li><code>^version</code>"Compatible with version" See <ahref="../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></ul>
<p>For example, these are all valid:</p>
<p>For example, these are all valid:</p>
@ -396,6 +397,40 @@ can consume the functionality without requiring them to compile it
themselves. In dev mode (ie, locally running <code>npm install</code>), it'll
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>
run this script as well, so that you can test it easily.</p>
<h2id="peerDependencies">peerDependencies</h2>
<p>In some cases, you want to express the compatibility of your package with an
host tool or library, while not necessarily doing a <code>require</code> of this host.
This is usually refered 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. The host package is automatically
installed if needed. <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>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 <ahref="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>
Timothy J Fontaine
11 years ago