# package-lock and npm-shrinkwrap

`npm` can have one of two different lock files:

* `package-lock.json`, which is ordinarily always present and is never published.
* `npm-shrinkwrap.json`, which is created with `npm shrinkwrap` and usually published.

You can only have one of them and in the event that you have both,
`npm-shrinkwrap.json` takes precedence.  The files are exactly the same
format and in fact all the `npm shrinkwrap` command does is rename your
`package-lock.json`.

Through the rest of this document we will refer to the package-lock and
`package-lock.json` but everything also applies to `npm-shrinkwrap.json`.

## File Format

### name

The name of the package this is a package-lock for. This must match what's in `package.json`.

### version

The version of the package this is a package-lock for. This must match what's in `package.json`.

### lockfileVersion *(new)*

An integer version, starting at `1` with the version number of this document
whose semantics were used when generating this `package-lock.json`.

### preserveSymlinks *(new)*

Indicates that the install was done with the environment variable
`NODE_PRESERVE_SYMLINKS` enabled. The installer should insist that the value of this
property match that environment variable.

### dependencies

These are the modules installed in the `node_modules`.  Some of these are
dependencies some of these are transitive dependencies (that is,
dependencies of our dependencies).

This is a mapping of package name to dependency object.  Dependency objects have the
following properties:

#### version *(changed)*

This is a specifier that uniquely identifies this package and should be
usable in fetching a new copy of it.

* bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.
* registry sources: This is a version number. (eg, `1.2.3`)
* git sources: This is a git specifier with resolved committish. (eg, `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)
* http tarball sources: This is the URL of the tarball. (eg, `https://example.com/example-1.3.0.tgz`)
* local tarball sources: This is the file URL of the tarball. (eg `file:///opt/storage/example-1.3.0.tgz`)
* local link sources: This is the file URL of the link. (eg `file:libs/our-module`)

#### integrity *(new)*

This is a [Standard Subresource
Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) for
this resource.

* For bundled dependencies this is not included, regardless of source.
* For registry sources, this is the `integrity` that the registry provided, or if one wasn't provided the SHA1 in `shasum`.
* For git sources this is the specific commit hash we cloned from.
* For remote tarball sources this is an integrity based on a SHA512 of
  the file.
* For local tarball sources: This is an integrity field based on the SHA512 of the file.

#### resolved

* For bundled dependencies this is not included, regardless of source.
* For registry sources this is path of the tarball relative to the registry
  URL.  If the tarball URL isn't on the same server as the registry URL then
  this is a complete URL.

#### link *(new)*

If this module was symlinked in development but had semver in the
`package.json` then this is the relative path of that link.

Discussion of the semantics of this will go in the symlinks RFC.

Implementation note: To be implemented post npm@5.

#### bundled *(new)*

If true, this is the bundled dependency and will be installed by the parent
module.  When installing, this module will be extracted from the parent
module during the extract phase, not installed as a separate dependency.

#### dev

If true then this dependency is either a development dependency ONLY of the
top level module or a transitive dependency of one.  This is false for
dependencies that are both a development dependency of the top level and a
transitive dependency of a non-development dependency of the top level.

#### optional

If true then this dependency is either an optional dependency ONLY of the
top level module or a transitive dependency of one.  This is false for
dependencies that are both an optional dependency of the top level and a
transitive dependency of a non-optional dependency of the top level.

All optional dependencies should be included even if they're uninstallable
on the current platform.

#### from

This is a record of what specifier was used to originally install this
package.  This should be used only for git dependencies.

#### requires

This is a mapping of module name to version.  This is a list of everything
this module requires, regardless of where it will be installed.  The version
should match via normal matching rules a dependency either in our
`dependencies` or in a level higher than us.

#### dependencies

Exactly like `dependencies` at the top level, this is a list of modules to
install in the `node_modules` of this module.

## Generating

### `npm init`

If neither a `package-lock.json` nor an `npm-shrinkwrap.json` exist then
`npm init` will create a `package-lock.json`.  This is functionally
equivalent to running `npm shrinkwrap` after the current init completes and
renaming the result to `package-lock.json`.

### `npm install --save`

If either an `npm-shrinkwrap.json` or a `package-lock.json` exists then it
will be updated.

If neither exist then a `package-lock.json` should be generated.

If a `package.json` does not exist, it should be generated.  The generated
`package.json` should be empty, as in:

```
{
   "dependencies": {
   }
}
```

If the user wants to get a default package name/version added they can run `npm init`.

### `npm shrinkwrap`

If a `package-lock.json` exists, rename it to `npm-shrinkwrap.json`.
Refresh the data from the installer's ideal tree.

The top level `name` and `version` come from the `package.json`.  It is an
error if either are missing or invalid.

#### dependencies.dev

This is `true` if this dependency is ONLY installed to fulfill either a top
level development dependency, or one of its transitive dependencies.

Given:
```
B (Dev) → C
```

Then both B and C would be `dev: true`.

Given:
```
A → B → C
B (Dev) -> C
```

Then all dependencies would be `dev: false`.

#### dependencies.optional

This is `true` if this dependency is ONLY ever either an optional dependency
or a transitive dependency of optional dependencies.

Given:
```
A (Opt) → B → C
```

Then all three of A, B and C would be flagged as optional.

Given:
```
A (Opt) → B → C
D → C
```

Then A and B would be flagged as optional, but C would not be.

Given:
```
A (Opt) → B → C
D → A
```

Then none would be flagged as optional.

## Installing

If the `packageIntegrity` in the `package-lock.json` differs from the one
computed from the `package.json` then places where the `package.json` is
incompatible with the `package-lock.json` a new module should be installed.
That is, while the `package-lock.json` ordinarily defines the state of your
project, if your `package.json` is edited independently it will take
precedence.

The `package-lock.json` describes the exact tree that `npm` should create.
Any deviation between the `package.json` and the shrinkwrap/lock should
result in a warning be issued.  This includes:

* Modules in `package.json` but missing from the `package-lock.json`
* Modules in the `package-lock.json` but missing from the `package.json`.
* Modules in `package.json` whose specifiers don't match the version in `package-lock.json`.

Warn if the `lockfileVersion` in the `package-lock.json` is for a different
major version than we implement.

Module resolution from package-lock data works as such:

* If install was run with `--resolve-links` and a dependency has a `link`
  property then a symlink is made using that.  If the version of the
  destination can not be matched to the package-lock and/or the package.json
  then a warning will be issued.

* Otherwise, if a `integrity` is available then we try to install it from the cache using it.

If `integrity` is unavailable or we are unable to locate a module from the `integrity` then:

* If `lockfileVersion` is set:
  * Install using the value of `version` and validate the result against the
    `integrity`.
* Otherwise, try these in turn and validate the result against the `integrity`:
  * `resolved`, then `from`, then `version.
  * `from` can be either `package@specifier` or just `specifier`.

Regardless of how the module is installed the metadata in the installed
module should be identical to what it would have been if the module were
installed w/o a package-lock.

## Implied Changes To Other Commands

### `npm rm --save`

Currently if you ask to remove a package that's both a direct and a
transitive dependency, we'll remove the package from `node_modules` even if
this results in a broken tree.  This was chosen at the time because we felt
that users would expect `npm rm pkgname` to be equivalent of
`rm -rf node_modules/pkgname`.

As you are no longer going to be allowed to put your `node_modules` in a
state that's not a valid package-lock, this means this behavior is no longer
valid.  Instead we should follow normal rules, removing it from the
dependencies for the top level but only removing the module on disk if
nothing requires it any more.

## Additional fields / Adding new fields

Installers should ignore any field they aren't aware of.  It's not an error
to have additional properties in the package-lock or lock file.

Installers that want to add new fields should either have one added via RFC
in the npm issue tracker and an accompanying documentation PR, or should prefix
it with the name of their project.