How to Use Forked NPM Dependencies in React

When using open-source software in your project, odds are you will run into an NPM dependency that doesn't do quite what you want it to. This dependency may be the 95% solution to the problem you're looking for, but maybe it is missing a feature that you need or has a bug that needs to be worked around for your use case. So what do you do in these types of situations? If your team doesn't have time to create your own custom solution to the problem, many times it is best to create a pull request to the repo in question. This can work very well in projects that are actively maintained, but it can sometimes take months or even years before some pull requests are merged into a project.

One way you can work around this limitation is to create your own fork of the project. You can change the project's code to your heart's delight and add that feature or fix that bug. Once complete, you can submit your pull request to the upstream open-source project ... but while you wait for this pull request to get merged, did you know that you can use the code within your fork now simply by altering your package.json file? In this guide, you will learn how to do just that!

Let's dive in.

In order to install a forked dependency into your project or app, you first need to create a fork! Creating a forked repository is very easy within GitHub. All you have to do is navigate to the repo of the project that you want to fork and select the Fork button. After you click this button, GitHub will create a copy of this repo within your user namespace. If the repo lived at user-name/custom-npm-dep, you now will have a new repo within your user namespace like this: <your-user-name>/custom-npm-dep.

With the project forked, the next step is to make code changes to facilitate the behavior you are looking for. Often, NPM projects have a CONTRIBUTING.md file that gives a detailed guide of how to successfully submit a pull request to the project. If this file exists, be sure to check it out!

After you've made the code changes that are needed, you are ready to submit a pull request. This can easily be done from within GitHub's UI. For more information and for a detailed guide, check this out.

Now you're in "pull request limbo"... Who knows how long it will take to get this pull request merged and for a new release of the dependency to come out?! But it's ok—there is a way around this waiting time. Let's take a look at an example package.json that is not using the forked project:

Currently, you are installing the custom-node-dep package directly from NPM. In order to use the fork, change this line in the configuration to:

The above configuration changes the version number of the custom-node-dep project to a direct link to the source code. If the project in question is a library that is well set up with a prepublish command, this is all you will need to do! However, if the project is not being installed correctly, you might have to build it manually. You can achieve this by ensuring that all build files within the forked repo are not hidden from source control after you build. How you do this is specific to the forked project. Usually, an npm run build command is sufficient to build the project. Whatever directory the build files are outputted to, you will need to make sure to remove from the .gitignore. This will ensure that the package.json downloads all of the needed build files when you npm install your app's dependencies.

And there you have it! Because NPM allows for direct downloading of packages from source control, you don't have to wait on pull requests to get merged, and your app can benefit from custom code changes now. This capability can allow your team to move fast to fix bugs coming from third-party dependencies.

For more information, check out the "dependencies" portion of the NPM documentation.