Publish your React app on a live URL hosted on GitHub Pages

Summary

In this article we will deploy a create-react-app (with routing) to a live URL hosted on GitHub Pages, we will configure the application so that it serves from a sub-folder and our routing works as expected. Some prerequisites before we get started;

A GitHub account

Node ≥ 6 npm ≥ 5.2

Note: Please replace my GitHub username 8eni with your own throughout the article.

We will achieve our goal in 3 easy steps:

Create GitHub repository & add create-react-app application (skip to step 2 if you already have) Add Routing to our application Add GitHub Pages & deploy the application

Before we dive in, let’s understand what GitHub Pages is.

Websites for you and your projects, hosted directly from your GitHub repository. Just edit, push, and your changes are live.

Create GitHub repository and add React application

Navigate to your GitHub account and create a new repository. I’ve called mine my-react-app.

GitHub — Create new repository

Clone our repository locally and run create-react-app from the same directory you cloned too.

$: git clone https://github.com/8eni/my-react-app.git

$: npx create-react-app my-react-app

Note: npx is a package runner tool that comes with npm 5.2+.

Add Routing to our application

For routing, we will use the react-router-dom package. Navigate to our new directory and install the package

$: cd my-react-app

$: npm install react-router-dom

Then import HashRouter, Route, and Link from react-router-dom into our application. It is important to note we are using HashRouter here as without it on browser refresh, we would get a 404 on our GitHub pages live URL.

// App.js import React, { Component } from 'react';

import { HashRouter, Route, Link } from "react-router-dom";

Next replace the render() method in App.js with the following.

// App.js render() {

return (

<HashRouter basename='/'>

<div>

<ul>

<li><Link to="/">Home</Link></li>

<li><Link to="/about">About</Link></li>

</ul>

<hr />

<Route exact path="/" component={Home} />

<Route path="/about" component={About} />

</div>

</HashRouter>

);

}

As we will be serving the application from the /my-react-app subdirectory on our GitHub Pages URL, we will want to add the property basename to our <HashRouter> . This will act as our base URL for all our routes.

Next we will add some views for our routes. Add the following functions to App.js just before we export the component.



// App.js

... const Home = () => <div><h2>Home</h2></div>

const About = () => <div><h2>About</h2></div> export default App;

Now our App.js file should look like the following;

App.js

That's everything we need for a working React application with Routing. Serve the application locally via npm start , and confirm routing is working as expected.

Adding GitHub Pages and deploy the application

For this, we will need to install gh-pages package.

$: npm install gh-pages

Before we build our application for deployment we need to add a homepage property to our package.json file. This sets the base URL for all our routes and also lets GitHub Pages know where to deploy. We also need to update our scripts property so that we can run a deploy from the command line.

The predeploy script initiates after we run our deploy script, this bundles our application for deployment. Let's deploy our application to GitHub pages;

$: npm run deploy

If our build and deployment were successful you should see Published in the last line of your terminal, and if you go to your repository on GitHub and you should see a new branch created called gh-pages .

GitHub — gh-pages branch gets generated on deploy

In the settings tabs of your repository you should also see confirmation of deployment to your new URL

GitHub Settings tab — Confirmation our application has deployed succesfully

Navigating to our URL we should see the our application in action https://8eni.github.io/my-react-app.

GitHub pages — Our hosted react app with hash routing

Note: You may see an error 404 page when you view the url after successful deployment/publish, this is normal, give it 30–60 seconds, refresh the browser and your application should be present.

Conclusion

We have successfully deployed a create-react-app with routing to a live URL on GitHub Pages. By utilising react-router-dom ’s HashRouter we don’t have to worry about getting a 404 error on page refresh. As we are hosting the application in a subdirectory this means we can deploy multiple applications in different subdirectories on our GitHub Pages URL.

Hope you enjoyed this article. If you have any suggestions for improvement related to the content of this article or queries please leave in the comments.