deps/npm/man/man1/npm-shrinkwrap.1

   1 .\" Generated with Ronnjs 0.3.8
   2 .\" http://github.com/kapouer/ronnjs/
   3 .
   4 .TH "NPM\-SHRINKWRAP" "1" "November 2013" "" ""
   5 .
   6 .SH "NAME"
   7 \fBnpm-shrinkwrap\fR \-\- Lock down dependency versions
   8 .
   9 .SH "SYNOPSIS"
  10 .
  11 .nf
  12 npm shrinkwrap
  13 .
  14 .fi
  15 .
  16 .SH "DESCRIPTION"
  17 This command locks down the versions of a package\'s dependencies so
  18 that you can control exactly which versions of each dependency will be
  19 used when your package is installed\. The "package\.json" file is still
  20 required if you want to use "npm install"\.
  21 .
  22 .P
  23 By default, "npm install" recursively installs the target\'s
  24 dependencies (as specified in package\.json), choosing the latest
  25 available version that satisfies the dependency\'s semver pattern\. In
  26 some situations, particularly when shipping software where each change
  27 is tightly managed, it\'s desirable to fully specify each version of
  28 each dependency recursively so that subsequent builds and deploys do
  29 not inadvertently pick up newer versions of a dependency that satisfy
  30 the semver pattern\. Specifying specific semver patterns in each
  31 dependency\'s package\.json would facilitate this, but that\'s not always
  32 possible or desirable, as when another author owns the npm package\.
  33 It\'s also possible to check dependencies directly into source control,
  34 but that may be undesirable for other reasons\.
  35 .
  36 .P
  37 As an example, consider package A:
  38 .
  39 .IP "" 4
  40 .
  41 .nf
  42 {
  43   "name": "A",
  44   "version": "0\.1\.0",
  45   "dependencies": {
  46     "B": "<0\.1\.0"
  47   }
  48 }
  49 .
  50 .fi
  51 .
  52 .IP "" 0
  53 .
  54 .P
  55 package B:
  56 .
  57 .IP "" 4
  58 .
  59 .nf
  60 {
  61   "name": "B",
  62   "version": "0\.0\.1",
  63   "dependencies": {
  64     "C": "<0\.1\.0"
  65   }
  66 }
  67 .
  68 .fi
  69 .
  70 .IP "" 0
  71 .
  72 .P
  73 and package C:
  74 .
  75 .IP "" 4
  76 .
  77 .nf
  78 {
  79   "name": "C,
  80   "version": "0\.0\.1"
  81 }
  82 .
  83 .fi
  84 .
  85 .IP "" 0
  86 .
  87 .P
  88 If these are the only versions of A, B, and C available in the
  89 registry, then a normal "npm install A" will install:
  90 .
  91 .IP "" 4
  92 .
  93 .nf
  94 A@0\.1\.0
  95 `\-\- B@0\.0\.1
  96     `\-\- C@0\.0\.1
  97 .
  98 .fi
  99 .
 100 .IP "" 0
 101 .
 102 .P
 103 However, if B@0\.0\.2 is published, then a fresh "npm install A" will
 104 install:
 105 .
 106 .IP "" 4
 107 .
 108 .nf
 109 A@0\.1\.0
 110 `\-\- B@0\.0\.2
 111     `\-\- C@0\.0\.1
 112 .
 113 .fi
 114 .
 115 .IP "" 0
 116 .
 117 .P
 118 assuming the new version did not modify B\'s dependencies\. Of course,
 119 the new version of B could include a new version of C and any number
 120 of new dependencies\. If such changes are undesirable, the author of A
 121 could specify a dependency on B@0\.0\.1\. However, if A\'s author and B\'s
 122 author are not the same person, there\'s no way for A\'s author to say
 123 that he or she does not want to pull in newly published versions of C
 124 when B hasn\'t changed at all\.
 125 .
 126 .P
 127 In this case, A\'s author can run
 128 .
 129 .IP "" 4
 130 .
 131 .nf
 132 npm shrinkwrap
 133 .
 134 .fi
 135 .
 136 .IP "" 0
 137 .
 138 .P
 139 This generates npm\-shrinkwrap\.json, which will look something like this:
 140 .
 141 .IP "" 4
 142 .
 143 .nf
 144 {
 145   "name": "A",
 146   "version": "0\.1\.0",
 147   "dependencies": {
 148     "B": {
 149       "version": "0\.0\.1",
 150       "dependencies": {
 151         "C": {
 152           "version": "0\.1\.0"
 153         }
 154       }
 155     }
 156   }
 157 }
 158 .
 159 .fi
 160 .
 161 .IP "" 0
 162 .
 163 .P
 164 The shrinkwrap command has locked down the dependencies based on
 165 what\'s currently installed in node_modules\.  When "npm install"
 166 installs a package with a npm\-shrinkwrap\.json file in the package
 167 root, the shrinkwrap file (rather than package\.json files) completely
 168 drives the installation of that package and all of its dependencies
 169 (recursively)\.  So now the author publishes A@0\.1\.0, and subsequent
 170 installs of this package will use B@0\.0\.1 and C@0\.1\.0, regardless the
 171 dependencies and versions listed in A\'s, B\'s, and C\'s package\.json
 172 files\.
 173 .
 174 .SS "Using shrinkwrapped packages"
 175 Using a shrinkwrapped package is no different than using any other
 176 package: you can "npm install" it by hand, or add a dependency to your
 177 package\.json file and "npm install" it\.
 178 .
 179 .SS "Building shrinkwrapped packages"
 180 To shrinkwrap an existing package:
 181 .
 182 .IP "1" 4
 183 Run "npm install" in the package root to install the current
 184 versions of all dependencies\.
 185 .
 186 .IP "2" 4
 187 Validate that the package works as expected with these versions\.
 188 .
 189 .IP "3" 4
 190 Run "npm shrinkwrap", add npm\-shrinkwrap\.json to git, and publish
 191 your package\.
 192 .
 193 .IP "" 0
 194 .
 195 .P
 196 To add or update a dependency in a shrinkwrapped package:
 197 .
 198 .IP "1" 4
 199 Run "npm install" in the package root to install the current
 200 versions of all dependencies\.
 201 .
 202 .IP "2" 4
 203 Add or update dependencies\. "npm install" each new or updated
 204 package individually and then update package\.json\.  Note that they
 205 must be explicitly named in order to be installed: running \fBnpm
 206 install\fR with no arguments will merely reproduce the existing
 207 shrinkwrap\.
 208 .
 209 .IP "3" 4
 210 Validate that the package works as expected with the new
 211 dependencies\.
 212 .
 213 .IP "4" 4
 214 Run "npm shrinkwrap", commit the new npm\-shrinkwrap\.json, and
 215 publish your package\.
 216 .
 217 .IP "" 0
 218 .
 219 .P
 220 npm help You can use npm\-outdated to view dependencies with newer versions
 221 available\.
 222 .
 223 .SS "Other Notes"
 224 A shrinkwrap file must be consistent with the package\'s package\.json
 225 file\. "npm shrinkwrap" will fail if required dependencies are not
 226 already installed, since that would result in a shrinkwrap that
 227 wouldn\'t actually work\. Similarly, the command will fail if there are
 228 extraneous packages (not referenced by package\.json), since that would
 229 indicate that package\.json is not correct\.
 230 .
 231 .P
 232 Since "npm shrinkwrap" is intended to lock down your dependencies for
 233 production use, \fBdevDependencies\fR will not be included unless you
 234 explicitly set the \fB\-\-dev\fR flag when you run \fBnpm shrinkwrap\fR\|\.  If
 235 installed \fBdevDependencies\fR are excluded, then npm will print a
 236 warning\.  If you want them to be installed with your module by
 237 default, please consider adding them to \fBdependencies\fR instead\.
 238 .
 239 .P
 240 If shrinkwrapped package A depends on shrinkwrapped package B, B\'s
 241 shrinkwrap will not be used as part of the installation of A\. However,
 242 because A\'s shrinkwrap is constructed from a valid installation of B
 243 and recursively specifies all dependencies, the contents of B\'s
 244 shrinkwrap will implicitly be included in A\'s shrinkwrap\.
 245 .
 246 .SS "Caveats"
 247 Shrinkwrap files only lock down package versions, not actual package
 248 contents\.  While discouraged, a package author can republish an
 249 existing version of a package, causing shrinkwrapped packages using
 250 that version to pick up different code than they were before\. If you
 251 want to avoid any risk that a byzantine author replaces a package
 252 you\'re using with code that breaks your application, you could modify
 253 the shrinkwrap file to use git URL references rather than version
 254 numbers so that npm always fetches all packages from git\.
 255 .
 256 .P
 257 If you wish to lock down the specific bytes included in a package, for
 258 example to have 100% confidence in being able to reproduce a
 259 deployment or build, then you ought to check your dependencies into
 260 source control, or pursue some other mechanism that can verify
 261 contents rather than versions\.
 262 .
 263 .SH "SEE ALSO"
 264 .
 265 .IP "\(bu" 4
 266 npm help install
 267 .
 268 .IP "\(bu" 4
 269 npm help  package\.json
 270 .
 271 .IP "\(bu" 4
 272 npm help ls
 273 .
 274 .IP "" 0
 275