Currently, I'm developing a component library at work that will be consumed by our company's internal applications. Part of this process requires bundling the library and making sure that it can be installed in other applications. Before publishing the package, however, I wanted to test importing the components from a local version of the bundled code.

Turns out that testing a local version of a package is a fairly straightforward process with yarn link (There is also an npm link equivalent). In this blog post, you will learn what npm/yarn link is, how it works, and how you can incorporate it into your own projects.

Note: This tutorial assumes that you already have a bundled version of your code using a module bundler like rollup.js or Webpack.

What is yarn link? 🔗

yarn link is a CLI command that allows developers to link a package in one project to other separate projects. This is particularly useful when you are developing a package in one repository but want to test a local version of that package in another application before publishing it. When a package is linked, you are able to test and build iteratively as revisions are automatically synced whenever a new bundle is generated.

Package linking is a two-step process:

Step 1

• Run yarn link in the root directory of the package that you want to link. This creates a global symbolic link (symlink) for the package and provides a reference point for the consuming project.

Step 2

• Run yarn link <package-name> in the root directory of the consuming project. This will create a symlink in the consuming projects node_modules folder that points to the globally-installed <package-name>.

Package Linking Example 📦

Assume you have two projects: my-cool-library and consuming-webapp.

my-cool-library provides a helper function, myCoolFunction, that you want to import into the consuming-webapp project.

1. In the root directory of my-cool-library run the following command to create the global symlink:

   yarn link
   

2. In the root directory of consuming-webapp run the following command to link to my-cool-library locally:

   yarn link my-cool-library
   

   • Now if you were to navigate to the node_modules folder in consuming-webapp, you would see the symlink point to the local version of my-cool-library.

3. With the linking process successfully completed, you could now import the myCoolFunction helper function in consuming-webapp like so:

   import { myCoolFunction } from "my-cool-library";
   

Note: By default, package dependencies linked in this way are not saved to package.json. This is based on the assumption that the intention is to have a link stand in for a regular non-link dependency. This means that your IDE may show an error when attempting to import from the package, however, you can ignore this and your code should render just fine.

Unlinking a Package 🔓

yarn unlink is an aptly named command that handles removing (unlinking) the symlinked package. Similar to the linking method, unlinking a package is also a two-step process that is essentially a reversal of the linking workflow:

Step 1:

• Run yarn unlink in the root directory of the package that you want to dissociate.

Step 2

• Run yarn unlink <package-name> in the root directory of the consuming project.

Based on the example in the previous section, that would mean running yarn unlink in the my-cool-library project and yarn unlink my-cool-library in the consuming-webapp project.

Both steps combined remove the global symlink for the package and delete the reference point from the consuming project, therefore completing the unlinking process. Unlinking is important to remember as a cleanup mechanism when you're done performing local testing.

El Fin 👋🏽

Hopefully, you learned something new about how you can leverage package linking to test packages locally.

If you enjoy what you read, feel free to like this article or subscribe to my newsletter, where I write about programming and productivity tips.

As always, thank you for reading, and happy coding!

Resources

• npm link

• yarn link and yarn unlink

• Brad Garropy - 🔗 developing npm packages locally

• LevelUp Tuts - How to Use a Local Javascript Package in a Real Project