1NPM-LINK(1) NPM-LINK(1)
2
3
4
6 npm-link - Symlink a package folder
7
8 Synopsis
9 npm link [<package-spec>]
10
11 alias: ln
12
13 Description
14 This is handy for installing your own stuff, so that you can work on it
15 and test iteratively without having to continually rebuild.
16
17 Package linking is a two-step process.
18
19 First, npm link in a package folder with no arguments will create a
20 symlink in the global folder {prefix}/lib/node_modules/<package> that
21 links to the package where the npm link command was executed. It will
22 also link any bins in the package to {prefix}/bin/{name}. Note that
23 npm link uses the global prefix (see npm prefix -g for its value).
24
25 Next, in some other location, npm link package-name will create a sym‐
26 bolic link from globally-installed package-name to node_modules/ of the
27 current folder.
28
29 Note that package-name is taken from package.json, not from the direc‐
30 tory name.
31
32 The package name can be optionally prefixed with a scope. See npm help
33 scope. The scope must be preceded by an @-symbol and followed by a
34 slash.
35
36 When creating tarballs for npm publish, the linked packages are "snap‐
37 shotted" to their current state by resolving the symbolic links, if
38 they are included in bundleDependencies.
39
40 For example:
41
42 cd ~/projects/node-redis # go into the package directory
43 npm link # creates global link
44 cd ~/projects/node-bloggy # go into some other package directory.
45 npm link redis # link-install the package
46
47 Now, any changes to ~/projects/node-redis will be reflected in
48 ~/projects/node-bloggy/node_modules/node-redis/. Note that the link
49 should be to the package name, not the directory name for that package.
50
51 You may also shortcut the two steps in one. For example, to do the
52 above use-case in a shorter way:
53
54 cd ~/projects/node-bloggy # go into the dir of your main project
55 npm link ../node-redis # link the dir of your dependency
56
57 The second line is the equivalent of doing:
58
59 (cd ../node-redis; npm link)
60 npm link redis
61
62 That is, it first creates a global link, and then links the global in‐
63 stallation target into your project's node_modules folder.
64
65 Note that in this case, you are referring to the directory name,
66 node-redis, rather than the package name redis.
67
68 If your linked package is scoped (see npm help scope) your link command
69 must include that scope, e.g.
70
71 npm link @myorg/privatepackage
72
73 Caveat
74 Note that package dependencies linked in this way are not saved to
75 package.json by default, on the assumption that the intention is to
76 have a link stand in for a regular non-link dependency. Otherwise, for
77 example, if you depend on redis@^3.0.1, and ran npm link redis, it
78 would replace the ^3.0.1 dependency with file:../path/to/node-redis,
79 which you probably don't want! Additionally, other users or developers
80 on your project would run into issues if they do not have their folders
81 set up exactly the same as yours.
82
83 If you are adding a new dependency as a link, you should add it to the
84 relevant metadata by running npm install <dep> --package-lock-only.
85
86 If you want to save the file: reference in your package.json and pack‐
87 age-lock.json files, you can use npm link <dep> --save to do so.
88
89 Workspace Usage
90 npm link <pkg> --workspace <name> will link the relevant package as a
91 dependency of the specified workspace(s). Note that It may actually be
92 linked into the parent project's node_modules folder, if there are no
93 conflicting dependencies.
94
95 npm link --workspace <name> will create a global link to the specified
96 workspace(s).
97
98 Configuration
99 save
100 • Default: true unless when using npm update where it defaults to false
101
102 • Type: Boolean
103
104
105 Save installed packages to a package.json file as dependencies.
106
107 When used with the npm rm command, removes the dependency from pack‐
108 age.json.
109
110 Will also prevent writing to package-lock.json if set to false.
111
112 save-exact
113 • Default: false
114
115 • Type: Boolean
116
117
118 Dependencies saved to package.json will be configured with an exact
119 version rather than using npm's default semver range operator.
120
121 global
122 • Default: false
123
124 • Type: Boolean
125
126
127 Operates in "global" mode, so that packages are installed into the pre‐
128 fix folder instead of the current working directory. See npm help fold‐
129 ers for more on the differences in behavior.
130
131 • packages are installed into the {prefix}/lib/node_modules folder, in‐
132 stead of the current working directory.
133
134 • bin files are linked to {prefix}/bin
135
136 • man pages are linked to {prefix}/share/man
137
138
139 global-style
140 • Default: false
141
142 • Type: Boolean
143
144
145 Causes npm to install the package into your local node_modules folder
146 with the same layout it uses with the global node_modules folder. Only
147 your direct dependencies will show in node_modules and everything they
148 depend on will be flattened in their node_modules folders. This obvi‐
149 ously will eliminate some deduping. If used with legacy-bundling,
150 legacy-bundling will be preferred.
151
152 legacy-bundling
153 • Default: false
154
155 • Type: Boolean
156
157
158 Causes npm to install the package such that versions of npm prior to
159 1.4, such as the one included with node 0.8, can install the package.
160 This eliminates all automatic deduping. If used with global-style this
161 option will be preferred.
162
163 strict-peer-deps
164 • Default: false
165
166 • Type: Boolean
167
168
169 If set to true, and --legacy-peer-deps is not set, then any conflicting
170 peerDependencies will be treated as an install failure, even if npm
171 could reasonably guess the appropriate resolution based on non-peer de‐
172 pendency relationships.
173
174 By default, conflicting peerDependencies deep in the dependency graph
175 will be resolved using the nearest non-peer dependency specification,
176 even if doing so will result in some packages receiving a peer depen‐
177 dency outside the range set in their package's peerDependencies object.
178
179 When such and override is performed, a warning is printed, explaining
180 the conflict and the packages involved. If --strict-peer-deps is set,
181 then this warning is treated as a failure.
182
183 package-lock
184 • Default: true
185
186 • Type: Boolean
187
188
189 If set to false, then ignore package-lock.json files when installing.
190 This will also prevent writing package-lock.json if save is true.
191
192 This configuration does not affect npm ci.
193
194 omit
195 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
196 duction', otherwise empty.
197
198 • Type: "dev", "optional", or "peer" (can be set multiple times)
199
200
201 Dependency types to omit from the installation tree on disk.
202
203 Note that these dependencies are still resolved and added to the pack‐
204 age-lock.json or npm-shrinkwrap.json file. They are just not physically
205 installed on disk.
206
207 If a package type appears in both the --include and --omit lists, then
208 it will be included.
209
210 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
211 ment variable will be set to 'production' for all lifecycle scripts.
212
213 ignore-scripts
214 • Default: false
215
216 • Type: Boolean
217
218
219 If true, npm does not run scripts specified in package.json files.
220
221 Note that commands explicitly intended to run a particular script, such
222 as npm start, npm stop, npm restart, npm test, and npm run-script will
223 still run their intended script if ignore-scripts is set, but they will
224 not run any pre- or post-scripts.
225
226 audit
227 • Default: true
228
229 • Type: Boolean
230
231
232 When "true" submit audit reports alongside the current npm command to
233 the default registry and all registries configured for scopes. See the
234 documentation for npm help audit for details on what is submitted.
235
236 bin-links
237 • Default: true
238
239 • Type: Boolean
240
241
242 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
243 ecutables.
244
245 Set to false to have it not do this. This can be used to work around
246 the fact that some file systems don't support symlinks, even on osten‐
247 sibly Unix systems.
248
249 fund
250 • Default: true
251
252 • Type: Boolean
253
254
255 When "true" displays the message at the end of each npm install ac‐
256 knowledging the number of dependencies looking for funding. See npm
257 help npm fund for details.
258
259 dry-run
260 • Default: false
261
262 • Type: Boolean
263
264
265 Indicates that you don't want npm to make any changes and that it
266 should only report what it would have done. This can be passed into any
267 of the commands that modify your local installation, eg, install, up‐
268 date, dedupe, uninstall, as well as pack and publish.
269
270 Note: This is NOT honored by other network related commands, eg
271 dist-tags, owner, etc.
272
273 workspace
274 • Default:
275
276 • Type: String (can be set multiple times)
277
278
279 Enable running a command in the context of the configured workspaces of
280 the current project while filtering by running only the workspaces de‐
281 fined by this configuration option.
282
283 Valid values for the workspace config are either:
284
285 • Workspace names
286
287 • Path to a workspace directory
288
289 • Path to a parent workspace directory (will result in selecting all
290 workspaces within that folder)
291
292
293 When set for the npm init command, this may be set to the folder of a
294 workspace which does not yet exist, to create the folder and set it up
295 as a brand new workspace within the project.
296
297 This value is not exported to the environment for child processes.
298
299 workspaces
300 • Default: null
301
302 • Type: null or Boolean
303
304
305 Set to true to run the command in the context of all configured
306 workspaces.
307
308 Explicitly setting this to false will cause commands like install to
309 ignore workspaces altogether. When not set explicitly:
310
311 • Commands that operate on the node_modules tree (install, update,
312 etc.) will link workspaces into the node_modules folder. - Commands
313 that do other things (test, exec, publish, etc.) will operate on the
314 root project, unless one or more workspaces are specified in the
315 workspace config.
316
317
318 This value is not exported to the environment for child processes.
319
320 include-workspace-root
321 • Default: false
322
323 • Type: Boolean
324
325
326 Include the workspace root when workspaces are enabled for a command.
327
328 When false, specifying individual workspaces via the workspace config,
329 or all workspaces via the workspaces flag, will cause npm to operate
330 only on the specified workspaces, and not on the root project.
331
332 This value is not exported to the environment for child processes.
333
334 install-links
335 • Default: false
336
337 • Type: Boolean
338
339
340 When set file: protocol dependencies that exist outside of the project
341 root will be packed and installed as regular dependencies instead of
342 creating a symlink. This option has no effect on workspaces.
343
344 See Also
345 • npm help package spec
346
347 • npm help developers
348
349 • npm help package.json
350
351 • npm help install
352
353 • npm help folders
354
355 • npm help config
356
357 • npm help npmrc
358
359
360
361
362 September 2022 NPM-LINK(1)