Verdaccio what?!

verdaccio-link is a thing I made that takes some of the frustration out of linking together npm packages for local development.

If you're like me and you have 5-6 projects open at a time, each interlinking with each other in complex and often multi-layered ways, you will have noticed that the behavior of npm link will sometimes be somewhat... erratic.

For one thing, what actually exists in your symlinked module folder will be different from what exists in the packaged project. And symlinking effects module resolution in ways that more often and not require workarounds in webpack/tsconfig.

Turns out these irritating behaviors add upp to a critical issue when dealing with testing in mocha and enzyme. A symlinked package will always resolve enzyme to a version in it's own node_modules, even if it would've been decoupled by the consuming project. And if you move enzyme into the peerDependencies, it simply doesn't resolve at all. For mocha, unlike webpack and tsconfig, there seems to be no workaround for this.

Rather than being stuck in a loop of publishing and unpublishing this dependency to gemfury everytime I made a minor debugging change, I spend this friday afternoon building this thing.

Follow the instructions below to try it out!

Install verdaccio

Verdaccio is a local npm registry that you can setup on your computer with zero conf.

We will use it as a sort of linking pool for local development packages.

The first thing you must do to utilize verdaccio-link is install verdaccio globally.

$ npm i -g verdaccio

Then start a local instance of the server, do:

$ verdaccio

Now you have verdaccio running!

Linking a package to the repository

Let's say we have two packages, my-application and my-dependency.

The first thing we must do is "link" my-dependency to verdaccio.

Start by installing verdaccio-link in my-dependency:

$ npm i -D @fbinhouse/verdaccio-link

Then write a script entry in package.json for linking the package:

...
"scripts": {
    "verdaccio:link": "verdaccio-link"
}
...

Now simply run the following command every time you want to "link" the package to the repository.

$ npm run verdaccio:link

If you want to rebuild the package every time you link it, just add your build commands to prepublishOnly as per usual.

Linking a package from the repository to our project

First of all, we need to install verdaccio-link in my-application:

$ npm i -D @fbinhouse/verdaccio-link

Then, we need to add the following to the scripts of our package.json:

...
"scripts": {
    "verdaccio:relink": "verdaccio-link @fbinhouse/my-dependency"
}
...

To link the dependency to our application project, we simply do:

$ npm run verdaccio:relink

If we have more than one dependency we can just stack them at the end like so:

...
"scripts": {
    "verdaccio:relink": "verdaccio-link @fbinhouse/my-dependency @fbinhouse/some-other-dependency""
}
...

Custom service URL

If you for some reason are running verdaccio on a non-standard URL, you can use the -a or --address flag to set a custom server endpoint.

$ verdaccio-link -a http://my-custom-repository.com

Specifying a directory

When running from outside of the root of the project which we want to target, use the -d or --directory flag to set a path to the project root (must contain a package.json).

$ verdaccio-link -d ../ @fbinhouse/some-dependency

verdaccio-config.json

Instead of specifying command line args you put them in a json file:

{
    "directory": "../",
    "address": "http://my-custom-repository.com"
}

Then specify the location of that file with the -c or --config arg:

$ verdaccio-link -c ./verdaccio-config.json