Go to main content

man pages section 5: File Formats

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

package-lock-json (5)

Name

package-lock-json - A manifestation of the manifest Description package-lock.json is automatically generated for any operations where npm modifies either the node_modules tree, or package.json. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermedi- ate dependency updates. This file is intended to be committed into source repositories, and serves various purposes: o Describe a single representation of a dependency tree such that team- mates, deployments, and continuous integration are guaranteed to install exactly the same dependencies. o Provide a facility for users to "time-travel" to previous states of node_modules without having to commit the directory itself. o Facilitate greater visibility of tree changes through readable source control diffs. o Optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages. o As of npm v7, lockfiles include enough information to gain a complete picture of the package tree, reducing the need to read package.json files, and allowing for significant performance improvements. package-lock.json vs npm-shrinkwrap.json Both of these files have the same format, and perform similar functions in the root of a project. The difference is that package-lock.json cannot be published, and it will be ignored if found in any place other than the root project. In contrast, npm help npm-shrinkwrap.json allows publication, and defines the dependency tree from the point encountered. This is not recommended unless deploying a CLI tool or otherwise using the publica- tion process for producing production packages. If both package-lock.json and npm-shrinkwrap.json are present in the root of a project, npm-shrinkwrap.json will take precedence and pack- age-lock.json will be ignored. Hidden Lockfiles In order to avoid processing the node_modules folder repeatedly, npm as of v7 uses a "hidden" lockfile present in node_modules/.pack- age-lock.json. This contains information about the tree, and is used in lieu of reading the entire node_modules hierarchy provided that the following conditions are met: o All package folders it references exist in the node_modules hierar- chy. o No package folders exist in the node_modules hierarchy that are not listed in the lockfile. o The modified time of the file is at least as recent as all of the package folders it references. That is, the hidden lockfile will only be relevant if it was created as part of the most recent update to the package tree. If another CLI mutates the tree in any way, this will be detected, and the hidden lockfile will be ignored. Note that it is possible to manually change the contents of a package in such a way that the modified time of the package folder is unaf- fected. For example, if you add a file to node_modules/foo/lib/bar.js, then the modified time on node_modules/foo will not reflect this change. If you are manually editing files in node_modules, it is gen- erally best to delete the file at node_modules/.package-lock.json. As the hidden lockfile is ignored by older npm versions, it does not contain the backwards compatibility affordances present in "normal" lockfiles. That is, it is lockfileVersion: 3, rather than lockfileVer- sion: 2. Handling Old Lockfiles When npm detects a lockfile from npm v6 or before during the package installation process, it is automatically updated to fetch missing information from either the node_modules tree or (in the case of empty node_modules trees or very old lockfile formats) the npm registry. File Format name The name of the package this is a package-lock for. This will match what's in package.json. version The version of the package this is a package-lock for. This will match what's in package.json. lockfileVersion An integer version, starting at 1 with the version number of this docu- ment whose semantics were used when generating this package-lock.json. Note that the file format changed significantly in npm v7 to track information that would have otherwise required looking in node_modules or the npm registry. Lockfiles generated by npm v7 will contain lock- fileVersion: 2. o No version provided: an "ancient" shrinkwrap file from a version of npm prior to npm v5. o 1: The lockfile version used by npm v5 and v6. o 2: The lockfile version used by npm v7, which is backwards compatible to v1 lockfiles. o 3: The lockfile version used by npm v7, without backwards compatibil- ity affordances. This is used for the hidden lockfile at node_mod- ules/.package-lock.json, and will likely be used in a future version of npm, once support for npm v6 is no longer relevant. npm will always attempt to get whatever data it can out of a lockfile, even if it is not a version that it was designed to support. packages This is an object that maps package locations to an object containing the information about that package. The root project is typically listed with a key of "", and all other packages are listed with their relative paths from the root project folder. Package descriptors have the following fields: o version: The version found in package.json o resolved: The place where the package was actually resolved from. In the case of packages fetched from the registry, this will be a url to a tarball. In the case of git dependencies, this will be the full git url with commit sha. In the case of link dependencies, this will be the location of the link target. registry.npmjs.org is a magic value meaning "the currently configured registry". o integrity: A sha512 or sha1 Standard Subresource Integrity https://w3c.github.io/webappsec/specs/subresourceintegrity/ string for the artifact that was unpacked in this location. o link: A flag to indicate that this is a symbolic link. If this is present, no other fields are specified, since the link target will also be included in the lockfile. o dev, optional, devOptional: If the package is strictly part of the devDependencies tree, then dev will be true. If it is strictly part of the optionalDependencies tree, then optional will be set. If it is both a dev dependency and an optional dependency of a non-dev dependency, then devOptional will be set. (An optional dependency of a dev dependency will have both dev and optional set.) o inBundle: A flag to indicate that the package is a bundled depen- dency. o hasInstallScript: A flag to indicate that the package has a prein- stall, install, or postinstall script. o hasShrinkwrap: A flag to indicate that the package has an npm-shrinkwrap.json file. o bin, license, engines, dependencies, optionalDependencies: fields from package.json dependencies Legacy data for supporting versions of npm that use lockfileVersion: 1. This is a mapping of package names to dependency objects. Because the object structure is strictly hierarchical, symbolic link dependencies are somewhat challenging to represent in some cases. npm v7 ignores this section entirely if a packages section is present, but does keep it up to date in order to support switching between npm v6 and npm v7. Dependency objects have the following fields: o version: a specifier that varies depending on the nature of the pack- age, and is usable in fetching a new copy of it. o bundled dependencies: Regardless of source, this is a version num- ber that is purely for informational purposes. o registry sources: This is a version number. (eg, 1.2.3) o git sources: This is a git specifier with resolved committish. (eg, git+https://exam- ple.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e) o http tarball sources: This is the URL of the tarball. (eg, https://example.com/example-1.3.0.tgz) o local tarball sources: This is the file URL of the tarball. (eg file:///opt/storage/example-1.3.0.tgz) o local link sources: This is the file URL of the link. (eg file:libs/our-module) o integrity: A sha512 or sha1 Standard Subresource Integrity https://w3c.github.io/webappsec/specs/subresourceintegrity/ string for the artifact that was unpacked in this location. For git depen- dencies, this is the commit sha. o resolved: 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. registry.npmjs.org is a magic value meaning "the currently configured registry". o bundled: 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. o 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 depen- dency of the top level. o optional: If true then this dependency is either an optional depen- dency 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 depen- dency of the top level. o 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. o dependencies: The dependencies of this dependency, exactly as at the top level. See also o npm help shrinkwrap o npm help npm-shrinkwrap.json o npm help package.json o npm help install

