creating aliases with npm
I recently ran into a situation where a CICD pipeline was breaking because of an npm dependency. This is a common issue in web development as packages become deprecated or you’re forced to use an older version to be compliant with some enterprise requirements.
To fix the issue I used an npm alias. I thought this was super cool and so this post is going to briefly cover how it works.
The issue with the dependency
So before I go into how it works, I wanted to explain the problem/ I was using an older version of a dependency that had been deprecated. This hadn’t been an issue before, but my Continuous Integration Continuous Deployment(CICD) runner changed its version of NodeJS and this made the package fail. Fortunately, some quick googling found that I could use an upgraded package, but I had steps in a custom webpack setup that were set to using the older package. So to fix this, I created an alias!
What is an npm alias
If you use npm, you’ll know there are a lot of different features that you can use when installing and building your projects.
Npm aliases are when you install a package, but with an aliased name. So this means you can install the package, but instead of using the standard npm name, you can use your own!
To do this, you just run the following when doing your install:
npm install <ALIAS_NAME>@npm:<REAL_PACKAGE>@<PACKAGE_VERSION>
Here obviously the
ALIAS_NAME is how you reference it in your code, and then the
REAL_PACKAGE is the actual npm package you are installing.
So in our case, what I did was install the newer package under an alias for the older one. This made it so we didn’t have to change any code in our webpack setup.
One other good reason for using aliases is when you want to install an upgraded package, but want to test it first. If you install a newer version of the same package under an alias, then you can reference both old and new packages in your code. This specific example can be seen on egghead.io with a video at this link.
Example of it in action
So I wanted to finish out this post with an example. Since we’re getting close to Christmas I thought it’d be fun to use a Christmas npm package called days-until-christmas. This package basically just calculates the days until Christmas and then prints them to your console. I have a copy of this example in my GitHub repo npm-alias;
So to start with, the “days-until-christmas” package that was originally installed was version
1.1.2. If you go check npm, you’ll see that the newest version of this package is
So before we upgrade the package, lets test the new upgrade with an alias.
To do this, you can install the newer version with the following:
npm install days-until-christmas-next@npm:email@example.com
If you open your
package.json file you’ll see that the newer version is installed alongside the original:
Now in our code, we can reference both the old and new packages by just importing them (in this case I’m using “require” since its just a standalone JS file).
const daysUntilChristmas = require("days-until-christmas"); const daysUntilChristmasNext = require("days-until-christmas-next"); console.log("counting the days until Christmas with the original package"); console.log(daysUntilChristmas()); console.log("counting the days until Christmas with the new package"); console.log(daysUntilChristmasNext());
If you run this with
node HelloAlias.js you’ll see the following:
Now you can go ahead and uninstall the older version and reinstall the newest version to finish out the upgrade.
I know this post was relatively short, but it covers the basic concept and shows you a real example of how this works. I think npm aliases are really useful, and will definitely remember this in the future.