npm-link | What NPM won't tell you!

Hello readers. So back with another easy yet unexplored feature of npm/yarn packages.

We as frontend developers / SDK developers, have to deal with more than one repositories where we actually code contribute. Most SDK developers would know this already or they use the not-so-well documented 'npm link' command.

/**
 * @disclaimer
 * Please read this post fully before executing any command. My scenario might not be the same as yours.
 * This article below uses a repo from my current workplace as an example which is open-source and does not violate the Cisco Confidentiality Policies
*/

To make this article easier to understand, some representations,

• Host - Package that needs another local package as part of its node modules. Let's assume the path to this package is ~/Documents/Repos/demo-app
• Adhoc - Local package that is added into another package as a dependency. Let's assume the path to this package is ~/Documents/Repos/semver-monorepo

What is npm link?

This is a command offered by npm to link packages locally.  This uses the Symlink mechanism underneath to link an Adhoc package into the node_modules of the Host package. 

How to link an Adhoc package?

As for how to link a local package using the npm link command, ensure the following:

• You have your host package cloned, dependencies installed and built. 
• You have your Adhoc package cloned,  dependencies installed and built

Now, to link these, execute the following command with appropriate values,

This command links the Adhoc package in the respective folder under node_modules. So, if the package.json has a name like @infotron/semver-monorepo, it’ll be symlinked under ~/Documents/Repos/demo-app/node_modules/@infotron/semver-monorepo. Simple as that. Let's look at it with a simple command,

If you see, when we execute the "readlink" command, it gives the path to the Host package folder. Now every time something in the Adhoc package is changed, both the Adhoc package and the Host packages need to be rebuilt. 

What if the Adhoc package is a yarn workspace?

Read about yarn workspaces here: https://classic.yarnpkg.com/lang/en/docs/workspaces/

This is when some of us get stuck or confused but the easiest way to think about it is, where does the package.json of a workspace exists? That becomes a target. Let me take an example from my current workplace and the primary SDK that I work on which is the Cisco Webex Javascript SDK. This SDK has several dependencies under @webex/*, which reside in the same repo as the webex package. Each one of those dependencies is a folder inside the SDK repo itself. 

This is how the package looks roughly,

Notice that it's a mono repo or in other words, a yarn workspace and each of the packages gets published separately. This means each of these packages is already optimised for installing separately and using. Therefore, what does one do to test such mono repo packages locally?

Testing local packages of a mono repo

In such scenarios, one can be sure that we do not need the entire package to be locally linked. Only a few of those would be changed and only those need to be linked.

In our scenario, let's assume we only need to locally link the @webex/plugin-callings package and @webex/plugin-meetings package.

Step 1: Install the actual dependency

The actual webex dependency in this example needs to be installed,

Now, when you list the node_modules, you'll see the below,

Step 2: Linking local dependencies

Now, let's try to link the local packages for @webex/plugin-callings and @webex/plugin-meetings,

Step 3: Check for symlinks

In this step, we will ensure that the packages are symlinks,

That confirms the packages are properly linked and that is how we handle the mono-repo situations.

Once this linking is done, every time a change happens in one of those packages, the Host package as well as the Adhoc package needs to be re-built.

Defect with this command

The only defect in using this command is that every time an npm install happens or when the node_modules folder gets removed, one has to do npm link again for all the locally linked packages. 

The "link:" attribute

This attribute is very helpful in the above scenarios where one has to frequently delete and install node_modules again provided the host package uses yarn packages instead of npm

Where to add the "link:" attribute and How?

This attribute goes inside the package.json of the Host package.

Let's look at an example of linking a regular ad-hoc package as well as a mono repo ad-hoc package,

Here, to link the following ad-hoc packages,

• @webex/plugin-meetings
• @webex/plugin-callings
• @infotron/semver

we'll make the following changes,

Now, when we do yarn install (remember - npm install does not support link attribute and would throw EUNSUPPORTEDPROTOCOL error) the adhoc packages that are locally linked alone would be replaced with symlinks and others would be installed as it is. 

Note - For some of the inter-dependent packages, yarn is going to ask for a package resolution to choose a version number for them. 

Since we have the local links mentioned in the package.json itself, no matter how many times the node_modules is removed, we won't have to worry about linking the adhoc package in the host package manually using npm link. The post is open for comments in case of any mistakes.