I wanted to create a one-page application for trying out Github Pages. The issue I had was constantly getting error 404 or readme.md. I read a lot of articles to find a way to solve those issues and get the default create-react-app page shown. However, I failed to find a ready-to-go solution that worked for me.

So here I will describe what I did to make my GitHub pages work with my repository. I skipped creating a GitHub repo, cloning the project, and running create-react-app to create a project. I assume you have already done that before you follow my steps.

Please, keep in mind that if you design an application with multiple pages additional configuration might be needed. My application contains only one page, this is why I did not use react-router.

So, let me start.

Steps 1:

I remove node_modules folder and reinstall npm modules. This is optional and should be done if deployment haven't worked for you previously (e.g. the following error appeared: 'fatal: Couldn't find remote ref refs/heads/gh-pages').

Step 2:

It was pointed out in the sources I read that GitHub pages do not play very well with SPA so I needed to do few changes to package.json file.

First, I install gh-pages as devDependencies.

npm i --save-dev gh-pages // -> using npm
yarn add -D gh-pages // -> using yarn

gh-pages module helps with deploying the application and it creates a branch where we want to deploy our code. That is why there is no need to create a branch manually.

Now I need to add in package.json file.

{
  "homepage": "https://[GITHUB_USER].github.io/[GITHUB_REPOSITORY_NAME]"
}

This will be URL of the project homepage.

After that, I add the following lines in the scripts section in package.json.

{
  "predeploy": "npm run build", // or yarn build
  "deploy": "gh-pages -b gh-deploy -d build",
}

-b name of the branch I am pushing to, the default branch is gh-pages
-d Base directory for source files

When I run deploy it automatically runs predeploy first. Also, the code that was built with predeploy command is deployed to thegh-deploy branch.

The final result should look like this:

{
  "homepage": "https://[GITHUB_USER].github.io/[GITHUB_PROJECT]",
  ...
  "scripts": {
    "predeploy": "npm run build", // or yarn build
    "deploy": "gh-pages -b gh-deploy -d build",
    ...
  },
  ...
  "devDependencies": {
    "gh-pages": "^3.2.3"
  },
  ...
}

Step 3:

1. Open GitHub and open your repository.

2. Click Settings.

3. Click Pages.

4. Select gh-deploy branch from dropdown.

5. Click Save.

6. Wait for deployment to finish and then check out the app.

This is one of the ways you can deploy your one-page application to GitHub pages. Hopefully, it will help you if you find yourself struggling with the same issues.

Sources