What is GitHub Pages?

GitHub 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. There are three types of GitHub Pages sites:

Project- These are connected to a specific repository present in GitHub and are hosted under user or organization sites.
User- An individual GitHub user account can publish a site for repository under the user. The domain looks like: https://username.github.io/repository
Organization- An organisation can publish a site for repository under their account. The domain looks like: https://organization.github.io/repository

Types projects that can be hosted on GitHub Pages:

GitHub Pages also provides options for non coders to setup beautiful websites using pre-made templates, which can be very easily modified to users requirement. There are no real restrictions, as long as an index.html file which can be served exists.

Restrictions regarding using GitHub pages:

GitHub Pages source repositories have a recommended limit of 1GB.
GitHub Pages sites may be no larger than 1 GB
GitHub Pages sites have a soft bandwidth limit of 100GB per month.
GitHub Pages sites have a soft limit of 10 builds per hour

Few GitHub pages examples for the non-believers:

Twitter: twitter.github.io
Yelp: yelp.github.io
My website built using React+Material UI: sharkpot.github.io/alliance-management-system

So what does it cost to do all of this? Nothing. Nothing at all. As long as you are under the restrictions threshold, you don’t have to pay a dime.

Let’s get started with deploying our own website. For this example, I will be using React.

Setting up the React GitHub project

To start off, setup your GitHub repository and clone it to your local system. We will use create-react-app to create a new React project like this:
```
npx create-react-app my-app
cd my-app
```
For routing, our preferred package would be react-router-dom as shown below:
```
npm install react-router-dom
```
When using react-router-dom we will not be using BrowserRouter, since any of your sub-domains cannot be accessed directly by adding the URL in the address bar or refreshing the page, resulting in a 404 page. Instead we will use HashRouter during this process.

At this point, our App component will look something like this:

// import { BrowserRouter as Router } from 'react-router-dom';
import { HashRouter as Router } from 'react-router-dom'

render() {
 return (
  <Router basename='/'>
    ...
  </Router>
 );
}

Our final code will look something like this:

import React, { Component } from 'react';
import { HashRouter as Router, Route, Link } from "react-router-dom";


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

class App extends Component {
  render() {
    return (
      <Router basename="/">
        <div>
          <ul>
            <li><Link to="/">Home</Link></li>
            <li><Link to="/about">About</Link></li>
          </ul>
          <Route exact path="/" component={Home} />
          <Route path="/about" component={About} />
        </div>
      </Router>
    );
  }
}

export default App;

Deploying on GitHub Pages

Now, we shall learn how to deploy a webpage on GitHub Pages. An easy way to perform this action would be to use gh-pages library, as shown:

npm install gh-pages

Open package.json and add the following:

"homepage": "https://<username>.github.io/my-app"

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

The homepage field defines where your project site will be hosted. Make sure your project name is the same as sub-domain, else it might cause issues wherein it requests for resources at the wrong domain.

Predeploy script is also automatically run alongside when deploy script is run. It will build your application. If you are using other frameworks, you can replace this command with the build command of the framework.

Your final package.json should look something like this:

Deploying your code

As we reach the final segment of this article, let's learn how to deploy your code. Start by running the following:

npm run deploy

This will build and deploy your project and on completion. It will say that it has been successfully published. You can verify it yourself by simply checking your branches. There will be a branch called gh-pages. This branch can be considered as your build branch and can be changed if required in the settings of GitHub Pages.

You can go to your repository settings, and scroll down to find the GitHub Pages section. It will also provide you with the URL where the project is deployed. An example is shown below:

When you check for the first time, it might take a few minutes (4-5 minutes) for your project to be actually running on the site. For repeated deployment, you can simply run the deploy command, and after a few minutes (1-2 minutes), the updated code should be deployed.

The application is hosted in a sub directory; which means we can deploy multiple applications in different sub directories on our GitHub Pages URL, as long as it doesn't hit the cap. It is also very helpful to setup custom 404 pages. You can refer to this for all information on the topic.

Hope you've had a nice read!

References:

GitHub Pages Docs: docs.github.com/en/github/working-with-gith..

create-react-app: reactjs.org/docs/create-a-new-react-app.html

React-Router-Dom: reactrouter.com/web/guides/quick-start

gh-pages Library: npmjs.com/package/gh-pages

Deploying the React App on GitHub Pages

What is GitHub Pages?

Setting up the React GitHub project

Deploying on GitHub Pages

Deploying your code