Provided by: npm_8.5.1~ds-1_all bug

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
       intermediate dependency updates.

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

       • Describe  a single representation of a dependency tree such that teammates, deployments,
         and continuous integration are guaranteed to install exactly the same dependencies.

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

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

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

       • 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 publication 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 package-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/.package-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:

       • All package folders it references exist in the node_modules hierarchy.

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

       • 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 unaffected.  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 generally 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 lockfileVersion: 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 document 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 lockfileVersion: 2.

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

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

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

       • 3: The lockfile version used by npm v7,  without  backwards  compatibility  affordances.
         This is used for the hidden lockfile at node_modules/.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:

       • version: The version found in package.json

       • 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".

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

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

       • 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.)

       • inBundle: A flag to indicate that the package is a bundled dependency.

       • hasInstallScript: A flag to indicate that the package  has  a  preinstall,  install,  or
         postinstall script.

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

       • 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:

       • version:  a  specifier that varies depending on the nature of the package, and is 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:     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 dependencies, this is the commit sha.

       • 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".

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

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

       • 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: The dependencies of this dependency, exactly as at the top level.

   See also
       • npm help shrinkwrap

       • npm help npm-shrinkwrap.json

       • npm help package.json

       • npm help install

                                          undefined NaN                      PACKAGE-LOCK.JSON(5)