You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
184 lines
11 KiB
184 lines
11 KiB
<!doctype html>
|
|
<html>
|
|
<title>npm-shrinkwrap</title>
|
|
<meta charset="utf-8">
|
|
<link rel="stylesheet" type="text/css" href="../../static/style.css">
|
|
<link rel="canonical" href="https://www.npmjs.org/doc/cli/npm-shrinkwrap.html">
|
|
<script async=true src="../../static/toc.js"></script>
|
|
|
|
<body>
|
|
<div id="wrapper">
|
|
|
|
<h1><a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap</a></h1> <p>Lock down dependency versions</p>
|
|
<h2 id="synopsis">SYNOPSIS</h2>
|
|
<pre><code>npm shrinkwrap
|
|
</code></pre><h2 id="description">DESCRIPTION</h2>
|
|
<p>This command locks down the versions of a package's dependencies so
|
|
that you can control exactly which versions of each dependency will be
|
|
used when your package is installed. The <code>package.json</code> file is still
|
|
required if you want to use <code>npm install</code>.</p>
|
|
<p>By default, <code>npm install</code> recursively installs the target's
|
|
dependencies (as specified in <code>package.json</code>), choosing the latest
|
|
available version that satisfies the dependency's semver pattern. In
|
|
some situations, particularly when shipping software where each change
|
|
is tightly managed, it's desirable to fully specify each version of
|
|
each dependency recursively so that subsequent builds and deploys do
|
|
not inadvertently pick up newer versions of a dependency that satisfy
|
|
the semver pattern. Specifying specific semver patterns in each
|
|
dependency's <code>package.json</code> would facilitate this, but that's not always
|
|
possible or desirable, as when another author owns the npm package.
|
|
It's also possible to check dependencies directly into source control,
|
|
but that may be undesirable for other reasons.</p>
|
|
<p>As an example, consider package A:</p>
|
|
<pre><code>{
|
|
"name": "A",
|
|
"version": "0.1.0",
|
|
"dependencies": {
|
|
"B": "<0.1.0"
|
|
}
|
|
}
|
|
</code></pre><p>package B:</p>
|
|
<pre><code>{
|
|
"name": "B",
|
|
"version": "0.0.1",
|
|
"dependencies": {
|
|
"C": "<0.1.0"
|
|
}
|
|
}
|
|
</code></pre><p>and package C:</p>
|
|
<pre><code>{
|
|
"name": "C",
|
|
"version": "0.0.1"
|
|
}
|
|
</code></pre><p>If these are the only versions of A, B, and C available in the
|
|
registry, then a normal <code>npm install A</code> will install:</p>
|
|
<pre><code>A@0.1.0
|
|
`-- B@0.0.1
|
|
`-- C@0.0.1
|
|
</code></pre><p>However, if B@0.0.2 is published, then a fresh <code>npm install A</code> will
|
|
install:</p>
|
|
<pre><code>A@0.1.0
|
|
`-- B@0.0.2
|
|
`-- C@0.0.1
|
|
</code></pre><p>assuming the new version did not modify B's dependencies. Of course,
|
|
the new version of B could include a new version of C and any number
|
|
of new dependencies. If such changes are undesirable, the author of A
|
|
could specify a dependency on B@0.0.1. However, if A's author and B's
|
|
author are not the same person, there's no way for A's author to say
|
|
that he or she does not want to pull in newly published versions of C
|
|
when B hasn't changed at all.</p>
|
|
<p>In this case, A's author can run</p>
|
|
<pre><code>npm shrinkwrap
|
|
</code></pre><p>This generates <code>npm-shrinkwrap.json</code>, which will look something like this:</p>
|
|
<pre><code>{
|
|
"name": "A",
|
|
"version": "0.1.0",
|
|
"dependencies": {
|
|
"B": {
|
|
"version": "0.0.1",
|
|
"from": "B@^0.0.1",
|
|
"resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
|
|
"dependencies": {
|
|
"C": {
|
|
"version": "0.0.1",
|
|
"from": "org/C#v0.0.1",
|
|
"resolved": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code></pre><p>The shrinkwrap command has locked down the dependencies based on what's
|
|
currently installed in <code>node_modules</code>. The installation behavior is changed to:</p>
|
|
<ol>
|
|
<li><p>The module tree described by the shrinkwrap is reproduced. This means
|
|
reproducing the structure described in the file, using the specific files
|
|
referenced in "resolved" if available, falling back to normal package
|
|
resolution using "version" if one isn't.</p>
|
|
</li>
|
|
<li><p>The tree is walked and any missing dependencies are installed in the usual fashion.</p>
|
|
</li>
|
|
</ol>
|
|
<p>If <code>preshrinkwrap</code>, <code>shrinkwrap</code> or <code>postshrinkwrap</code> are in the <code>scripts</code> property of the
|
|
<code>package.json</code>, they will be executed by running <code>npm shrinkwrap</code>.
|
|
<code>preshrinkwrap</code> and <code>shrinkwrap</code> are executed before the shrinkwrap, <code>postshrinkwrap</code> is
|
|
executed afterwards. For example to run some postprocessing on the generated file:</p>
|
|
<pre><code>"scripts": { "postshrinkwrap": "node fix-shrinkwrap.js" }
|
|
</code></pre><h3 id="using-shrinkwrapped-packages">Using shrinkwrapped packages</h3>
|
|
<p>Using a shrinkwrapped package is no different than using any other
|
|
package: you can <code>npm install</code> it by hand, or add a dependency to your
|
|
<code>package.json</code> file and <code>npm install</code> it.</p>
|
|
<h3 id="building-shrinkwrapped-packages">Building shrinkwrapped packages</h3>
|
|
<p>To shrinkwrap an existing package:</p>
|
|
<ol>
|
|
<li>Run <code>npm install</code> in the package root to install the current
|
|
versions of all dependencies.</li>
|
|
<li>Validate that the package works as expected with these versions.</li>
|
|
<li>Run <code>npm shrinkwrap</code>, add <code>npm-shrinkwrap.json</code> to git, and publish
|
|
your package.</li>
|
|
</ol>
|
|
<p>To add or update a dependency in a shrinkwrapped package:</p>
|
|
<ol>
|
|
<li>Run <code>npm install</code> in the package root to install the current
|
|
versions of all dependencies.</li>
|
|
<li>Add or update dependencies. <code>npm install --save</code> or <code>npm install --save-dev</code>
|
|
each new or updated package individually to update the <code>package.json</code> and
|
|
the shrinkwrap. Note that they must be explicitly named in order to be
|
|
installed: running <code>npm install</code> with no arguments will merely reproduce
|
|
the existing shrinkwrap.</li>
|
|
<li>Validate that the package works as expected with the new
|
|
dependencies.</li>
|
|
<li>Commit the new <code>npm-shrinkwrap.json</code>, and publish your package.</li>
|
|
</ol>
|
|
<p>You can use <a href="../cli/npm-outdated.html">npm-outdated(1)</a> to view dependencies with newer versions
|
|
available.</p>
|
|
<h3 id="other-notes">Other Notes</h3>
|
|
<p>A shrinkwrap file must be consistent with the package's <code>package.json</code>
|
|
file. <code>npm shrinkwrap</code> will fail if required dependencies are not
|
|
already installed, since that would result in a shrinkwrap that
|
|
wouldn't actually work. Similarly, the command will fail if there are
|
|
extraneous packages (not referenced by <code>package.json</code>), since that would
|
|
indicate that <code>package.json</code> is not correct.</p>
|
|
<p>Starting with npm v4.0.1, <code>devDependencies</code> are included when you run
|
|
<code>npm shrinkwrap</code> and follow the usual rules as to when they're installed.
|
|
As of npm v3.10.8, if you run <code>npm install --only=production</code> or
|
|
<code>npm install --production</code> with a shrinkwrap including your development
|
|
dependencies they won't be installed. Similarly, if the environment
|
|
variable <code>NODE_ENV</code> is <code>production</code> then they won't be installed. If you
|
|
need compatibility with versions of npm prior to v3.10.8 or otherwise
|
|
don't want them in your shrinkwrap you can exclude development
|
|
dependencies with:
|
|
<code>npm shrinkwrap --only=prod</code> or <code>npm shrinkwrap --production</code>.</p>
|
|
<p>If shrinkwrapped package A depends on shrinkwrapped package B, B's
|
|
shrinkwrap will not be used as part of the installation of A. However,
|
|
because A's shrinkwrap is constructed from a valid installation of B
|
|
and recursively specifies all dependencies, the contents of B's
|
|
shrinkwrap will implicitly be included in A's shrinkwrap.</p>
|
|
<h3 id="caveats">Caveats</h3>
|
|
<p>If you wish to lock down the specific bytes included in a package, for
|
|
example to have 100% confidence in being able to reproduce a
|
|
deployment or build, then you ought to check your dependencies into
|
|
source control, or pursue some other mechanism that can verify
|
|
contents rather than versions.</p>
|
|
<h2 id="see-also">SEE ALSO</h2>
|
|
<ul>
|
|
<li><a href="../cli/npm-install.html">npm-install(1)</a></li>
|
|
<li><a href="../cli/npm-run-script.html">npm-run-script(1)</a></li>
|
|
<li><a href="../misc/npm-scripts.html">npm-scripts(7)</a></li>
|
|
<li><a href="../files/package.json.html">package.json(5)</a></li>
|
|
<li><a href="../cli/npm-ls.html">npm-ls(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-shrinkwrap — npm@4.4.1</p>
|
|
|