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.
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.
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.
Then clone the repo from this fork to your development machine in the usual way.
git clone firstname.lastname@example.org: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.
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.
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.
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.