w3resource

Package-lock.json


In the previous tutorial we examined the npmrc file. The tutorial you are about to read will explore the pacakage-lock.json configuration file.

The package-lock.json file is a manifestation of the manifest.

Description

The package-lock.json file will be generated automatically for any operations where npm modifies either the node_modules tree, or package.json. it will describe the exact tree that is was generated, such that subsequent installs will be able to generate identical trees, irrespective of intermediate dependency updates.

The aim is to commit this file into source repositories, and will serve various purposes, namely:

  • To describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.
  • To provide a facility for users to "time-travel" to previous states of node_modules without having to commit the directory itself.
  • To facilitate greater visibility of changes in through readable source control diffs.
  • And to optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages.

A key detail of the package-lock.json is that it cannot be published, and it is ignored if it is found in any place other than the toplevel package. This file shares a format with the npm-shrinkwrap.json. The npm-shrinkwrap.json file is essentially the same as the package-lock.json file, but allows you to publish it. Unless you are deploying a CLI tool it is not recommended.

The package-lock.json will be completely ignored if an npm-shrinkwrap.json file is also present in the root of a project.

FILE FORMAT

name

This is the name of the package that the package-lock is for. This must match what is in package.json.

version

This is the version of the package that the package-lock is for. This must match what is in package.json.

lockfileVersion

This is an integer version, that starts at 1 with the version number of this document whose semantics were used when generating this package-lock.json.

packageIntegrity

The packageIntegrity is a subresource integrity value created from the package.json. No preprocessing of the package.json has to be done. Subresource integrity strings may be produced by modules like ssri.

preserveSymlinks

This indicates that the install was done with the environment variable NODE_PRESERVE_SYMLINKS enabled. The installer has to insist that the value of this property match that environment variable.

dependencies

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

version

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

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

integrity

This property specifies a Standard Subresource Integrity for this resource.

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

resolved

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

bundled

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

dev

If this is set to true, then this dependency is either a development dependency ONLY of the top level module or it is a transitive dependency of one. This will be false for dependencies that are both a development dependency of the top level as well as being a transitive dependency of a non-development dependency of the top level.

optional

If this is set to true, then this dependency is either an optional dependency ONLY of the top level module or it is a transitive dependency of one. This will be false for dependencies that are both an optional dependency of the top level as well as being transitive dependency of a non-optional dependency of the top level.

Every optional dependency has to be included even if they are uninstallable on the current platform.

requires

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

dependencies

This is the dependencies of this dependency, it is same as at the top level.

Previous: Npmrc
Next: Npm-package-locks