link
v2.1.1
Published
A better npm link
Downloads
52,185
Readme
npx link
A safer and enhanced version of npm link
.
Why is npm link
unsafe? Read the blog post.
Features
- 🔗 Link dependencies without removing previous links
- 🛡 Only resolves to local paths
- 🔥 Config file quickly linking multiple packages
- 💫 Deep linking for quickling linking multilple packages
Terminology
Dependency package
The package getting linked. This is usually a library.
Consuming package
The project you want to link the Dependency package as a dependency of. This is usually an application.
consuming-package/node_modules/dependency-package
→dependency-package
Usage
Linking a package
From the Consuming package directory, link the Dependency package:
npx link <dependency-package-path>
This creates a symbolic link inside the node_modules
of Consuming package, referencing the Dependency package.
🛡️ Secure linking
Unlike
npm link
, it doesn't install the Dependency package globally or re-install project dependencies.
Publish mode
Using symbolic links may not replicate the exact environment you get from a standard npm install
. This discrepancy primarily arises from symlinked packages retaining their development node_modules
directory. This can lead to issues, especially when multiple packages depend on the same library.
In a production environment, npm install
detects common dependencies and installs only one instance of a shared dependency. However, when there's a symbolic link to the development directory of a dependency, separate copies of those dependencies are resolved from the development node_modules
.
Let's say there's an App A with a dependency on Package B, and they both depend on Library C:
Production environment
npm install
detects that both App A and Package B depends on Library C, and only installs one copy of Library C for them to share.Symbolic link environment
App A has its copy of Library C, and Package B also has its development copy of Library C—possibly with different versions. Consequently, when you run the application, it will load two different versions of Library C, leading to unexpected outcomes.
Publish mode helps replicate the production environment in your development setup.
Setup instructions
In the Dependency package, run
npm pack
to create a tarball:cd dependency-package-path npm pack
This generates a tarball (
.tgz
) file in the current directory. Installing from this simulates the conditions of a published package without actually publishing it.Tip: You can skip this step if this dependency is already installed from npm and there are no changes to the dependency's
package.json
In the Consuming package
Install the Dependency tarball from Step 1
npm install --no-save <dependency-tarball-path>
This sets up the same
node_modules
tree used in a production environment.Link the Dependency package
npx link publish <dependency-package-path>
This creates hard links in
node_modules/dependency
to the specific publish assets of the Dependency package.Another issue with the symlink approach is that Node.js, and popular bundlers, looks up the
node_module
directory relative to a module's realpath rather than the import path (symlink path). By using hard links, we can prevent this behavior and ensure that thenode_modules
directory is resolved using the production tree we set up in Step 2.
Start developing!
Any changes you make to the Dependency package will be reflected in the
node_modules
directory of the Consuming package.Note: If the Dependency package emits new files, you'll need to re-run
npx link publish <dependency-package-path>
to create new hard links.
Configuration file
Create a link.config.json
(or link.config.js
) configuration file at the root of the Consuming package to automatically setup links to multiple Dependency packages.
Example link.config.json:
{
"packages": [
"/path/to/dependency-path-a",
"../dependency-path-b"
]
}
The configuration has the following type schema:
type LinkConfig = {
// Whether to run `npx link` on dependency packages with link.config.json
deepLink?: boolean
// List of dependency packages to link
packages?: string[]
}
Note: It's not recommended to commit this file to source control since this is for local development with local paths.
To link the dependencies defined in link.config.json
, run:
npx link
Deep linking
By default, npx link
only links packages in the Consuming package. However, there are cases where the Dependency packages also needs linking setup.
Deep linking recursively runs link on every linked dependency that has a link.config.json
file.
Enable with the --deep
flag or deepLink
property in link.config.json
.
npx link --deep
FAQ
Why should I use npx link
over npm link
?
Because npm link
is complicated and dangerous to use. And npx link
offers more features such as Publish mode.
How do I remove the links?
Run npm install
and it should remove them.
npm install
enforces the integrity of node_modules
by making sure all packages are correctly installed. Reverting the links is a side effect of this.
Why does npx link
point to ln
?
You must use npx v7 or higher. Check the version with npx -v
.
In the obsolete npx v6, local binaries take precedence over npm modules so npx link
can point to the native link
/ln
command:
$ npx link
usage: ln [-s [-F] | -L | -P] [-f | -i] [-hnv] source_file [target_file]
ln [-s [-F] | -L | -P] [-f | -i] [-hnv] source_file ... target_dir
link source_file target_file
To work around this, install link
globally first:
$ npm i -g link
$ npx link
Related
npx ci
- A betternpm ci
.