Using Custom Domains for React Apps Deployed to GitHub Pages

There is no better way to showcase your projects and apps than having a deployed version of them. One of the ways of doing this is using GitHub Pages, which host your app directly from your project repository. It is free and easy to use and maintain. React projects bootstrapped with Create React App are even easier to deploy with GitHub pages.

The app deployed using GitHub Pages have default URLs like {username}.github.io/{repository-name}, but what if you want to change the domain? In this guide you will learn how to add custom domains to your React apps hosted with GitHub Pages.

This guide assumes you have already deployed your React app with GitHub pages and have purchased a Custom Domain. You can learn how to deploy React apps on GitHub Pages here.

The first step is to set your custom domain in the GitHub project settings. Go to your GitHub repository's settings. Under Custom domain add your custom domain and click Save. This will create a CNAME file in the root of your project publishing source. Don't delete it.

CNAME stands for canonical name, it is used to alias one domain name to another. Unlike A records, a CNAME record points to another domain and never directly to the IP server.

If your custom domain is example.com, then your CNAME file will be like this:

This CNAME file can only contain one domain and should be the bare minimum of your URL, like www.example.com or example.com rather than https://example.com.

Now the next step is to configure your Domain Name Registrar (like Namecheap, Domain.com, Google Domains, etc.). You just need to set A and CNAME records.

A record stands for address record, it connects your domain name to the actual IP addresses where your site resides on a server.

For A record set all the following:

Depending on your DNS provider, you may be asked for the name of the record. Set it to @.

Create a CNAME record that points your subdomain to the default domain for your site.

For example, to redirect the www subdomain (www.example.com) to the original domain, add a CNAME record with your project's default URL with a period at the end as its value. If asked, set the name of the record to "www" and TTL to "hour or less".

For example, if your username is "ezio" and your project repository is named "react-photo-search-app" then by default your app will be published to https://ezio.github.io/react-photo-search-app/. For this, the CNAME record that you need is

Note: This CNAME is different from the one created in your project repo.

After you have successfully added and configured the records, you can add an extra layer of encryption by checking Enforce HTTPS under the Custom domain setting in your repository settings.

That's it, a custom domain has now been added to your React app. It may take up to 24 to 48 hrs depending upon your DNS provider to reflect these changes, so just sit back and wait.

This resource on troubleshooting custom domains and GitHub Pages may help if you run into an error.