1 +
# package-lock and npm-shrinkwrap
2 + 3 +
`npm` can have one of two different lock files:
4 + 5 +
* `package-lock.json`, which is ordinarily always present and is never published.
6 +
* `npm-shrinkwrap.json`, which is created with `npm shrinkwrap` and usually published.
7 + 8 +
You can only have one of them and in the event that you have both,
9 +
`npm-shrinkwrap.json` takes precedence. The files are exactly the same
10 +
format and in fact all the `npm shrinkwrap` command does is rename your
11 +
`package-lock.json`.
12 + 13 +
Through the rest of this document we will refer to the package-lock and
14 +
`package-lock.json` but everything also applies to `npm-shrinkwrap.json`.
15 + 16 +
## File Format
17 + 18 +
### name
19 + 20 +
The name of the package this is a package-lock for. This must match what's in `package.json`.
21 + 22 +
### version
23 + 24 +
The version of the package this is a package-lock for. This must match what's in `package.json`.
25 + 26 +
### lockfileVersion *(new)*
27 + 28 +
An integer version, starting at `1` with the version number of this document
29 +
whose semantics were used when generating this `package-lock.json`.
30 + 31 +
### packageIntegrity *(new)*
32 + 33 +
This is a
34 +
[subresource integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/)
35 +
value created from the `pacakge.json`. No preprocessing of the
36 +
`package.json` should be done. Subresource integrity strings can be
37 +
produced by modules like
38 +
[`ssri`](https://www.npmjs.com/package/ssri).
39 + 40 +
### preserveSymlinks *(new)*
41 + 42 +
Indicates that the install was done with the environment variable
43 +
`NODE_PRESERVE_SYMLINKS` enabled. The installer should insist that the value of this
44 +
property match that environment variable.
45 + 46 +
### dependencies
47 + 48 +
A mapping of package name to dependency object. Dependency objects have the
49 +
following properties:
50 + 51 +
#### version *(changed)*
52 + 53 +
This is a specifier that uniquely identifies this package and should be
54 +
usable in fetching a new copy of it.
55 + 56 +
* bundled dependencies: Regardless of source, this is a version number that is purely for informational purposes.
57 +
* registry sources: This is a version number. (eg, `1.2.3`)
58 +
* git sources: This is a git specifier with resolved committish. (eg, `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)
59 +
* http tarball sources: This is the URL of the tarball. (eg, `https://example.com/example-1.3.0.tgz`)
60 +
* local tarball sources: This is the file URL of the tarball. (eg `file:///opt/storage/example-1.3.0.tgz`)
61 +
* local link sources: This is the file URL of the link. (eg `file:libs/our-module`)
62 + 63 +
#### integrity *(new)*
64 + 65 +
This is a [Standard Subresource
66 +
Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/) for
67 +
this resource.
68 + 69 +
* For bundled dependencies this is not included, regardless of source.
70 +
* For registry sources, this is the `integrity` that the registry provided, or if one wasn't provided the SHA1 in `shasum`.
71 +
* For git sources this is the specific commit hash we cloned from.
72 +
* For remote tarball sources this is an integrity based on a SHA512 of
73 +
the file.
74 +
* For local tarball sources: This is an integrity field based on the SHA512 of the file.
75 + 76 +
#### resolved
77 + 78 +
* For bundled dependencies this is not included, regardless of source.
79 +
* For registry sources this is path of the tarball relative to the registry
80 +
URL. If the tarball URL isn't on the same server as the registry URL then
81 +
this is a complete URL.
82 + 83 +
#### link *(new)*
84 + 85 +
If this module was symlinked in development but had semver in the
86 +
`package.json` then this is the relative path of that link.
87 + 88 +
Discussion of the semantics of this will go in the symlinks RFC.
89 + 90 +
Implementation note: To be implemented post npm@5.
91 + 92 +
#### bundled *(new)*
93 + 94 +
If true, this is the bundled dependency and will be installed by the parent
95 +
module. When installing, this module will be extracted from the parent
96 +
module during the extract phase, not installed as a separate dependency.
97 + 98 +
#### dev
99 + 100 +
If true then this dependency is either a development dependency ONLY of the
101 +
top level module or a transitive dependency of one. This is false for
102 +
dependencies that are both a development dependency of the top level and a
103 +
transitive dependency of a non-development dependency of the top level.
104 + 105 +
#### optional
106 + 107 +
If true then this dependency is either an optional dependency ONLY of the
108 +
top level module or a transitive dependency of one. This is false for
109 +
dependencies that are both an optional dependency of the top level and a
110 +
transitive dependency of a non-optional dependency of the top level.
111 + 112 +
All optional dependencies should be included even if they're uninstallable
113 +
on the current platform.
114 + 115 +
#### from *(deprecated)*
116 + 117 +
This is a record of what specifier was used to originally install this
118 +
package. This should not be included in new `package-lock.json` files.
119 + 120 +
#### dependencies
121 + 122 +
The dependencies of this dependency, exactly as at the top level.
123 + 124 +
## Generating
125 + 126 +
### `npm init`
127 + 128 +
If neither a `package-lock.json` nor an `npm-shrinkwrap.json` exist then
129 +
`npm init` will create a `package-lock.json`. This is functionally
130 +
equivalent to running `npm shrinkwrap` after the current init completes and
131 +
renaming the result to `package-lock.json`.
132 + 133 +
### `npm install --save`
134 + 135 +
If either an `npm-shrinkwrap.json` or a `package-lock.json` exists then it
136 +
will be updated.
137 + 138 +
If neither exist then a `package-lock.json` should be generated.
139 + 140 +
If a `package.json` does not exist, it should be generated. The generated
141 +
`package.json` should be empty, as in:
142 + 143 +
```
144 +
{
145 +
"dependencies": {
146 +
}
147 +
}
148 +
```
149 + 150 +
If the user wants to get a default package name/version added they can run `npm init`.
151 + 152 +
### `npm shrinkwrap`
153 + 154 +
If a `package-lock.json` exists, rename it to `npm-shrinkwrap.json`.
155 +
Refresh the data from the installer's ideal tree.
156 + 157 +
The top level `name` and `version` come from the `package.json`. It is an
158 +
error if either are missing or invalid.
159 + 160 +
#### dependencies.dev
161 + 162 +
This is `true` if this dependency is ONLY installed to fulfill either a top
163 +
level development dependency, or one of its transitive dependencies.
164 + 165 +
Given:
166 +
```
167 +
B (Dev) → C
168 +
```
169 + 170 +
Then both B and C would be `dev: true`.
171 + 172 +
Given:
173 +
```
174 +
A → B → C
175 +
B (Dev) -> C
176 +
```
177 + 178 +
Then all dependencies would be `dev: false`.
179 + 180 +
#### dependencies.optional
181 + 182 +
This is `true` if this dependency is ONLY ever either an optional dependency
183 +
or a transitive dependency of optional dependencies.
184 + 185 +
Given:
186 +
```
187 +
A (Opt) → B → C
188 +
```
189 + 190 +
Then all three of A, B and C would be flagged as optional.
191 + 192 +
Given:
193 +
```
194 +
A (Opt) → B → C
195 +
D → C
196 +
```
197 + 198 +
Then A and B would be flagged as optional, but C would not be.
199 + 200 +
Given:
201 +
```
202 +
A (Opt) → B → C
203 +
D → A
204 +
```
205 + 206 +
Then none would be flagged as optional.
207 + 208 +
## Installing
209 + 210 +
If the `packageIntegrity` in the `package-lock.json` differs from the one
211 +
computed from the `package.json` then places where the `package.json` is
212 +
incompatible with the `package-lock.json` a new module should be installed.
213 +
That is, while the `package-lock.json` ordinarily defines the state of your
214 +
project, if your `package.json` is edited independently it will take
215 +
precedence.
216 + 217 +
The `package-lock.json` describes the exact tree that `npm` should create.
218 +
Any deviation between the `package.json` and the shrinkwrap/lock should
219 +
result in a warning be issued. This includes:
220 + 221 +
* Modules in `package.json` but missing from the `package-lock.json`
222 +
* Modules in the `package-lock.json` but missing from the `package.json`.
223 +
* Modules in `package.json` whose specifiers don't match the version in `package-lock.json`.
224 + 225 +
Warn if the `lockfileVersion` in the `package-lock.json` is for a different
226 +
major version than we implement.
227 + 228 +
Module resolution from package-lock data works as such:
229 + 230 +
* If install was run with `--resolve-links` and a dependency has a `link`
231 +
property then a symlink is made using that. If the version of the
232 +
destination can not be matched to the package-lock and/or the package.json
233 +
then a warning will be issued.
234 + 235 +
* Otherwise, if a `integrity` is available then we try to install it from the cache using it.
236 + 237 +
If `integrity` is unavailable or we are unable to locate a module from the `integrity` then:
238 + 239 +
* If `lockfileVersion` is set:
240 +
* Install using the value of `version` and validate the result against the
241 +
`integrity`.
242 +
* Otherwise, try these in turn and validate the result against the `integrity`:
243 +
* `resolved`, then `from`, then `version.
244 +
* `from` can be either `package@specifier` or just `specifier`.
245 + 246 +
Regardless of how the module is installed the metadata in the installed
247 +
module should be identical to what it would have been if the module were
248 +
installed w/o a package-lock.
249 + 250 +
## Implied Changes To Other Commands
251 + 252 +
### `npm rm --save`
253 + 254 +
Currently if you ask to remove a package that's both a direct and a
255 +
transitive dependency, we'll remove the package from `node_modules` even if
256 +
this results in a broken tree. This was chosen at the time because we felt
257 +
that users would expect `npm rm pkgname` to be equivalent of
258 +
`rm -rf node_modules/pkgname`.
259 + 260 +
As you are no longer going to be allowed to put your `node_modules` in a
261 +
state that's not a valid package-lock, this means this behavior is no longer
262 +
valid. Instead we should follow normal rules, removing it from the
263 +
dependencies for the top level but only removing the module on disk if
264 +
nothing requires it any more.
265 + 266 +
## Additional fields / Adding new fields
267 + 268 +
Installers should ignore any field they aren't aware of. It's not an error
269 +
to have additional properities in the package-lock or lock file.
270 + 271 +
Installers that want to add new fields should either have one added via RFC
272 +
in the npm issue tracker and an accompanying documentation PR, or should prefix
273 +
it with the name of their project.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4