foreword

When executing npm install to download the package, we will find that there will be package.json and package-lock.json files in the directory. Just recently, I am also researching some things about the package, and I am a little rusty about some fields in the lock file. Write This article records some knowledge about lock files.

Why do you need a lock file

The lock file only appeared after npm5. package-lock.jsonThe appearance of the file is to solve two main problems in the npm package management process: version management and repeatability .

version management

In npm, package versions are managed using Semantic Versioning ( semver for short).

Each package has a version number, in the form of MAJOR.MINOR.PATCH(can be understood as major version number, minor version number, revision number). MAJOR version numbers indicate incompatible changes, MINOR version numbers indicate backward compatible new features, and PATCH version numbers indicate backward compatible bug fixes.

During development, you may depend on other packages and specify their version ranges (eg ^1.2.0. However, this describes a version range rather than a specific version. When executing npm install, if there is no lock file, the latest version in this version range will be downloaded. If the actual version installed by other developers or the build environment is different from yours may result in inconsistent behavior, or even errors.

The file package-lock.jsonrecords precise dependencies and version numbers to ensure that the same dependency version is installed in different environments, thus solving version management problems.

Regarding the semver version range,

If you write ~0.13.0, you only want to update the patch version: 0.13.1 yes, but 0.14.0 no.

If you write ^0.13.0, you want to get updates that don't change the leftmost non-zero digit: 0.13.1, 0.13.2etc. If you write ^1.13.0, you'll get patches and minor versions: 1.13.1, 1.14.0 etc, until 2.0.0 but not 2.0.0.

If you write 0.13.0, that's the exact version that will be used, and this version of the package will always be downloaded

repeatability

npm's dependency resolution is based on recursion. When you install a package, npm resolves the package's dependencies, installs their dependencies, and so on.

However, since a package's version range can be ambiguous, different resolution processes can result in different dependency versions being installed, introducing uncertainty and inconsistency. package-lock.jsonFiles lock dependency versions during resolution to ensure that the same dependency tree is reproduced in different environments, providing reproducibility .

npm install rules

If there is only one package.json file, running npm i will generate a package-lock.json file based on it. This file is equivalent to a snapshot of this install. It not only records the version of the direct dependency specified by package.json, but also records The version of the indirect dependency.

If the semver-range version of package.json is compatible with the version in package-lock.json (package-lock.json version is within the version range specified by package.json), even if there is a new version in package.json at this time, execute npm i will still download according to package-lock.json.

If the version ranges of package.json are manually modified and are not compatible with the version in package-lock.json, then package-lock.json will be updated to a version compatible with package.json when npm i is executed.

Lock file field analysis

Each dependency in a package-lock.json is mainly composed of the following parts:

"name": Specifies the name of the package package.json, "name"corresponding to the field in the file.
"version": Specifies the version number of the package package.json, "version"corresponding to the field in the file.
"lockfileVersion": package-lock.jsonThe format version number of the file, used to determine the structure and compatibility of the file.
"requires": Whether to use requiresto track module dependencies
"dependencies": An object containing other packages that the project depends on and their version numbers. These dependencies can be direct dependencies or indirect dependencies (depended on by other dependencies). Not all sub-dependencies have a dependencies attribute, only after the dependencies of the sub-dependence conflict with the dependencies in the node_modules currently installed in the root directory, this attribute will be available. This may involve dependency management for nested situations.
"devDependencies": An object listing the packages and their version numbers required during development. These packages are typically used for testing, building, and development tools.
"dev": Indicates whether the module is a development dependency of the top-level module or a transitive dependency of a
"resolved": The installation source of the dependent package (can be understood as the download address)
"integrity": The integrity check value of each package, used to ensure the integrity and security of the downloaded package. It is a unique identifier calculated using a hash algorithm to verify that the contents of the package have not been tampered with.
"subdependencies": An object containing sub-dependencies for each package. This includes the names of sub-dependencies, version numbers, and information about other sub-dependencies.
"dependenciesMeta": An object containing metadata for each package. This metadata can include version range, source, resolution policy, and other information.
"engines": An object that contains the engine that the package needs to use, as well as the version range of the engine, usually only node, npm

When will package-lock.json change

package-lock.json will be automatically generated when npm install.
When we modify the dependency location, such as moving the location of some packages from dependencies to devDependencies, although the package has not changed, it will also affect package-lock.json, and the dev field of some packages will be set to true.
If our installation source registry is different, package-lock.json will also be modified when npm install is executed. Because he will record the address of our dependent package.
When we use npm install to add or npm uninstall to remove packages, package-lock.json will also be modified.
When we update the version of a package, we will also modify package-lock.json.

It should be noted that we should not manually modify the package.json or package-lock.json file, which may cause some unexpected errors. We should use npm cli instead, and npm cli will automatically modify it for us /Update the package.json/package-lock.json file. For example, if we want to download the specified version of the npm package, we should use `npm install [email protected]`

Detailed explanation of package-lock.json file