privatenumber/link

🔗 A better `npm link`

^{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

^{Already a sponsor? Join the discussion in the Development repo!}

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.

Here's an example

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

1. 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

2. In the Consuming package

   1. 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.

   2. 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.

      Why hard links instead of symbolic links?

      
      

      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 the node_modules directory is resolved using the production tree we set up in Step 2.

3. 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 better npm ci.

Sponsors