codekingpro/portable-devtools
114k
1<!DOCTYPE html><html><head>
2<meta charset="utf-8">
3<title>package-lock.json</title>
4<style>
5body {
6 background-color: #ffffff;
7 color: #24292e;
8
9 margin: 0;
10
11 line-height: 1.5;
12
13 font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
14}
15#rainbar {
16 height: 10px;
17 background-image: linear-gradient(139deg, #fb8817, #ff4b01, #c12127, #e02aff);
18}
19
20a {
21 text-decoration: none;
22 color: #0366d6;
23}
24a:hover {
25 text-decoration: underline;
26}
27
28pre {
29 margin: 1em 0px;
30 padding: 1em;
31 border: solid 1px #e1e4e8;
32 border-radius: 6px;
33
34 display: block;
35 overflow: auto;
36
37 white-space: pre;
38
39 background-color: #f6f8fa;
40 color: #393a34;
41}
42code {
43 font-family: SFMono-Regular, Consolas, "Liberation Mono", Menlo, Courier, monospace;
44 font-size: 85%;
45 padding: 0.2em 0.4em;
46 background-color: #f6f8fa;
47 color: #393a34;
48}
49pre > code {
50 padding: 0;
51 background-color: inherit;
52 color: inherit;
53}
54h1, h2, h3 {
55 font-weight: 600;
56}
57
58#logobar {
59 background-color: #333333;
60 margin: 0 auto;
61 padding: 1em 4em;
62}
63#logobar .logo {
64 float: left;
65}
66#logobar .title {
67 font-weight: 600;
68 color: #dddddd;
69 float: left;
70 margin: 5px 0 0 1em;
71}
72#logobar:after {
73 content: "";
74 display: block;
75 clear: both;
76}
77
78#content {
79 margin: 0 auto;
80 padding: 0 4em;
81}
82
83#table_of_contents > h2 {
84 font-size: 1.17em;
85}
86#table_of_contents ul:first-child {
87 border: solid 1px #e1e4e8;
88 border-radius: 6px;
89 padding: 1em;
90 background-color: #f6f8fa;
91 color: #393a34;
92}
93#table_of_contents ul {
94 list-style-type: none;
95 padding-left: 1.5em;
96}
97#table_of_contents li {
98 font-size: 0.9em;
99}
100#table_of_contents li a {
101 color: #000000;
102}
103
104header.title {
105 border-bottom: solid 1px #e1e4e8;
106}
107header.title > h1 {
108 margin-bottom: 0.25em;
109}
110header.title > .description {
111 display: block;
112 margin-bottom: 0.5em;
113 line-height: 1;
114}
115
116header.title .version {
117 font-size: 0.8em;
118 color: #666666;
119}
120
121footer#edit {
122 border-top: solid 1px #e1e4e8;
123 margin: 3em 0 4em 0;
124 padding-top: 2em;
125}
126
127table {
128 width: 100%;
129 margin: 1em 0;
130 border-radius: 6px;
131 border: 1px solid #e1e4e8;
132 overflow: hidden;
133 border-collapse: separate;
134 border-spacing: 0;
135}
136
137table thead {
138 background-color: #f6f8fa;
139}
140
141table tbody {
142 background-color: #ffffff;
143}
144
145table th,
146table td {
147 padding: 0.75em;
148 text-align: left;
149 border-right: 1px solid #e1e4e8;
150 border-bottom: 1px solid #e1e4e8;
151}
152
153table th:last-child,
154table td:last-child {
155 border-right: none;
156}
157
158table tbody tr:last-child td {
159 border-bottom: none;
160}
161
162table th {
163 font-weight: 600;
164 background-color: #f6f8fa;
165}
166
167table code {
168 white-space: nowrap;
169}
170
171</style>
172</head>
173<body>
174<div id="banner">
175<div id="rainbar"></div>
176<div id="logobar">
177<svg class="logo" role="img" height="32" width="32" viewBox="0 0 700 700">
178<polygon fill="#cb0000" points="0,700 700,700 700,0 0,0"></polygon>
179<polygon fill="#ffffff" points="150,550 350,550 350,250 450,250 450,550 550,550 550,150 150,150"></polygon>
180</svg>
181<div class="title">
182npm command-line interface
183</div>
184</div>
185</div>
186
187<section id="content">
188<header class="title">
189<h1 id="----package-lockjson----11121">
190 <span>package-lock.json</span>
191 <span class="version">@11.12.1</span>
192</h1>
193<span class="description">A manifestation of the manifest</span>
194</header>
195
196<section id="table_of_contents">
197<h2 id="table-of-contents">Table of contents</h2>
198<div id="_table_of_contents"><ul><li><a href="#description">Description</a></li><li><a href="#package-lockjson-vs-npm-shrinkwrapjson"><code>package-lock.json</code> vs <code>npm-shrinkwrap.json</code></a></li><li><a href="#hidden-lockfiles">Hidden Lockfiles</a></li><li><a href="#handling-old-lockfiles">Handling Old Lockfiles</a></li><li><a href="#file-format">File Format</a></li><ul><li><a href="#name"><code>name</code></a></li><li><a href="#version"><code>version</code></a></li><li><a href="#lockfileversion"><code>lockfileVersion</code></a></li><li><a href="#packages"><code>packages</code></a></li><li><a href="#dependencies">dependencies</a></li></ul><li><a href="#see-also">See also</a></li></ul></div>
199</section>
200
201<div id="_content"><h3 id="description">Description</h3>
202<p><code>package-lock.json</code> is automatically generated for any operations where npm modifies either the <code>node_modules</code> tree, or <code>package.json</code>.
203It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.</p>
204<p>This file is intended to be committed into source repositories, and serves various purposes:</p>
205<ul>
206<li>
207<p>Describe a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies.</p>
208</li>
209<li>
210<p>Provide a facility for users to "time-travel" to previous states of <code>node_modules</code> without having to commit the directory itself.</p>
211</li>
212<li>
213<p>Facilitate greater visibility of tree changes through readable source control diffs.</p>
214</li>
215<li>
216<p>Optimize the installation process by allowing npm to skip repeated metadata resolutions for previously-installed packages.</p>
217</li>
218<li>
219<p>As of npm v7, lockfiles include enough information to gain a complete picture of the package tree, reducing the need to read <code>package.json</code> files, and allowing for significant performance improvements.</p>
220</li>
221</ul>
222<p>When <code>npm</code> creates or updates <code>package-lock.json</code>, it will infer line endings and indentation from <code>package.json</code> so that the formatting of both files matches.</p>
223<h3 id="package-lockjson-vs-npm-shrinkwrapjson"><code>package-lock.json</code> vs <code>npm-shrinkwrap.json</code></h3>
224<p>Both of these files have the same format, and perform similar functions in the root of a project.</p>
225<p>The difference is that <code>package-lock.json</code> cannot be published, and it will be ignored if found in any place other than the root project.</p>
226<p>In contrast, <a href="../configuring-npm/npm-shrinkwrap-json.html">npm-shrinkwrap.json</a> allows publication, and defines the dependency tree from the point encountered.
227This is not recommended unless deploying a CLI tool or otherwise using the publication process for producing production packages.</p>
228<p>If both <code>package-lock.json</code> and <code>npm-shrinkwrap.json</code> are present in the root of a project, <code>npm-shrinkwrap.json</code> will take precedence and <code>package-lock.json</code> will be ignored.</p>
229<h3 id="hidden-lockfiles">Hidden Lockfiles</h3>
230<p>In order to avoid processing the <code>node_modules</code> folder repeatedly, npm as of v7 uses a "hidden" lockfile present in <code>node_modules/.package-lock.json</code>.
231This contains information about the tree, and is used in lieu of reading the entire <code>node_modules</code> hierarchy provided that the following conditions are met:</p>
232<ul>
233<li>All package folders it references exist in the <code>node_modules</code> hierarchy.</li>
234<li>No package folders exist in the <code>node_modules</code> hierarchy that are not listed in the lockfile.</li>
235<li>The modified time of the file is at least as recent as all of the package folders it references.</li>
236</ul>
237<p>That is, the hidden lockfile will only be relevant if it was created as part of the most recent update to the package tree.
238If another CLI mutates the tree in any way, this will be detected, and the hidden lockfile will be ignored.</p>
239<p>Note that it <em>is</em> possible to manually change the <em>contents</em> of a package in such a way that the modified time of the package folder is unaffected.
240For example, if you add a file to <code>node_modules/foo/lib/bar.js</code>, then the modified time on <code>node_modules/foo</code> will not reflect this change.
241If you are manually editing files in <code>node_modules</code>, it is generally best to delete the file at <code>node_modules/.package-lock.json</code>.</p>
242<p>As the hidden lockfile is ignored by older npm versions, it does not contain the backwards compatibility affordances present in "normal" lockfiles.
243That is, it is <code>lockfileVersion: 3</code>, rather than <code>lockfileVersion: 2</code>.</p>
244<h3 id="handling-old-lockfiles">Handling Old Lockfiles</h3>
245<p>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 <code>node_modules</code> tree or (in the case of empty <code>node_modules</code> trees or very old lockfile formats) the npm registry.</p>
246<h3 id="file-format">File Format</h3>
247<h4 id="name"><code>name</code></h4>
248<p>The name of the package this is a package-lock for.
249This will match what's in <code>package.json</code>.</p>
250<h4 id="version"><code>version</code></h4>
251<p>The version of the package this is a package-lock for.
252This will match what's in <code>package.json</code>.</p>
253<h4 id="lockfileversion"><code>lockfileVersion</code></h4>
254<p>An integer version, starting at <code>1</code> with the version number of this document whose semantics were used when generating this <code>package-lock.json</code>.</p>
255<p>Note that the file format changed significantly in npm v7 to track information that would have otherwise required looking in <code>node_modules</code> or the npm registry.
256Lockfiles generated by npm v7 will contain <code>lockfileVersion: 2</code>.</p>
257<ul>
258<li>No version provided: an "ancient" shrinkwrap file from a version of npm prior to npm v5.</li>
259<li><code>1</code>: The lockfile version used by npm v5 and v6.</li>
260<li><code>2</code>: The lockfile version used by npm v7 and v8. Backwards compatible to v1 lockfiles.</li>
261<li><code>3</code>: The lockfile version used by npm v9 and above.
262Backwards compatible to npm v7.</li>
263</ul>
264<p>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.</p>
265<h4 id="packages"><code>packages</code></h4>
266<p>This is an object that maps package locations to an object containing the information about that package.</p>
267<p>The root project is typically listed with a key of <code>""</code>, and all other packages are listed with their relative paths from the root project folder.</p>
268<p>Package descriptors have the following fields:</p>
269<ul>
270<li>
271<p>version: The version found in <code>package.json</code></p>
272</li>
273<li>
274<p>resolved: The place where the package was actually resolved from.
275In the case of packages fetched from the registry, this will be a url to a tarball.
276In the case of git dependencies, this will be the full git url with commit sha.
277In the case of link dependencies, this will be the location of the link target.
278<code>registry.npmjs.org</code> is a magic value meaning "the currently configured registry".</p>
279</li>
280<li>
281<p>integrity: A <code>sha512</code> or <code>sha1</code> <a href="https://w3c.github.io/webappsec/specs/subresourceintegrity/">Standard Subresource Integrity</a> string for the artifact that was unpacked in this location.</p>
282</li>
283<li>
284<p>link: A flag to indicate that this is a symbolic link.
285If this is present, no other fields are specified, since the link target will also be included in the lockfile.</p>
286</li>
287<li>
288<p>dev, optional, devOptional: If the package is strictly part of the
289<code>devDependencies</code> tree, then <code>dev</code> will be true.
290If it is strictly part of the <code>optionalDependencies</code> tree, then <code>optional</code> will be set.
291If it is both a <code>dev</code> dependency <em>and</em> an <code>optional</code> dependency of a non-dev dependency, then <code>devOptional</code> will be set.
292(An <code>optional</code> dependency of a <code>dev</code> dependency will have both <code>dev</code> and <code>optional</code> set.)</p>
293</li>
294<li>
295<p>inBundle: A flag to indicate that the package is a bundled dependency.</p>
296</li>
297<li>
298<p>hasInstallScript: A flag to indicate that the package has a <code>preinstall</code>, <code>install</code>, or <code>postinstall</code> script.</p>
299</li>
300<li>
301<p>hasShrinkwrap: A flag to indicate that the package has an <code>npm-shrinkwrap.json</code> file.</p>
302</li>
303<li>
304<p>bin, license, engines, dependencies, optionalDependencies: fields from <code>package.json</code></p>
305</li>
306<li>
307<p>os: An array of operating systems this package is compatible with, as specified in <code>package.json</code>. This field is included when the package specifies OS restrictions.</p>
308</li>
309<li>
310<p>cpu: An array of CPU architectures this package is compatible with, as specified in <code>package.json</code>. This field is included when the package specifies CPU restrictions.</p>
311</li>
312<li>
313<p>funding: Funding information for the package, as specified in <code>package.json</code>. This field contains details about how to support the package maintainers.</p>
314</li>
315</ul>
316<h4 id="dependencies">dependencies</h4>
317<p>Legacy data for supporting versions of npm that use <code>lockfileVersion: 1</code>.
318This is a mapping of package names to dependency objects.
319Because the object structure is strictly hierarchical, symbolic link dependencies are somewhat challenging to represent in some cases.</p>
320<p>npm v7 ignores this section entirely if a <code>packages</code> section is present, but does keep it up to date in order to support switching between npm v6 and npm v7.</p>
321<p>Dependency objects have the following fields:</p>
322<ul>
323<li>
324<p>version: a specifier that varies depending on the nature of the package, and is usable in fetching a new copy of it.
325Note that for peer dependencies that are not installed, or optional dependencies that are not installed, this field may be omitted.</p>
326<ul>
327<li>bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.</li>
328<li>registry sources: This is a version number.
329(eg, <code>1.2.3</code>)</li>
330<li>git sources: This is a git specifier with resolved committish.
331(eg, <code>git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e</code>)</li>
332<li>http tarball sources: This is the URL of the tarball.
333(eg, <code>https://example.com/example-1.3.0.tgz</code>)</li>
334<li>local tarball sources: This is the file URL of the tarball.
335(eg <code>file:///opt/storage/example-1.3.0.tgz</code>)</li>
336<li>local link sources: This is the file URL of the link.
337(eg <code>file:libs/our-module</code>)</li>
338</ul>
339<p><strong>Note:</strong> The <code>version</code> field may be omitted for certain types of dependencies, such as optional peer dependencies that are not installed. In these cases, only metadata fields like <code>dev</code>, <code>optional</code>, and <code>peer</code> will be present.</p>
340</li>
341<li>
342<p>integrity: A <code>sha512</code> or <code>sha1</code> <a href="https://w3c.github.io/webappsec/specs/subresourceintegrity/">Standard Subresource Integrity</a> string for the artifact that was unpacked in this location.
343For git dependencies, this is the commit sha.</p>
344</li>
345<li>
346<p>resolved: For registry sources this is path of the tarball relative to the registry URL.
347If the tarball URL isn't on the same server as the registry URL then this is a complete URL.
348<code>registry.npmjs.org</code> is a magic value meaning "the currently configured registry".</p>
349</li>
350<li>
351<p>bundled: If true, this is the bundled dependency and will be installed by the parent module.
352When installing, this module will be extracted from the parent module during the extract phase, not installed as a separate dependency.</p>
353</li>
354<li>
355<p>dev: If true then this dependency is either a development dependency ONLY of the top level module or a transitive dependency of one.
356This 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.</p>
357</li>
358<li>
359<p>optional: If true then this dependency is either an optional dependency ONLY of the top level module or a transitive dependency of one.
360This 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.</p>
361</li>
362<li>
363<p>requires: This is a mapping of module name to version.
364This is a list of everything this module requires, regardless of where it will be installed.
365The version should match via normal matching rules a dependency either in our <code>dependencies</code> or in a level higher than us.</p>
366</li>
367<li>
368<p>dependencies: The dependencies of this dependency, exactly as at the top level.</p>
369</li>
370</ul>
371<h3 id="see-also">See also</h3>
372<ul>
373<li><a href="../commands/npm-shrinkwrap.html">npm shrinkwrap</a></li>
374<li><a href="../configuring-npm/npm-shrinkwrap-json.html">npm-shrinkwrap.json</a></li>
375<li><a href="../configuring-npm/package-json.html">package.json</a></li>
376<li><a href="../commands/npm-install.html">npm install</a></li>
377</ul></div>
378
379<footer id="edit">
380<a href="https://github.com/npm/cli/edit/latest/docs/lib/content/configuring-npm/package-lock-json.md">
381<svg role="img" viewBox="0 0 16 16" width="16" height="16" fill="currentcolor" style="vertical-align: text-bottom; margin-right: 0.3em;">
382<path fill-rule="evenodd" d="M11.013 1.427a1.75 1.75 0 012.474 0l1.086 1.086a1.75 1.75 0 010 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 01-.927-.928l.929-3.25a1.75 1.75 0 01.445-.758l8.61-8.61zm1.414 1.06a.25.25 0 00-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 000-.354l-1.086-1.086zM11.189 6.25L9.75 4.81l-6.286 6.287a.25.25 0 00-.064.108l-.558 1.953 1.953-.558a.249.249 0 00.108-.064l6.286-6.286z"></path>
383</svg>
384Edit this page on GitHub
385</a>
386</footer>
387</section>
388
389
390
391</body></html>