1NPM-LINK(1) NPM-LINK(1)
2
6 npm-link - Symlink a package folder
7 Synopsis
9 npm link [<package-spec>]
10 alias: ln
12 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 Package linking is a two-step process.
18 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 npm
23 link uses the global prefix (see npm prefix -g for its value).
24 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 Note that package-name is taken from package.json, not from the direc‐
30 tory name.
31 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 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 For example:
41 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 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 You may also shortcut the two steps in one. For example, to do the
52 above use-case in a shorter way:
53 cd ~/projects/node-bloggy # go into the dir of your main project
55 npm link ../node-redis # link the dir of your dependency
56 The second line is the equivalent of doing:
58 (cd ../node-redis; npm link)
60 npm link redis
61 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 Note that in this case, you are referring to the directory name, node-
66 redis, rather than the package name redis.
67 If your linked package is scoped (see npm help scope) your link command
69 must include that scope, e.g.
70 npm link @myorg/privatepackage
72 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 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 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 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 npm link --workspace <name> will create a global link to the specified
96 workspace(s).
97 Configuration
99 save
100 • Default: true unless when using npm update where it defaults to
101 false
102 • Type: Boolean
104 Save installed packages to a package.json file as dependencies.
107 When used with the npm rm command, removes the dependency from pack‐
109 age.json.
110 Will also prevent writing to package-lock.json if set to false.
112 save-exact
114 • Default: false
115 • Type: Boolean
117 Dependencies saved to package.json will be configured with an exact
120 version rather than using npm's default semver range operator.
121 global
123 • Default: false
124 • Type: Boolean
126 Operates in "global" mode, so that packages are installed into the pre‐
129 fix folder instead of the current working directory. See npm help fold‐
130 ers for more on the differences in behavior.
131 • packages are installed into the {prefix}/lib/node_modules folder,
133 instead of the current working directory.
134 • bin files are linked to {prefix}/bin
136 • man pages are linked to {prefix}/share/man
138 install-strategy
141 • Default: "hoisted"
142 • Type: "hoisted", "nested", "shallow", or "linked"
144 Sets the strategy for installing packages in node_modules. hoisted (de‐
147 fault): Install non-duplicated in top-level, and duplicated as neces‐
148 sary within directory structure. nested: (formerly --legacy-bundling)
149 install in place, no hoisting. shallow (formerly --global-style) only
150 install direct deps at top-level. linked: (experimental) install in
151 node_modules/.store, link in place, unhoisted.
152 legacy-bundling
154 • Default: false
155 • Type: Boolean
157 • DEPRECATED: This option has been deprecated in favor of --install-
159 strategy=nested
160 Instead of hoisting package installs in node_modules, install packages
163 in the same manner that they are depended on. This may cause very deep
164 directory structures and duplicate package installs as there is no de-
165 duplicating. Sets --install-strategy=nested.
166 global-style
168 • Default: false
169 • Type: Boolean
171 • DEPRECATED: This option has been deprecated in favor of --install-
173 strategy=shallow
174 Only install direct dependencies in the top level node_modules, but
177 hoist on deeper dependencies. Sets --install-strategy=shallow.
178 strict-peer-deps
180 • Default: false
181 • Type: Boolean
183 If set to true, and --legacy-peer-deps is not set, then any conflicting
186 peerDependencies will be treated as an install failure, even if npm
187 could reasonably guess the appropriate resolution based on non-peer de‐
188 pendency relationships.
189 By default, conflicting peerDependencies deep in the dependency graph
191 will be resolved using the nearest non-peer dependency specification,
192 even if doing so will result in some packages receiving a peer depen‐
193 dency outside the range set in their package's peerDependencies object.
194 When such an override is performed, a warning is printed, explaining
196 the conflict and the packages involved. If --strict-peer-deps is set,
197 then this warning is treated as a failure.
198 package-lock
200 • Default: true
201 • Type: Boolean
203 If set to false, then ignore package-lock.json files when installing.
206 This will also prevent writing package-lock.json if save is true.
207 omit
209 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
210 duction', otherwise empty.
211 • Type: "dev", "optional", or "peer" (can be set multiple times)
213 Dependency types to omit from the installation tree on disk.
216 Note that these dependencies are still resolved and added to the pack‐
218 age-lock.json or npm-shrinkwrap.json file. They are just not physically
219 installed on disk.
220 If a package type appears in both the --include and --omit lists, then
222 it will be included.
223 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
225 ment variable will be set to 'production' for all lifecycle scripts.
226 include
228 • Default:
229 • Type: "prod", "dev", "optional", or "peer" (can be set multiple
231 times)
232 Option that allows for defining which types of dependencies to install.
235 This is the inverse of --omit=<type>.
237 Dependency types specified in --include will not be omitted, regardless
239 of the order in which omit/include are specified on the command-line.
240 ignore-scripts
242 • Default: false
243 • Type: Boolean
245 If true, npm does not run scripts specified in package.json files.
248 Note that commands explicitly intended to run a particular script, such
250 as npm start, npm stop, npm restart, npm test, and npm run-script will
251 still run their intended script if ignore-scripts is set, but they will
252 not run any pre- or post-scripts.
253 audit
255 • Default: true
256 • Type: Boolean
258 When "true" submit audit reports alongside the current npm command to
261 the default registry and all registries configured for scopes. See the
262 documentation for npm help audit for details on what is submitted.
263 bin-links
265 • Default: true
266 • Type: Boolean
268 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
271 ecutables.
272 Set to false to have it not do this. This can be used to work around
274 the fact that some file systems don't support symlinks, even on osten‐
275 sibly Unix systems.
276 fund
278 • Default: true
279 • Type: Boolean
281 When "true" displays the message at the end of each npm install ac‐
284 knowledging the number of dependencies looking for funding. See npm
285 help fund for details.
286 dry-run
288 • Default: false
289 • Type: Boolean
291 Indicates that you don't want npm to make any changes and that it
294 should only report what it would have done. This can be passed into any
295 of the commands that modify your local installation, eg, install, up‐
296 date, dedupe, uninstall, as well as pack and publish.
297 Note: This is NOT honored by other network related commands, eg dist-
299 tags, owner, etc.
300 workspace
302 • Default:
303 • Type: String (can be set multiple times)
305 Enable running a command in the context of the configured workspaces of
308 the current project while filtering by running only the workspaces de‐
309 fined by this configuration option.
310 Valid values for the workspace config are either:
312 • Workspace names
314 • Path to a workspace directory
316 • Path to a parent workspace directory (will result in selecting all
318 workspaces within that folder)
319 When set for the npm init command, this may be set to the folder of a
322 workspace which does not yet exist, to create the folder and set it up
323 as a brand new workspace within the project.
324 This value is not exported to the environment for child processes.
326 workspaces
328 • Default: null
329 • Type: null or Boolean
331 Set to true to run the command in the context of all configured
334 workspaces.
335 Explicitly setting this to false will cause commands like install to
337 ignore workspaces altogether. When not set explicitly:
338 • Commands that operate on the node_modules tree (install, update,
340 etc.) will link workspaces into the node_modules folder. - Commands
341 that do other things (test, exec, publish, etc.) will operate on
342 the root project, unless one or more workspaces are specified in
343 the workspace config.
344 This value is not exported to the environment for child processes.
347 include-workspace-root
349 • Default: false
350 • Type: Boolean
352 Include the workspace root when workspaces are enabled for a command.
355 When false, specifying individual workspaces via the workspace config,
357 or all workspaces via the workspaces flag, will cause npm to operate
358 only on the specified workspaces, and not on the root project.
359 This value is not exported to the environment for child processes.
361 install-links
363 • Default: false
364 • Type: Boolean
366 When set file: protocol dependencies will be packed and installed as
369 regular dependencies instead of creating a symlink. This option has no
370 effect on workspaces.
371 See Also
373 • npm help "package spec"
374 • npm help developers
376 • package.json ⟨/configuring-npm/package-json⟩
378 • npm help install
380 • npm help folders
382 • npm help config
384 • npm help npmrc
386 November 2023 NPM-LINK(1)