Deploying a React App on Github Using gh-pages

Sometimes, after following the instructions from the official documentation page, We don’t get the expected results. And We ended up spending more time figuring out how to make things right.

I am sure your react app is ready and you probably want to deploy it, Here are some simple steps you can follow to deploy and show the world your amazing app.

This guide assumes some level of familiarity with Git and command line interfaces.

Before I walk you through the steps, I’d like to share the issues I encountered while deploying my first React App on Github, as well as how I resolved them.

Here are the issues I faced :

Missing the property “homepage” in package.json
When you omit this parameter, your index.html file will try to find a /static/js/…js resource under your root folder. As a result, the browser will return a Not Found error message when attempting to access this resource.
Enough talking. This is a screenshot from one of my react-app hosted on Github, after removing the homepage property from my package.json file

• Forgetting to clean up the cache directory This is another dilemma which can be fixed manually by removing node_modules/.cache/gh-pages folder or by running ./node_modules/gh-pages/bin/gh-pages-clean.js from your terminal [“check this in step 2 ”]. If you don’t clean up before deploying, you might end up building your project from a cached version of your app rather than the most recent updated version.

Finally, if you are using React-Router, you may encounter this problem

• The URL, likehttps://<github-username>.github.io/<repo-name> doesn’t work as expected. The reason behind this is that you are telling your app to look for a route “/repo-name” on the other hand your route is expecting something like “/” or “/some-route-name”. This will result in a Not Found page load error.

The list above contains the three problems I faced when I was deploying my react-app on Github using gh-pages for the first time.

Open now your terminal We are now ready to take off 🚀

Step 1. Install the gh-pages package

According to the documentation, gh-pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website.

Navigate to your project folder, then run the command below from your terminal to install the package. (Note: Make sure you run a version of Git ≥ 1.9 & Node ≥ 12)

npm install gh-pages --save-dev

Step 2. Update the “scripts” property field in package.json file

"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"predeploy": "npm run build",
"deploy": "./node_modules/gh-pages/bin/gh-pages-clean.js && gh-pages -d build"
},

The predeploy script will run automatically before deploy is run.

Step 3. Add “homepage” property in the same package.jsonfile

This property holds your link for a live preview

"homepage": ".",
// OR
"homepage": "https://<github-username>.github.io/<repo-name>",

The first option instructs your server to use relative paths in the current folder rather than absolute paths.The second option directly specifies the relative path. The two options have the same meaning.

Step 4. Add basename property to BrowserRouter

<BrowserRouter basename="/repo-name">
<App />
</BrowserRouter>,

The base URL for all locations. Our react-app will be served from a sub-directory on the GitHub server. If you omit this you will probably encounter a Not Found page load error which I discussed earlier at the beginning of this. A properly formatted basename should have a leading slash, but no trailing slash.

Step 5. Deploy your app

This command will create a branch named gh-pages and it will host your app.

npm run deploy

Important Notes:

• For windows users if you do get not recognized as an internal or external command, error, you can manually delete gh-pages from node_modules/.cache folder or run rm -rf node_modules/.cache/gh-pages then edit the “deploy” property and keep just the second part after the && This is how it should be after updating

"scripts": {
......
"deploy": "gh-pages -d build"
},

• In case your distribution folder is named differently replace build with the name of your distribution folder. For example, if it is dist, the deploy property value will become gh-page -d dist

You have seen how you can publish your React application to gh-pages with a few easy steps using gh-pages npm package.

If you liked the content, Kindly share and follow me on medium and on LinkedIn for more updates like this. You can also leave a comment in the section below.
Thank you very much.