Synopsis

Please see following description for synopsis

Description

PACKAGE-LOCK.JSON(5)                                      PACKAGE-LOCK.JSON(5)



NAME
       package-lock.json - A manifestation of the manifest

   Description
       package-lock.json  is  automatically generated for any operations where
       npm  modifies  either  the  node_modules  tree,  or  package.json.   It
       describes  the  exact  tree  that  was  generated, such that subsequent
       installs are able to generate identical trees, regardless of intermedi-
       ate dependency updates.

       This  file  is  intended  to be committed into source repositories, and
       serves various purposes:

       o Describe a single representation of a dependency tree such that team-
         mates,  deployments,  and  continuous  integration  are guaranteed to
         install exactly the same dependencies.

       o Provide a facility for users to "time-travel" to previous  states  of
         node_modules without having to commit the directory itself.

       o Facilitate greater visibility of tree changes through readable source
         control diffs.

       o Optimize the installation process by allowing npm  to  skip  repeated
         metadata resolutions for previously-installed packages.

       o As of npm v7, lockfiles include enough information to gain a complete
         picture of the package tree, reducing the need to  read  package.json
         files, and allowing for significant performance improvements.


   package-lock.json vs npm-shrinkwrap.json
       Both of these files have the same format, and perform similar functions
       in the root of a project.

       The difference is that package-lock.json cannot be  published,  and  it
       will be ignored if found in any place other than the root project.

       In  contrast,  npm  help  npm-shrinkwrap.json  allows  publication, and
       defines the dependency tree from the point encountered.   This  is  not
       recommended unless deploying a CLI tool or otherwise using the publica-
       tion process for producing production packages.

       If both package-lock.json and npm-shrinkwrap.json are  present  in  the
       root  of  a project, npm-shrinkwrap.json will take precedence and pack-
       age-lock.json will be ignored.

   Hidden Lockfiles
       In order to avoid processing the node_modules folder repeatedly, npm as
       of   v7   uses  a  "hidden"  lockfile  present  in  node_modules/.pack-
       age-lock.json.  This contains information about the tree, and  is  used
       in  lieu of reading the entire node_modules hierarchy provided that the
       following conditions are met:

       o All package folders it references exist in the  node_modules  hierar-
         chy.

       o No  package  folders exist in the node_modules hierarchy that are not
         listed in the lockfile.

       o The modified time of the file is at least as recent  as  all  of  the
         package folders it references.


       That is, the hidden lockfile will only be relevant if it was created as
       part of the most recent update to the package  tree.   If  another  CLI
       mutates  the  tree  in  any  way, this will be detected, and the hidden
       lockfile will be ignored.

       Note that it is possible to manually change the contents of  a  package
       in  such  a  way  that the modified time of the package folder is unaf-
       fected.  For example, if you add a file to node_modules/foo/lib/bar.js,
       then  the  modified  time  on  node_modules/foo  will  not reflect this
       change.  If you are manually editing files in node_modules, it is  gen-
       erally best to delete the file at node_modules/.package-lock.json.

       As  the  hidden  lockfile is ignored by older npm versions, it does not
       contain the backwards compatibility  affordances  present  in  "normal"
       lockfiles.  That is, it is lockfileVersion: 3, rather than lockfileVer-
       sion: 2.

   Handling Old Lockfiles
       When npm detects a lockfile from npm v6 or before  during  the  package
       installation  process,  it  is  automatically  updated to fetch missing
       information from either the node_modules tree or (in the case of  empty
       node_modules trees or very old lockfile formats) the npm registry.

   File Format
   name
       The  name  of  the  package this is a package-lock for. This will match
       what's in package.json.

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

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

       Note that the file format changed significantly  in  npm  v7  to  track
       information  that would have otherwise required looking in node_modules
       or the npm registry.  Lockfiles generated by npm v7 will contain  lock-
       fileVersion: 2.

       o No  version  provided: an "ancient" shrinkwrap file from a version of
         npm prior to npm v5.

       o 1: The lockfile version used by npm v5 and v6.

       o 2: The lockfile version used by npm v7, which is backwards compatible
         to v1 lockfiles.

       o 3: The lockfile version used by npm v7, without backwards compatibil-
         ity affordances.  This is used for the hidden lockfile  at  node_mod-
         ules/.package-lock.json,  and will likely be used in a future version
         of npm, once support for npm v6 is no longer relevant.


       npm will always attempt to get whatever data it can out of a  lockfile,
       even if it is not a version that it was designed to support.

   packages
       This  is  an object that maps package locations to an object containing
       the information about that package.

       The root project is typically listed with a key of "",  and  all  other
       packages  are  listed  with  their relative paths from the root project
       folder.

       Package descriptors have the following fields:

       o version: The version found in package.json

       o resolved: The place where the package was actually resolved from.  In
         the case of packages fetched from the registry, this will be a url to
         a tarball.  In the case of git dependencies, this will  be  the  full
         git url with commit sha.  In the case of link dependencies, this will
         be the location of the link target.  registry.npmjs.org  is  a  magic
         value meaning "the currently configured registry".

       o integrity:   A   sha512   or   sha1  Standard  Subresource  Integrity
         https://w3c.github.io/webappsec/specs/subresourceintegrity/    string
         for the artifact that was unpacked in this location.

       o link:  A  flag  to indicate that this is a symbolic link.  If this is
         present, no other fields are specified, since the  link  target  will
         also be included in the lockfile.

       o dev,  optional,  devOptional:  If the package is strictly part of the
         devDependencies tree, then dev will be true.  If it is strictly  part
         of  the  optionalDependencies tree, then optional will be set.  If it
         is both a dev dependency and an  optional  dependency  of  a  non-dev
         dependency, then devOptional will be set.  (An optional dependency of
         a dev dependency will have both dev and optional set.)

       o inBundle: A flag to indicate that the package  is  a  bundled  depen-
         dency.

       o hasInstallScript:  A  flag  to indicate that the package has a prein-
         stall, install, or postinstall script.

       o hasShrinkwrap:  A  flag  to  indicate  that  the   package   has   an
         npm-shrinkwrap.json file.

       o bin,  license,  engines,  dependencies,  optionalDependencies: fields
         from package.json


   dependencies
       Legacy data for supporting versions of npm that use lockfileVersion: 1.
       This  is a mapping of package names to dependency objects.  Because the
       object structure is strictly hierarchical, symbolic  link  dependencies
       are somewhat challenging to represent in some cases.

       npm  v7 ignores this section entirely if a packages section is present,
       but does keep it up to date in order to support switching  between  npm
       v6 and npm v7.

       Dependency objects have the following fields:

       o version: a specifier that varies depending on the nature of the pack-
         age, and is usable in fetching a new copy of it.

         o bundled dependencies: Regardless of source, this is a version  num-
           ber that is purely for informational purposes.

         o registry sources: This is a version number. (eg, 1.2.3)

         o git sources: This is a git specifier with resolved committish. (eg,
           git+https://exam-
           ple.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e)

         o http  tarball  sources:  This  is  the  URL  of  the  tarball. (eg,
           https://example.com/example-1.3.0.tgz)

         o local tarball sources: This is the file URL  of  the  tarball.  (eg
           file:///opt/storage/example-1.3.0.tgz)

         o local  link  sources:  This  is  the  file  URL  of  the  link. (eg
           file:libs/our-module)


       o integrity:  A  sha512  or   sha1   Standard   Subresource   Integrity
         https://w3c.github.io/webappsec/specs/subresourceintegrity/    string
         for the artifact that was unpacked in this location.  For git  depen-
         dencies, this is the commit sha.

       o resolved:  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. registry.npmjs.org is a
         magic value meaning "the currently configured registry".

       o bundled:  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.

       o 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 depen-
         dency of the top level.

       o optional:  If  true then this dependency is either an optional depen-
         dency 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 depen-
         dency of the top level.

       o 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.

       o dependencies: The dependencies of this dependency, exactly as at  the
         top level.


   See also
       o npm help shrinkwrap

       o npm help npm-shrinkwrap.json

       o npm help package.json

       o npm help install




ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | runtime/nodejs/nodejs-16 |
       +---------------+--------------------------+
       |Stability      | Pass-thru volatile       |
       +---------------+--------------------------+

NOTES
       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source    was   downloaded   from    https://github.com/nodejs/node/ar-
       chive/v16.11.1.zip.

       Further information about this software can be found on the open source
       community website at https://github.com/nodejs/node.



                                 October 2021             PACKAGE-LOCK.JSON(5)