org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/man/man1/npm-shrinkwrap.1

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