The idea of npm link is great - link a package under development into another package that uses it, allowing you test the changes being made to the package being linked. The problem with npm link is that it is a notorious PITA because of two things:

1. It's just a symlink to the package source: meaning that it has a full-blown node_modules (not deduped), causing problems with local package resolution.
2. It's just a symlink to the package source: meaning require resolution happens against the symlinks real path, which screws everything up most of the time.

So in most cases npm link simply does not work.

This package (xlink) tries to provide a dev time mechanism that allows you to "xlink" a package under development into another package that uses it, allowing you to test the changes being made to the package under development. So, the "use case" is basically the same as npm link.

The difference is that it doesn't use any symlinks and so doesn't have either of the issues listed above. It watches the source in the xlinked package (under dev) and "synchronizes" any changes as they happen. But, it does NOT touch the contents of the node_modules directory.

Install

npm install -g xlink

Usage

xlink requires you to start by installing the package(s) under development (e.g. "A") into the package in which you will be testing the changes to "A" (e.g. "B"). Once "A" is installed, "B" will have a properly deduped "A" in it's node_modules dir. Now you can xlink in "B", telling it to watch for and synchronize source changes in "A" into node_modules/A.

e.g.

npm install "A" in "B":

tfennelly@diego:~/projects/B $ npm install ../A

xlink "A" in "B" and make a source change to ../A/index.js:

tfennelly@diego:~/projects/B $ xlink ../A
Watching for changes in /Users/tfennelly/projects/A
    ./index.js changes synchronized.

In the above case xlink sits and watches for changes in ../A.

Note: You can also xlink using the package name (i.e. not a relative path). This works so long as the package being xlinkd has been npm linkd.

Note: If ../A/package.json contains a files spec, that spec will be honoured i.e. only files covered by the spec will be synchronized.

Note: You can specify multiple packages to be "xlinked" e.g. xlink ../X ../Y ../Z