| <!doctype html> |
| <html> |
| <title>npm-shrinkwrap</title> |
| <meta http-equiv="content-type" value="text/html;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 node_modules. When <code>npm install</code> |
| installs a package with an <code>npm-shrinkwrap.json</code> in the package |
| root, the shrinkwrap file (rather than <code>package.json</code> files) completely |
| drives the installation of that package and all of its dependencies |
| (recursively). So now the author publishes A@0.1.0, and subsequent |
| installs of this package will use B@0.0.1 and C@0.0.1, regardless the |
| dependencies and versions listed in A's, B's, and C's <code>package.json</code> |
| files.</p> |
| <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</code> each new or updated |
| package individually and then update <code>package.json</code>. 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>Run <code>npm shrinkwrap</code>, 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>Since <code>npm shrinkwrap</code> is intended to lock down your dependencies for |
| production use, <code>devDependencies</code> will not be included unless you |
| explicitly set the <code>--dev</code> flag when you run <code>npm shrinkwrap</code>. If |
| installed <code>devDependencies</code> are excluded, then npm will print a |
| warning. If you want them to be installed with your module by |
| default, please consider adding them to <code>dependencies</code> instead.</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="../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@2.15.8</p> |
| |
