1NPM-LINK(1)                                                        NPM-LINK(1)
2
3
4

NAME

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