Skip to main content

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

Published on

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?


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.

Labels:

Comments

Post a Comment

Popular posts from this blog

WebRTC - What the heck?

Published on
Over the past few weeks, I happened to work on stuff that enabled me to understand what WebRTC is and how useful it is.  The full form? Web R eal- T ime C ommunication The history It's first release was by 2011. If you want to know more, well, please read the wikipedia . WebRTC  has been a boon to web developers who want to build streaming applications or video calling applications. As you move downward, you'll just may be understand how WebRTC works but nothing technicals.  The story Let's begin with a short story. Long long ago, so long ago, nobody knew how long ago, there lived two shop keeper farmers John & Finch. It was that old point in time when barter system was a thing and money wasn't invented.  These shopkeepers lived in different cities across a river and the cities were connected by a rock solid bridge. Like how the golden gate connects the San Francisco city and the Marin County. Finch is a very private person and takes hard time to trust people. John
2 comments
Read more

Git - How to drop a commit in history?

Published on
Back after a while with another git magic. We already have seen how to get rid of the top most commit in this article ->  Git magic - Make commits disappear First of all, it's one of the not so recommended way of doing it and more than that, it can only get rid of sequential commits from latest. I recently happened to get into a scenario where I had to drop a commit in the history by keeping the latest ones. As part of that exploration, presenting you this article. /**  *  @disclaimer  * Please read this post fully before executing any command. My scenario might not be same as yours. */ To my greatest surprise, I didn't know a git rebase could do this. Please continue to read to know how. The steps are simple, Count until the commit line you need to drop using git log Do an interactive rebase and you're done.  Let me explain step by step. 1. Look at the commit log & count commits This is the first step. First let's list the commits using the following command,  
Post a Comment
Read more

Git - Removing a file from a commit

Published on
Once again, another git magic that might be of help to some of you. This research came up when I accidentally added a couple of unwanted files and wanted to remove them from a commit. We all know that to update an existing commit, we shall follow this git magic to amend commits . However, how do we drop changes to a particular file in a commit? While that is easy, it is also tricky. This blog post covers scenarios and respective commands that help you understand what should be done. /**  *  @disclaimer  * Please read this post fully before executing any command. My scenario might not be the same as yours. */ There are two scenarios to be handled here, Remove a newly added file Remove changes to an existing file Let's look at them separately, Remove a newly added file This is the scenario where an unwanted file added to the commit. This file might be some config.json that got generated while doing a research on a new testing tool or a bundling tool. Such scenarios are easier. 1. Re
Post a Comment
Read more