1NPM-LINK(1) NPM-LINK(1)
2
6 npm-link - Symlink a package folder
7 Synopsis
9 npm link (in package dir)
10 npm link [<@scope>/]<pkg>[@<version>]
11 alias: npm ln
13 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 Package linking is a two-step process.
19 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 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 Note that package-name is taken from package.json, not from the direc‐
31 tory name.
32 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 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 For example:
42 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 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 You may also shortcut the two steps in one. For example, to do the
53 above use-case in a shorter way:
54 cd ~/projects/node-bloggy # go into the dir of your main project
56 npm link ../node-redis # link the dir of your dependency
57 The second line is the equivalent of doing:
59 (cd ../node-redis; npm link)
61 npm link redis
62 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 Note that in this case, you are referring to the directory name,
67 node-redis, rather than the package name redis.
68 If your linked package is scoped (see npm help scope) your link command
70 must include that scope, e.g.
71 npm link @myorg/privatepackage
73 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 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 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 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 npm link --workspace <name> will create a global link to the specified
97 workspace(s).
98 Configuration
100 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START --> <!-- automatically
101 generated, do not edit manually --> <!-- see lib/utils/config/defini‐
102 tions.js -->
103 save
105 • Default: true
106 • Type: Boolean
108 Save installed packages to a package.json file as dependencies.
111 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 save-exact
118 • Default: false
119 • Type: Boolean
121 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 global
130 • Default: false
131 • Type: Boolean
133 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 • packages are installed into the {prefix}/lib/node_modules folder, in‐
140 stead of the current working directory.
141 • bin files are linked to {prefix}/bin
143 • man pages are linked to {prefix}/share/man
145 <!-- automatically generated, do not edit manually --> <!-- see
147 lib/utils/config/definitions.js -->
148 global-style
151 • Default: false
152 • Type: Boolean
154 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 legacy-bundling
166 • Default: false
167 • Type: Boolean
169 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 strict-peer-deps
179 • Default: false
180 • Type: Boolean
182 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 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 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 package-lock
202 • Default: true
203 • Type: Boolean
205 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 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 omit
217 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
218 duction', otherwise empty.
219 • Type: "dev", "optional", or "peer" (can be set multiple times)
221 Dependency types to omit from the installation tree on disk.
224 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 If a package type appears in both the --include and --omit lists, then
230 it will be included.
231 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 ignore-scripts
239 • Default: false
240 • Type: Boolean
242 If true, npm does not run scripts specified in package.json files.
245 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 audit
254 • Default: true
255 • Type: Boolean
257 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 bin-links
267 • Default: true
268 • Type: Boolean
270 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
273 ecutables.
274 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 fund
282 • Default: true
283 • Type: Boolean
285 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 dry-run
294 • Default: false
295 • Type: Boolean
297 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 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 workspace
310 • Default:
311 • Type: String (can be set multiple times)
313 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 Valid values for the workspace config are either:
320 • Workspace names
322 • Path to a workspace directory
324 • Path to a parent workspace directory (will result to selecting all of
326 the nested workspaces)
327 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 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 workspaces
339 • Default: false
340 • Type: Boolean
342 Enable running a command in the context of all the configured
345 workspaces.
346 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 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
352 See Also
355 • npm help developers
356 • npm help package.json
358 • npm help install
360 • npm help folders
362 • npm help config
364 • npm help npmrc
366 October 2021 NPM-LINK(1)