org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/doc/cli/npm-shrinkwrap.md

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