deps/npm/html/doc/cli/npm-shrinkwrap.html

   1 <!doctype html>
   2 <html>
   3   <title>npm-shrinkwrap</title>
   4   <meta http-equiv="content-type" value="text/html;utf-8">
   5   <link rel="stylesheet" type="text/css" href="../../static/style.css">
   6
   7   <body>
   8     <div id="wrapper">
   9 <h1><a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap</a></h1> <p>Lock down dependency versions</p>
  10
  11 <h2 id="SYNOPSIS">SYNOPSIS</h2>
  12
  13 <pre><code>npm shrinkwrap</code></pre>
  14
  15 <h2 id="DESCRIPTION">DESCRIPTION</h2>
  16
  17 <p>This command locks down the versions of a package&#39;s dependencies so
  18 that you can control exactly which versions of each dependency will be
  19 used when your package is installed. The &quot;package.json&quot; file is still
  20 required if you want to use &quot;npm install&quot;.</p>
  21
  22 <p>By default, &quot;npm install&quot; recursively installs the target&#39;s
  23 dependencies (as specified in package.json), choosing the latest
  24 available version that satisfies the dependency&#39;s semver pattern. In
  25 some situations, particularly when shipping software where each change
  26 is tightly managed, it&#39;s desirable to fully specify each version of
  27 each dependency recursively so that subsequent builds and deploys do
  28 not inadvertently pick up newer versions of a dependency that satisfy
  29 the semver pattern. Specifying specific semver patterns in each
  30 dependency&#39;s package.json would facilitate this, but that&#39;s not always
  31 possible or desirable, as when another author owns the npm package.
  32 It&#39;s also possible to check dependencies directly into source control,
  33 but that may be undesirable for other reasons.</p>
  34
  35 <p>As an example, consider package A:</p>
  36
  37 <pre><code>{
  38   &quot;name&quot;: &quot;A&quot;,
  39   &quot;version&quot;: &quot;0.1.0&quot;,
  40   &quot;dependencies&quot;: {
  41     &quot;B&quot;: &quot;&lt;0.1.0&quot;
  42   }
  43 }</code></pre>
  44
  45 <p>package B:</p>
  46
  47 <pre><code>{
  48   &quot;name&quot;: &quot;B&quot;,
  49   &quot;version&quot;: &quot;0.0.1&quot;,
  50   &quot;dependencies&quot;: {
  51     &quot;C&quot;: &quot;&lt;0.1.0&quot;
  52   }
  53 }</code></pre>
  54
  55 <p>and package C:</p>
  56
  57 <pre><code>{
  58   &quot;name&quot;: &quot;C,
  59   &quot;version&quot;: &quot;0.0.1&quot;
  60 }</code></pre>
  61
  62 <p>If these are the only versions of A, B, and C available in the
  63 registry, then a normal &quot;npm install A&quot; will install:</p>
  64
  65 <pre><code>A@0.1.0
  66 `-- B@0.0.1
  67     `-- C@0.0.1</code></pre>
  68
  69 <p>However, if B@0.0.2 is published, then a fresh &quot;npm install A&quot; will
  70 install:</p>
  71
  72 <pre><code>A@0.1.0
  73 `-- B@0.0.2
  74     `-- C@0.0.1</code></pre>
  75
  76 <p>assuming the new version did not modify B&#39;s dependencies. Of course,
  77 the new version of B could include a new version of C and any number
  78 of new dependencies. If such changes are undesirable, the author of A
  79 could specify a dependency on B@0.0.1. However, if A&#39;s author and B&#39;s
  80 author are not the same person, there&#39;s no way for A&#39;s author to say
  81 that he or she does not want to pull in newly published versions of C
  82 when B hasn&#39;t changed at all.</p>
  83
  84 <p>In this case, A&#39;s author can run</p>
  85
  86 <pre><code>npm shrinkwrap</code></pre>
  87
  88 <p>This generates npm-shrinkwrap.json, which will look something like this:</p>
  89
  90 <pre><code>{
  91   &quot;name&quot;: &quot;A&quot;,
  92   &quot;version&quot;: &quot;0.1.0&quot;,
  93   &quot;dependencies&quot;: {
  94     &quot;B&quot;: {
  95       &quot;version&quot;: &quot;0.0.1&quot;,
  96       &quot;dependencies&quot;: {
  97         &quot;C&quot;: {
  98           &quot;version&quot;: &quot;0.1.0&quot;
  99         }
 100       }
 101     }
 102   }
 103 }</code></pre>
 104
 105 <p>The shrinkwrap command has locked down the dependencies based on
 106 what&#39;s currently installed in node_modules.  When &quot;npm install&quot;
 107 installs a package with a npm-shrinkwrap.json file in the package
 108 root, the shrinkwrap file (rather than package.json files) completely
 109 drives the installation of that package and all of its dependencies
 110 (recursively).  So now the author publishes A@0.1.0, and subsequent
 111 installs of this package will use B@0.0.1 and C@0.1.0, regardless the
 112 dependencies and versions listed in A&#39;s, B&#39;s, and C&#39;s package.json
 113 files.</p>
 114
 115 <h3 id="Using-shrinkwrapped-packages">Using shrinkwrapped packages</h3>
 116
 117 <p>Using a shrinkwrapped package is no different than using any other
 118 package: you can &quot;npm install&quot; it by hand, or add a dependency to your
 119 package.json file and &quot;npm install&quot; it.</p>
 120
 121 <h3 id="Building-shrinkwrapped-packages">Building shrinkwrapped packages</h3>
 122
 123 <p>To shrinkwrap an existing package:</p>
 124
 125 <ol><li>Run &quot;npm install&quot; in the package root to install the current
 126 versions of all dependencies.</li><li>Validate that the package works as expected with these versions.</li><li>Run &quot;npm shrinkwrap&quot;, add npm-shrinkwrap.json to git, and publish
 127 your package.</li></ol>
 128
 129 <p>To add or update a dependency in a shrinkwrapped package:</p>
 130
 131 <ol><li>Run &quot;npm install&quot; in the package root to install the current
 132 versions of all dependencies.</li><li>Add or update dependencies. &quot;npm install&quot; each new or updated
 133 package individually and then update package.json.  Note that they
 134 must be explicitly named in order to be installed: running <code>npm
 135 install</code> with no arguments will merely reproduce the existing
 136 shrinkwrap.</li><li>Validate that the package works as expected with the new
 137 dependencies.</li><li>Run &quot;npm shrinkwrap&quot;, commit the new npm-shrinkwrap.json, and
 138 publish your package.</li></ol>
 139
 140 <p>You can use <a href="../cli/npm-outdated.html">npm-outdated(1)</a> to view dependencies with newer versions
 141 available.</p>
 142
 143 <h3 id="Other-Notes">Other Notes</h3>
 144
 145 <p>A shrinkwrap file must be consistent with the package&#39;s package.json
 146 file. &quot;npm shrinkwrap&quot; will fail if required dependencies are not
 147 already installed, since that would result in a shrinkwrap that
 148 wouldn&#39;t actually work. Similarly, the command will fail if there are
 149 extraneous packages (not referenced by package.json), since that would
 150 indicate that package.json is not correct.</p>
 151
 152 <p>Since &quot;npm shrinkwrap&quot; is intended to lock down your dependencies for
 153 production use, <code>devDependencies</code> will not be included unless you
 154 explicitly set the <code>--dev</code> flag when you run <code>npm shrinkwrap</code>.  If
 155 installed <code>devDependencies</code> are excluded, then npm will print a
 156 warning.  If you want them to be installed with your module by
 157 default, please consider adding them to <code>dependencies</code> instead.</p>
 158
 159 <p>If shrinkwrapped package A depends on shrinkwrapped package B, B&#39;s
 160 shrinkwrap will not be used as part of the installation of A. However,
 161 because A&#39;s shrinkwrap is constructed from a valid installation of B
 162 and recursively specifies all dependencies, the contents of B&#39;s
 163 shrinkwrap will implicitly be included in A&#39;s shrinkwrap.</p>
 164
 165 <h3 id="Caveats">Caveats</h3>
 166
 167 <p>Shrinkwrap files only lock down package versions, not actual package
 168 contents.  While discouraged, a package author can republish an
 169 existing version of a package, causing shrinkwrapped packages using
 170 that version to pick up different code than they were before. If you
 171 want to avoid any risk that a byzantine author replaces a package
 172 you&#39;re using with code that breaks your application, you could modify
 173 the shrinkwrap file to use git URL references rather than version
 174 numbers so that npm always fetches all packages from git.</p>
 175
 176 <p>If you wish to lock down the specific bytes included in a package, for
 177 example to have 100% confidence in being able to reproduce a
 178 deployment or build, then you ought to check your dependencies into
 179 source control, or pursue some other mechanism that can verify
 180 contents rather than versions.</p>
 181
 182 <h2 id="SEE-ALSO">SEE ALSO</h2>
 183
 184 <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>
 185 </div>
 186 <p id="footer">npm-shrinkwrap &mdash; npm@1.3.17</p>
 187 <script>
 188 ;(function () {
 189 var wrapper = document.getElementById("wrapper")
 190 var els = Array.prototype.slice.call(wrapper.getElementsByTagName("*"), 0)
 191   .filter(function (el) {
 192     return el.parentNode === wrapper
 193         && el.tagName.match(/H[1-6]/)
 194         && el.id
 195   })
 196 var l = 2
 197   , toc = document.createElement("ul")
 198 toc.innerHTML = els.map(function (el) {
 199   var i = el.tagName.charAt(1)
 200     , out = ""
 201   while (i > l) {
 202     out += "<ul>"
 203     l ++
 204   }
 205   while (i < l) {
 206     out += "</ul>"
 207     l --
 208   }
 209   out += "<li><a href='#" + el.id + "'>" +
 210     ( el.innerText || el.text || el.innerHTML)
 211     + "</a>"
 212   return out
 213 }).join("\n")
 214 toc.id = "toc"
 215 document.body.appendChild(toc)
 216 })()
 217 </script>