@darkobits/nlink

This tool is intended to be a suppliment to npm link in certain exotic cases where npm link doesn't do exactly what you want it to do.

It is especially useful for local development in large monorepos.

Install

npm install --save-dev @darkobits/nlink

Use

CLI

nlink has the same API as npm link, which has two modes of operation:

nlink [options]

Like npm link, this command should be run from a package you wish to link-to elsewhere.

Unlike npm link, which symlinks the entire package folder, nlink creates a folder and then symlinks only the following items into it:

• packge.json
• node_modules
• Anything declared in "files" in package.json.
• Anything declared in "bin" in package.json.

This creates a more "production-like" environment for the linked package, which helps to avoid issues that can sometimes arise when the entire project's source folder is linked.

To create a linkable package, but skip linking binaries:

nlink --bin=false

These behaviors are configurable. For a full list of options, see --help.

nlink <packageOrPattern>

Like npm link <package name>, but supports globbing to link several packages at once.

Patterns are matched against the contents of package-lock.json. If the project does not have a package-lock.json, or if the provided input does not match any dependencies therein, nlink will fall-back to treating the input as an explicit package name. In this case, if the input is a valid NPM package name, nlink will attempt to link to it. If an invalid name or glob pattern was provided, nlink will abort.

Because nlink matches against a project's lockfile, it is possible to link to transitive dependencies.

Note: This command uses minimatch under the hood, which was designed to work primarily with filesystems. Therefore, treat scoped packages like a directory structure.

For example, to match all @babel-scoped packages, you will need a globstar:

nlink '@babel/**'

To link @babel/core and any Babel plugins, but no other Babel packages:

nlink '@babel/{core,plugin*}'

Node API

Both functions used by the CLI are available for programmatic use. Please refer to the source for specifics.

Debugging

This package respects the LOG_LEVEL environment variable, and uses the standard NPM log levels. For more verbose output, try LOG_LEVEL=silly nlink ....

Additionally, you may pass --dry-run to either form of the command, which will automatically enable more verbose logging.

 

Happy linking!