|
|
- npm-package-locks(5) -- An explanation of npm lockfiles
- =====================================================
-
- ## DESCRIPTION
-
- Conceptually, the "input" to npm-install(1) is a package.json(5), while its
- "output" is a fully-formed `node_modules` tree: a representation of the
- dependencies you declared. In an ideal world, npm would work like a pure
- function: the same `package.json` should produce the exact same `node_modules`
- tree, any time. In some cases, this is indeed true. But in many others, npm is
- unable to do this. There are multiple reasons for this:
-
- * different versions of npm (or other package managers) may have been used to install a package, each using slightly different installation algorithms.
-
- * a new version of a direct semver-range package may have been published since the last time your packages were installed, and thus a newer version will be used.
-
- * A dependency of one of your dependencies may have published a new version, which will update even if you used pinned dependency specifiers (`1.2.3` instead of `^1.2.3`)
-
- * The registry you installed from is no longer available, or allows mutation of versions (unlike the primary npm registry), and a different version of a package exists under the same version number now.
-
- As an example, consider package A:
-
- {
- "name": "A",
- "version": "0.1.0",
- "dependencies": {
- "B": "<0.1.0"
- }
- }
-
- package B:
-
- {
- "name": "B",
- "version": "0.0.1",
- "dependencies": {
- "C": "<0.1.0"
- }
- }
-
- and package C:
-
- {
- "name": "C",
- "version": "0.0.1"
- }
-
- If these are the only versions of A, B, and C available in the
- registry, then a normal `npm install A` will install:
-
- A@0.1.0
- `-- B@0.0.1
- `-- C@0.0.1
-
- However, if B@0.0.2 is published, then a fresh `npm install A` will
- install:
-
- A@0.1.0
- `-- B@0.0.2
- `-- C@0.0.1
-
- 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.
-
- To prevent this potential issue, npm uses package-lock.json(5) or, if present,
- npm-shrinkwrap.json(5). These files are called package locks, or lockfiles.
-
- Whenever you run `npm install`, npm generates or updates your package lock,
- which will look something like this:
-
- {
- "name": "A",
- "version": "0.1.0",
- ...metadata fields...
- "dependencies": {
- "B": {
- "version": "0.0.1",
- "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
- "integrity": "sha512-DeAdb33F+"
- "dependencies": {
- "C": {
- "version": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
- }
- }
- }
- }
- }
-
- This file describes an *exact*, and more importantly *reproducible*
- `node_modules` tree. Once it's present, any future installation will base its
- work off this file, instead of recalculating dependency versions off
- package.json(5).
-
- The presence of a package lock changes the installation behavior such that:
-
- 1. The module tree described by the package lock is reproduced. This means
- reproducing the structure described in the file, using the specific files
- referenced in "resolved" if available, falling back to normal package resolution
- using "version" if one isn't.
-
- 2. The tree is walked and any missing dependencies are installed in the usual
- fashion.
-
- If `preshrinkwrap`, `shrinkwrap` or `postshrinkwrap` are in the `scripts`
- property of the `package.json`, they will be executed in order. `preshrinkwrap`
- and `shrinkwrap` are executed before the shrinkwrap, `postshrinkwrap` is
- executed afterwards. These scripts run for both `package-lock.json` and
- `npm-shrinkwrap.json`. For example to run some postprocessing on the generated
- file:
-
- "scripts": {
- "postshrinkwrap": "json -I -e \"this.myMetadata = $MY_APP_METADATA\""
- }
-
-
- ### Using locked packages
-
- Using a locked package is no different than using any package without a package
- lock: any commands that update `node_modules` and/or `package.json`'s
- dependencies will automatically sync the existing lockfile. This includes `npm
- install`, `npm rm`, `npm update`, etc. To prevent this update from happening,
- you can use the `--no-save` option to prevent saving altogether, or
- `--no-shrinkwrap` to allow `package.json` to be updated while leaving
- `package-lock.json` or `npm-shrinkwrap.json` intact.
-
- It is highly recommended you commit the generated package lock to source
- control: this will allow anyone else on your team, your deployments, your
- CI/continuous integration, and anyone else who runs `npm install` in your
- package source to get the exact same dependency tree that you were developing
- on. Additionally, the diffs from these changes are human-readable and will
- inform you of any changes npm has made to your `node_modules`, so you can notice
- if any transitive dependencies were updated, hoisted, etc.
-
- ### Resolving lockfile conflicts
-
- Occasionally, two separate npm install will create package locks that cause
- merge conflicts in source control systems. As of `npm@5.7.0`, these conflicts
- can be resolved by manually fixing any `package.json` conflicts, and then
- running `npm install [--package-lock-only]` again. npm will automatically
- resolve any conflicts for you and write a merged package lock that includes all
- the dependencies from both branches in a reasonable tree. If
- `--package-lock-only` is provided, it will do this without also modifying your
- local `node_modules/`.
-
- To make this process seamless on git, consider installing
- [`npm-merge-driver`](https://npm.im/npm-merge-driver), which will teach git how
- to do this itself without any user interaction. In short: `$ npx
- npm-merge-driver install -g` will let you do this, and even works with
- pre-`npm@5.7.0` versions of npm 5, albeit a bit more noisily. Note that if
- `package.json` itself conflicts, you will have to resolve that by hand and run
- `npm install` manually, even with the merge driver.
-
- ## SEE ALSO
-
- * https://medium.com/@sdboyer/so-you-want-to-write-a-package-manager-4ae9c17d9527
- * package.json(5)
- * package-lock.json(5)
- * npm-shrinkwrap.json(5)
- * npm-shrinkwrap(1)
|