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
19 teammates, deployments, and continuous integration are guaranteed
20 to install 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 • Facilitate greater visibility of tree changes through readable
26 source control diffs.
27 • Optimize the installation process by allowing npm to skip repeated
29 metadata resolutions for previously-installed packages.
30 • As of npm v7, lockfiles include enough information to gain a com‐
32 plete picture of the package tree, reducing the need to read pack‐
33 age.json files, and allowing for significant performance improve‐
34 ments.
35 package-lock.json vs npm-shrinkwrap.json
38 Both of these files have the same format, and perform similar functions
39 in the root of a project.
40 The difference is that package-lock.json cannot be published, and it
42 will be ignored if found in any place other than the root project.
43 In contrast, npm-shrinkwrap.json ⟨/configuring-npm/npm-shrinkwrap-json⟩
45 allows publication, and defines the dependency tree from the point en‐
46 countered. This is not recommended unless deploying a CLI tool or oth‐
47 erwise using the publication process for producing production packages.
48 If both package-lock.json and npm-shrinkwrap.json are present in the
50 root of a project, npm-shrinkwrap.json will take precedence and pack‐
51 age-lock.json will be ignored.
52 Hidden Lockfiles
54 In order to avoid processing the node_modules folder repeatedly, npm as
55 of v7 uses a "hidden" lockfile present in node_modules/.package-
56 lock.json. This contains information about the tree, and is used in
57 lieu of reading the entire node_modules hierarchy provided that the
58 following conditions are met:
59 • All package folders it references exist in the node_modules hierar‐
61 chy.
62 • No package folders exist in the node_modules hierarchy that are not
64 listed in the lockfile.
65 • The modified time of the file is at least as recent as all of the
67 package folders it references.
68 That is, the hidden lockfile will only be relevant if it was created as
71 part of the most recent update to the package tree. If another CLI mu‐
72 tates the tree in any way, this will be detected, and the hidden lock‐
73 file will be ignored.
74 Note that it is possible to manually change the contents of a package
76 in such a way that the modified time of the package folder is unaf‐
77 fected. For example, if you add a file to node_modules/foo/lib/bar.js,
78 then the modified time on node_modules/foo will not reflect this
79 change. If you are manually editing files in node_modules, it is gener‐
80 ally best to delete the file at node_modules/.package-lock.json.
81 As the hidden lockfile is ignored by older npm versions, it does not
83 contain the backwards compatibility affordances present in "normal"
84 lockfiles. That is, it is lockfileVersion: 3, rather than lockfileVer‐
85 sion: 2.
86 Handling Old Lockfiles
88 When npm detects a lockfile from npm v6 or before during the package
89 installation process, it is automatically updated to fetch missing in‐
90 formation from either the node_modules tree or (in the case of empty
91 node_modules trees or very old lockfile formats) the npm registry.
92 File Format
94 name
95 The name of the package this is a package-lock for. This will match
96 what's in package.json.
97 version
99 The version of the package this is a package-lock for. This will match
100 what's in package.json.
101 lockfileVersion
103 An integer version, starting at 1 with the version number of this docu‐
104 ment whose semantics were used when generating this package-lock.json.
105 Note that the file format changed significantly in npm v7 to track in‐
107 formation that would have otherwise required looking in node_modules or
108 the npm registry. Lockfiles generated by npm v7 will contain lock‐
109 fileVersion: 2.
110 • No version provided: an "ancient" shrinkwrap file from a version of
112 npm prior to npm v5.
113 • 1: The lockfile version used by npm v5 and v6.
115 • 2: The lockfile version used by npm v7 and v8. Backwards compatible
117 to v1 lockfiles.
118 • 3: The lockfile version used by npm v9 and above. Backwards compat‐
120 ible to npm v7.
121 npm will always attempt to get whatever data it can out of a lockfile,
124 even if it is not a version that it was designed to support.
125 packages
127 This is an object that maps package locations to an object containing
128 the information about that package.
129 The root project is typically listed with a key of "", and all other
131 packages are listed with their relative paths from the root project
132 folder.
133 Package descriptors have the following fields:
135 • version: The version found in package.json
137 • resolved: The place where the package was actually resolved from.
139 In the case of packages fetched from the registry, this will be a
140 url to a tarball. In the case of git dependencies, this will be the
141 full git url with commit sha. In the case of link dependencies,
142 this will be the location of the link target. registry.npmjs.org is
143 a magic value meaning "the currently configured registry".
144 • integrity: A sha512 or sha1 Standard Subresource Integrity
146 ⟨https://w3c.github.io/webappsec/specs/subresourceintegrity/⟩
147 string for the artifact that was unpacked in this location.
148 • link: A flag to indicate that this is a symbolic link. If this is
150 present, no other fields are specified, since the link target will
151 also be included in the lockfile.
152 • dev, optional, devOptional: If the package is strictly part of the
154 devDependencies tree, then dev will be true. If it is strictly part
155 of the optionalDependencies tree, then optional will be set. If it
156 is both a dev dependency and an optional dependency of a non-dev
157 dependency, then devOptional will be set. (An optional dependency
158 of a dev dependency will have both dev and optional set.)
159 • inBundle: A flag to indicate that the package is a bundled depen‐
161 dency.
162 • hasInstallScript: A flag to indicate that the package has a prein‐
164 stall, install, or postinstall script.
165 • hasShrinkwrap: A flag to indicate that the package has an npm-
167 shrinkwrap.json file.
168 • bin, license, engines, dependencies, optionalDependencies: fields
170 from package.json
171 dependencies
174 Legacy data for supporting versions of npm that use lockfileVersion: 1.
175 This is a mapping of package names to dependency objects. Because the
176 object structure is strictly hierarchical, symbolic link dependencies
177 are somewhat challenging to represent in some cases.
178 npm v7 ignores this section entirely if a packages section is present,
180 but does keep it up to date in order to support switching between npm
181 v6 and npm v7.
182 Dependency objects have the following fields:
184 • version: a specifier that varies depending on the nature of the
186 package, and is usable in fetching a new copy of it.
187 • bundled dependencies: Regardless of source, this is a version
189 number that is purely for informational purposes.
190 • registry sources: This is a version number. (eg, 1.2.3)
192 • git sources: This is a git specifier with resolved committish.
194 (eg, git+https://exam‐
195 ple.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e)
196 • http tarball sources: This is the URL of the tarball. (eg,
198 https://example.com/example-1.3.0.tgz)
199 • local tarball sources: This is the file URL of the tarball. (eg
201 file:///opt/storage/example-1.3.0.tgz)
202 • local link sources: This is the file URL of the link. (eg
204 file:libs/our-module)
205 • integrity: A sha512 or sha1 Standard Subresource Integrity
208 ⟨https://w3c.github.io/webappsec/specs/subresourceintegrity/⟩
209 string for the artifact that was unpacked in this location. For git
210 dependencies, this is the commit sha.
211 • resolved: For registry sources this is path of the tarball relative
213 to the registry URL. If the tarball URL isn't on the same server as
214 the registry URL then this is a complete URL. registry.npmjs.org is
215 a magic value meaning "the currently configured registry".
216 • bundled: If true, this is the bundled dependency and will be in‐
218 stalled by the parent module. When installing, this module will be
219 extracted from the parent module during the extract phase, not in‐
220 stalled as a separate dependency.
221 • dev: If true then this dependency is either a development depen‐
223 dency ONLY of the top level module or a transitive dependency of
224 one. This is false for dependencies that are both a development de‐
225 pendency of the top level and a transitive dependency of a non-de‐
226 velopment dependency of the top level.
227 • optional: If true then this dependency is either an optional depen‐
229 dency ONLY of the top level module or a transitive dependency of
230 one. This is false for dependencies that are both an optional de‐
231 pendency of the top level and a transitive dependency of a non-op‐
232 tional dependency of the top level.
233 • requires: This is a mapping of module name to version. This is a
235 list of everything this module requires, regardless of where it
236 will be installed. The version should match via normal matching
237 rules a dependency either in our dependencies or in a level higher
238 than us.
239 • dependencies: The dependencies of this dependency, exactly as at
241 the top level.
242 See also
245 • npm help shrinkwrap
246 • npm-shrinkwrap.json ⟨/configuring-npm/npm-shrinkwrap-json⟩
248 • package.json ⟨/configuring-npm/package-json⟩
250 • npm help install
252 November 2023 PACKAGE-LOCK.JSON(5)