How to fix a nodeJS package within your app. And send a pull request with your changes.
Sometimes you find an error or want to add features in a package that uses your app. So here I write about how you can change package:
- fork it
- work with NPM LINK (most important part🌶)
- change ES6 source code
- build package
- test it with your app
- and open PR
1. Find a repo link
First of all find a package that you want to change on https://www.npmjs.com/
Almost all packages contain repository.url in the package.json and placed on Github.
Click on the link (see screenshot) to open a package Github page.
2. Fork repo to your account
Press “Fork” button in the top right corner of the page to clone repo. When repo was forked, you will be redirected to your account.
3. Clone forked repo to your file system
For making changes in the module you should clone it to your file system. Press “clone or download”, ensure that your nickname present in a repository URL and copy it to the clipboard. I hope, that you setup ssh keys to your account already. If not, read how to do it here https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
After that open terminal and run following commands (oh, gosh… I hope that you have installed GIT CLI):
git clone firstname.lastname@example.org:nodkz/graphql-js.git
Repo will be cloned to folder with the repo name. So just enter to it with the following command:
4. Create new branch (IMPORTANT)
You should create a new branch, where you will make your changes. In this branch, you may do any number of commits as you wish (in future author of package may stash them into one commit when PR is accepted).
Remember that one branch should be equal to one your pull request. So if you want to make several features/bugfixes, you should create several branches. Every feature/bugfix should be landed in different pull requests.
You may choose any name for your branch and run following commands to create it:
git checkout master
git checkout -b patch-1
git push origin patch-1
5. Let’s LINK for package substitution, without changing imports in your app code (MAIN MAGIC, part 1) 🌶🌶🌶
NPM provide ability for the package linking (substitution). You may point any package from your_app/node_modules to the cloned repo.
The first step is creation a globally-installed symbolic link for cloned package repo. From folder of cloned package you should call the following command:
NPM reads package.json from a folder where you execute this command, gets a name of package and create symlink to npm’s internal folder (e.g. /usr/local/lib/node_modules/…). Internally will be called npm install and executed npm run build. So NPM prepared the cloned repo, which you can substitute the package in your app.
As you can see npm link got real package name graphql, rather than graphql-js folder name, where was cloned repo with module.
6. Let’s substitute package in our app (MAIN MAGIC, part 2) 🌶🌶🌶
It’s not cool when you want to fix some package in you app and change imports to relative paths of cloned module (after fix, you should return all imports back, agrrr). Or do symlinks by hands in node_modules; also often needs to change path in module’s package.json in `main` option, from lib to src (and do not forget to return it back); also may be your app and the package has different babel version/settings. Fatigue comes to me. 💩
So NPM provides proper easy way how to handle it:
npm link package_name
That’s all. From tons of packages in your app, you point to npm, what you want to change — only graphql package for the cloned repo. Internally npm removes folder your_app/node_modules/graphql and creates symlink from /usr/local/lib/node_modules/graphql. As you should remember, this folder was created in previous step 5.
7. Change cloned package code, build package and re-run your app
Just change what you want in the cloned package folder. Of course, in src folder. When you are done just, build package with your changes:
npm run build
I never met package that does not contain this command. This command usually fills lib or dist folder with code transpiled to es5.
So after the build, you may re-run your application. And your app takes new fixed code from cloned package. 🎉 Profit!
8. When you are almost Hero, and ready to send a Pull Request to be a real Hero 😉
Firstly, try to run tests via npm run test. If all is ok, or something like that, you may commit and push changes to your forked copy of package’s repo on Github:
git add .
git commit -a -m "commit message"
When push completes, open cloned repo on Github. Or you may again press “Fork” button on source repo and will be redirected to your existed copy of repo with your commit).
If you have light-yellow block on GitHub with “Compare & pull request” button, press it. Otherwise, you may select your last branch from the left side and press “New pull request” button. Let’s do it:
On opened page, read guidelines for contributing, add title for your PR and provide some description. Ta-dam, last call, we almost heroes! 😉 Press “Create pull request”.
That’s all! PR created successfully! You are awesome!
PS. There may be Travis check errors, merge conflicts, and other problems. But I think maintainer helps you to fix it.
PSS. When you no need any more cloned version of package.
Just run following commands:
npm unlink graphql — to remove symlink in your app from cloned package
npm install — to reinstall package from npmjs repository