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

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

Git worktree - guide to flexible folder structure

Published on
As always, let's start with a story why I have written this one down. I have been using git for almost 5 years now and in one of my work places I had to work on the same project but different features in parallel.  Switching between branches back and forth was a costly operation given that I didn't discover commit amend until recently. Even though I'd have discovered commit amend, I'd still have did this. Still did what? I can sense that question deep from your throats. So, whenever I am in a situation to work on multiple features or a feature and a bug fix, I'd have two clones of my repo each with different branches, Whenever a feature is merged or the fixes are merged, I'll delete the clone in my machine and branch in my origin (Gitlab / Github etc.,) Recently when I started writing these git articles, my manager suggested me to learn about Git Worktree and it'll be useful. And when I got free and good understanding of git commit, rebase and stuff, I decid
Post a Comment
Read more

Confluence: 5 quick things that you need

Published on
As part of my work experiments, this week I would like to write down the things that one needs to know in confluence that can up-skill their documentation works. I will cover the following 5 things, How to Anchor link a title? How to Anchor link to a section? How to create a dashing dashboard? Panel - Confluence Macro Layouts - Confluence Tools Content by Label - Confluence Macro 1. How to Anchor link a title? This is the most required thing. Most useful when one has to refer to a section internally on the same confluence page. Let's consider you have a page with three different sections and titles as shown below, In this, if you want to add an internal anchor from a text in paragraph 3 to a title in paragraph 1, you can add it as follows, Choose the word that needs Anchor Click on the link icon from the Toolbar above In the link box, enter #Page Title 1 Click Insert That is it. Your anchor from the selected text to Page Title 1 is ready. This can be tested out in the preview itsel
Post a Comment
Read more