A safer and enhanced version of npm link
.
Why is npm link
unsafe? Read the blog post.
Already a sponsor? Join the discussion in the Development repo!
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
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.
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.
Publish mode helps replicate the production environment in your development setup.
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.
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.
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
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
npx link
over npm link
?Because npm link
is complicated and dangerous to use. And npx link
offers more features such as Publish mode.
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.
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
npx ci
- A better npm ci
.