Using GitHub Pages with Custom Domains

In this guide, you'll learn about the various types of domains supported by GitHub pages and how to configure a custom domain on Github pages.

Oct 23, 2020 • 4 Minute Read

Subscribe to the newsletter

Introduction

Your shiny new app is complete and ready to be shown to the world, but you do not want to use the default .github.io domain. You want a fully customized domain name to give customers or users a seamless experience. What do you do? In this guide, you'll learn about the various types of domains supported by GitHub pages and how to configure a custom domain on Github pages.

Deploying Your App

If you're using a module bundler like webpack or parcel, ensure you push your production build to your GitHub repository. This also applies to frameworks or libraries like React, Angular, or Vue. Bear in mind that GitHub pages do not fully support single-page applications, especially when you're using an HTML5 history API-based routing solution like react-router-dom. To get around this, use the HashRouter rather than BrowserRouter, as shown below.

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

function Homepage(){
render(){
	<div>
				<p>Homepage</p>
	</div>
}

function App(){
	render(){
		<HashRouter basename='/'>
			<Route exact path='/homepage' component={Homepage}/>
		</HashRouter>
);
}
    

A link to the homepage route would return a link as shown below.

      <a href='#/homepage'>....

Follow my guide Deploying React on Github Pages to help you through the deployment process of a React app on GitHub pages.

Supported Domains

GitHub Pages supports two domain types, subdomains and apex domains. See examples of each below.

      // Examples
Subdomain type     |  Example
-------------------|-----------------
www subdomain      |  www.pluralsight.com
Custom subdomain   |  app.pluralsight.com
Apex domain        |  pluralsight.com
------------------------------------------
    

Configuring a Custom Domain

Subdomains

For a subdomain such as app.pluralsight.com, add a CNAME record to your domain service provider.

Follow the following steps to configure a subdomain:

On your site's repository, click the settings tab .
Under custom domain, type your custom domain and save. GitHub will automatically create a commit with a CNAME file at the root of your repository.
Visit the dashboard provided by your domain provider and add a CNAME record pointing to your subdomain. Given the example above, for the subdomain www.pluralsight.com, a CNAME record for www.pluralsight.com would point to <USER_NAME>.github.io where <USER_NAME> is your GitHub username.

You can optionally choose to enforce HTTPS in your settings on GitHub.

Note that DNS changes can take up to 24 hours to reflect.

Apex Domains

For apex domains, configure an ALIAS or ANAME/A record. To reiterate, an example apex domain would be pluralsight.com.

Follow the following steps to configure an apex domain:

On your site's repository, click the settings tab
Under custom domain, type your custom domain and save. GitHub will automatically create a commit with a CNAME file at the root of your repository.
Visit the dashboard provided by your domain provider and add an ALIAS or ANAME/A record pointing to your apex domain to the IP addresses of GitHub pages, as shown:

i. 185.199.108.153

ii. 185.199.109.153

iii. 185.199.110.153

iv. 185.199.111.153

Conclusion

And that's it! In this guide you learned how to use a custom domain name with GitHub pages.

Feel free to read more on this topic in the official documentation of GitHub.

If you want to talk more about this, drop me a line on Twitter.