1PACKAGE-LOCK.JSON(5) PACKAGE-LOCK.JSON(5)
2
6 package-lock.json - A manifestation of the manifest
7 Description
9 package-lock.json is automatically generated for any operations where
10 npm modifies either the node_modules tree, or package.json. It de‐
11 scribes the exact tree that was generated, such that subsequent in‐
12 stalls are able to generate identical trees, regardless of intermediate
13 dependency updates.
14 This file is intended to be committed into source repositories, and
16 serves various purposes:
17 • Describe a single representation of a dependency tree such that team‐
19 mates, deployments, and continuous integration are guaranteed to in‐
20 stall exactly the same dependencies.
21 • Provide a facility for users to "time-travel" to previous states of
23 node_modules without having to commit the directory itself.
24 • To facilitate greater visibility of tree changes through readable
26 source control diffs.
27 • And optimize the installation process by allowing npm to skip re‐
29 peated metadata resolutions for previously-installed packages.
30 One key detail about package-lock.json is that it cannot be published,
33 and it will be ignored if found in any place other than the toplevel
34 package. It shares a format with npm help npm-shrinkwrap.json, which is
35 essentially the same file, but allows publication. This is not recom‐
36 mended unless deploying a CLI tool or otherwise using the publication
37 process for producing production packages.
38 If both package-lock.json and npm-shrinkwrap.json are present in the
40 root of a package, package-lock.json will be completely ignored.
41 File Format
43 name
44 The name of the package this is a package-lock for. This must match
45 what's in package.json.
46 version
48 The version of the package this is a package-lock for. This must match
49 what's in package.json.
50 lockfileVersion
52 An integer version, starting at 1 with the version number of this docu‐
53 ment whose semantics were used when generating this package-lock.json.
54 packageIntegrity
56 This is a subresource integrity https://w3c.github.io/we‐
57 bappsec/specs/subresourceintegrity/ value created from the pack‐
58 age.json. No preprocessing of the package.json should be done. Subre‐
59 source integrity strings can be produced by modules like ssri
60 https://www.npmjs.com/package/ssri.
61 preserveSymlinks
63 Indicates that the install was done with the environment variable
64 NODE_PRESERVE_SYMLINKS enabled. The installer should insist that the
65 value of this property match that environment variable.
66 dependencies
68 A mapping of package name to dependency object. Dependency objects
69 have the following properties:
70 version
72 This is a specifier that uniquely identifies this package and should be
73 usable in fetching a new copy of it.
74 • bundled dependencies: Regardless of source, this is a version number
76 that is purely for informational purposes.
77 • registry sources: This is a version number. (eg, 1.2.3)
79 • git sources: This is a git specifier with resolved committish. (eg,
81 git+https://exam‐
82 ple.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e)
83 • http tarball sources: This is the URL of the tarball. (eg,
85 https://example.com/example-1.3.0.tgz)
86 • local tarball sources: This is the file URL of the tarball. (eg
88 file:///opt/storage/example-1.3.0.tgz)
89 • local link sources: This is the file URL of the link. (eg
91 file:libs/our-module)
92 integrity
95 This is a Standard Subresource Integrity https://w3c.github.io/we‐
96 bappsec/specs/subresourceintegrity/ for this resource.
97 • For bundled dependencies this is not included, regardless of source.
99 • For registry sources, this is the integrity that the registry pro‐
101 vided, or if one wasn't provided the SHA1 in shasum.
102 • For git sources this is the specific commit hash we cloned from.
104 • For remote tarball sources this is an integrity based on a SHA512 of
106 the file.
107 • For local tarball sources: This is an integrity field based on the
109 SHA512 of the file.
110 resolved
113 • For bundled dependencies this is not included, regardless of source.
114 • For registry sources this is path of the tarball relative to the reg‐
116 istry URL. If the tarball URL isn't on the same server as the reg‐
117 istry URL then this is a complete URL.
118 bundled
121 If true, this is the bundled dependency and will be installed by the
122 parent module. When installing, this module will be extracted from the
123 parent module during the extract phase, not installed as a separate de‐
124 pendency.
125 dev
127 If true then this dependency is either a development dependency ONLY of
128 the top level module or a transitive dependency of one. This is false
129 for dependencies that are both a development dependency of the top
130 level and a transitive dependency of a non-development dependency of
131 the top level.
132 optional
134 If true then this dependency is either an optional dependency ONLY of
135 the top level module or a transitive dependency of one. This is false
136 for dependencies that are both an optional dependency of the top level
137 and a transitive dependency of a non-optional dependency of the top
138 level.
139 All optional dependencies should be included even if they're uninstal‐
141 lable on the current platform.
142 requires
144 This is a mapping of module name to version. This is a list of every‐
145 thing this module requires, regardless of where it will be installed.
146 The version should match via normal matching rules a dependency either
147 in our dependencies or in a level higher than us.
148 dependencies
150 The dependencies of this dependency, exactly as at the top level.
151 See also
153 • npm help shrinkwrap
154 • npm help shrinkwrap.json
156 • npm help package-locks
158 • npm help package.json
160 • npm help install
162 April 2021 PACKAGE-LOCK.JSON(5)