How to fork a dependency and use it locally in a project

A guide to help the process of modifying a 3rd party dependency—from forking, using Yarn to link locally to submitting a PR.

Chris Masters
Jun 9, 2018 · 5 min read

Introduction

This is a how to illustrating how to work on a 3rd party package, it assumes you are using yarn as your project’s package manager.

In this example I’m using the ember-resolver as the 3rd party library and this Ember.js application as the project I want to use it in.

A gentle warning

It might be worth checking a release which has resolved this issue is available if you are using Yarn v1.7.0 to avoid being bitten by any linked file errors. A fix is already available in the nightly builds so it’s very likely to.

If not, a solution is to downgrade to Yarn v1.6.0 until then, which can easily be done like this (assuming you’re using homebrew on a mac).

brew unlink yarn
brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/76215230de5f7f7bee2cfcdd7185cf49d949862d/Formula/yarn.rb
brew switch yarn 1.6.0_1

Forking the 3rd party library

First, create a duplicate version of the library in your account by using the fork button on the right hand side of the Github interface.

Using the fork button on the right hand side

Then clone the repo from this fork to your development machine in the usual way.

git clone git@github.com:chrism/ember-resolver.git

Linking with yarn

Yarn allows linking to libraries which seems perfect for the task.

For development, a package can be linked into another project. This is often useful to test out new features or when trying to debug an issue in a package that manifests itself in another project.

Make sure you are in the project directory of the 3rd party library you want to link and run yarn link .

Following those logged instructions now from the directory of the project you want to use this linked version in you can now update the package to use the linked local version instead by running yarn link "ember-resolver".

Confirming the link is working

I was a little surprised that looking at my package.json file nothing changed, it still displayed "ember-resolver": "^4.0.0" in the dependencies as before.

However, a look in the node_modules directory shows that the symlink was working.

ember-resolver -> ../../ember-resolver

Using the local version in your project

At this point running the application gives an error saying that some dependencies are missing.

Running yarn doesn’t solve this in the directory doesn’t solve this.

It’s necessary to run yarn in the directory of the 3rd party library first to install the dependencies there then the application should run.

Making changes to the local version

Once running the application using the local version is possible to make it easier to submit a pull request (PR) start by creating a new branch for the feature or bug fix.

Giving a descriptive name for the branch helps others to quickly understand the purpose of the PR. For example,

git checkout -b added-config-type-to-mu-config

On this new branch any changes to the files you are editing are immediately reflected in the application which are linked to it.

This leads to an efficient workflow without needing to worry about syncing between the application and the library and possible caching issues.

Pushing new branch to Github

Once the new code has been included and checked to work the new branch can be pushed to the remote repository of the forked library. For example,

git add -A
git commit -m “Added config type to module unification config”
git push origin added-config-type-to-mu-config

Note that by pushing to origin and appending the new branch name it will automatically create a matching branch on Github before pushing the files.

Submitting a pull request

Github helps to create the PR, just first ensure you are on the right branch and then use the ‘New pull request’ button.

Ensure you are on the right branch the using the New pull request button

Make sure to add a clear message to the PR to help the maintainer understand the motivations for creating it—ideally including a link to a previously created issue.

Unlinking and using the forked remote dependency

Although the goal is to start using the 3rd party library with the changes released in a new version this could take some time, depending on the speed of the project the PR was submitted to.

In the meantime instead of using a local version having pushed a branch to the forked repository it’s possible to start using that.

One benefit of this is that it no longer relies on the local machine and can be shared with others.

In a similar way to linking Yarn allows you to unlink too.

Instead use the github url of the fork of the library. Include the branch you were working on too, for example

yarn upgrade ember-resolver@https://github.com/chrism/ember-resolver.git#added-config-type-to-mu-config

Updating to the new release of the library

Once the PR has been successfully merged then you can choose to either start using that url immediately, for example

yarn upgrade ember-resolver@https://github.com/ember-cli/ember-resolver.git

Or wait until a new version has been release on npm, when you can upgrade the package as usual.

Conclusion

Using Yarn with link has made it much more straightforward to work with local dependencies.

If you find yourself needing to make an update to a dependency don’t be too worried about forking the library and having a go.

Hope this proves useful to others, let me know if you have any feedback. Thanks.

Chris Masters

Written by

C'est anglais mais c'est bon.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade