Raquel M Smith

How to deploy create-react-app to Github Pages

You’d think it’d be super easy to deploy a simple app made with create-react-app to Github Pages, considering how common they both are. And while it is easy on a basic level, if you’re using React Router to create a single page app, it doesn’t work perfectly right out of the box.

It is possible to do, however! There’s just a bit of finagling to do.

There are two issues that need to be resolved in order to deploy your create-react-app app to GitHub Pages:

  1. create-react-app needs you to add the deploy script with all the right info
  2. If you’re using react-router-dom, the links won’t work on refresh. We’ll talk about how to get around this

Let’s get started!

New to developing with React? I highly recommend checking out Wes Bos’s course, React for Beginners. It’ll get you comfortable with creating simple React-based apps in just a few hours.

Add deploy script

Deploying to GitHub is easy with the npm gh-pages package. Let’s install that in your project:

npm install gh-pages --save-dev

To make use of this package, we have to add some extra bits to package.json. Head on over there, then add the following:

Add a homepage key, where username is your GitHub username and mysweetapp is the name of your repository:"homepage": "http://username.github.io/mysweetapp"

  "name": "myapp",
  "homepage": "http://username.github.io/mysweetapp",
  "version": "0.1.0",
  "private": true,

If you’re using a custom domain name for the project, eg. https://mysweetapp.com, you can use that there instead of the github.io address.

Next, inside scripts, add two new scripts for predeploy and deploy:

  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build",
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"

Add 404.html file

With React Router, the actual files your visitors will be trying to access don’t actually exist. All that exists is the main index.html file, so when the browser tries to navigate to something other than that file, it doesn’t exist.

So what needs to happen here?

When a path doesn’t exist, the browser goes to a 404 page – and you can provide a custom one of those. In that custom 404, you include a script that uses the given URL path and turns it into a query string, then tells the browser to load the page at that base URL with the query string.


Rafael Pedicinirafrex, a Frontend Engineer at Lyft, did all the heavy lifting for this in his SPA for Github Pages repository: https://github.com/rafrex/spa-github-pages

You’ll need to grab the 404.html file from that repository and paste it into your mysweetapp/public folder. If you aren’t using a custom domain name, find segmentCount in the 404.html file and set it to 1.

So now you’ve got:


Does this impact SEO?

Nope. Today’s search engines are really smart, and doing this kind of thing doesn’t have any impact on SEO. The search engine can tell where the browser eventually ends up, and the redirect isn’t visible to the end user, so SEO shouldn’t see much of an impact.

Add redirect script to index.html

Now we’ve got the 404 page telling the browser where to redirect to, all requests will end up on the index.html file. Now, we still nee to tell the index.html file what route to render based on the query string.

Fortunately, the SPA for Github Pages repo has this for us, too!

Add the script found here to the <head> section of your public/index.html file and you’re on your way.

Add CNAME file for custom domain name

If you’re using a custom domain name, another requirement for GitHub pages is a CNAME file. This also goes in the public directory. There’s no file extension, it’s just public/CNAME.

This file has a single line, and it’s the domain name that you’ll be using. You’ll omit any protocol information, so if your domain is https://mysweetapp.com then in the CNAME file you’ll just put mysweetapp.com. If you’re using a subdomain, then you’ll include that also.

Run the deploy scripts

Run npm run predeploy and then npm run deploy to build your app and send the correct info up to the gh-pages branch in your repository.

Activate Github Pages for the repo

Head on over to your repository Settings area and scroll down to GitHub Pages. Under Source, select gh-pages.

Add custom domain to Github Pages

If you’re using a custom domain name, add that under the “Custom Domain” area of GitHub Pages.

Update DNS for your custom domain to point to GitHub

Now that GitHub pages is all set up, you can point your domain name to GitHub. GitHub has different sets of instructions for how to set these up depending on what kind of URL you want to use, so I recommend checking out their page on setting up a custom domain for GitHub Pages. You’ll follow one of the guides in step 3.

And you’re done!

Verify that your DNS is set up properly, and then you should see your fancy new web app loading on your custom domain name (if you used one) and loading the pages properly. Enjoy!

I made this tutorial after working to get my little web app Zonestamp set up on GitHub pages. Check it out on Github and on the live site!

Leave a Reply

Your email address will not be published. Required fields are marked *

0 Comments on "How to deploy create-react-app to Github Pages"

    • About
    • Projects
    • Bookshelf
    • Blog
    • Github@raquelmsmith
    • LinkedIn@raquelmsmith
    • Emailhello@raquelmsmith.com