I kept getting confused with the link/unlink order mostly because I was getting myself into weird situations with permission issues where I would have the package not available anymore.

There are some good resources out there for linking but I was struggling at first to find the documentation for unlinking. I’ve written down the exact steps for both so that future devs never struggle like I did.

Lets say we have an npm package that we are working on locally, lets call it cowabunga. Our project structure looks something like this:

cowabunga package folder structure

And it’s package.json file looks something like this:

You’ll notice that this package has its own node_modules folder - this is where I kept getting tripped up. I would switch branches (where my package lived) and the node_modules folder would disappear. When I would go to unlink, npm was throwing permissions errors that went something like this:

npm ERR! enoent ENOENT: no such file or directory, access ‘my_project/node_modules/cowabunga/node_modules/react’

In order to avoid this, you have to follow the linking/unlinking order otherwise npm will try to unlink folders that no longer exist. Seems pretty basic but it was surprisingly tedious to figure out.

Linking:

First, in the cowabunga folder (where package.json is):
npm link

Then in the project you want to include cowabunga in:

npm link cowabunga

Unlinking:

Before switching branches and/or removing any node modules from the package itself (in my project, this includes running learn clean which removed the node_modules folders)

First, in the project:
npm unlink --no-save cowabunga

Second, in the package:
npm unlink

Note: order is important!

Where I kept running into issues is switching branches and then the symlink couldn’t find the package anymore so you were stuck in this weird state where you couldn’t link anything or unlink anything because the folders don’t exist. When this happens, check out your original branch and start from the beginning with linking the package and the project.

🤙

Bonus:
You can also run
npm install -g i .
in your package folder to install it globally 🎉