Deploy Simple React App on Github Page Using NPM in Six Steps

This article is written because it troubles me for a couple of days and I haven’t found a comprehensive article to explain the devils, probably because I’m suck at finding the correct key word. Anyway, I thought it might help me recall this process a couple months later, and it might help you along the way.

You will learn the followings in this article.

  1. Pick Up the Prerequisites Before Continuing
  2. Deploy React App on Github Page Using NPM in Six Steps
  3. Make Sense to What We Did
  4. Reference

Pick Up the Prerequisites Before Continuing

If you’re a junior in web development and a control freak like me, you might want to understand the terms and concept listed down here before deploying your React App. Or, if you’re more comfortable in try and error, then you may you skip to the next section.

Five Things I considered important before continuing:

  1. Must have basic knowledge of how HTML, CSS and JavaScript work together to render a web page. In short, HTML defines the structure of a page, CSS controls the look of its content and JavaScript manages user actions through DOM. This free code camp article explains more details for beginner
  2. Must understand and know how to use React to render HTML element. React official documentation is a good starting point
  3. Must understand WHAT folder structure is required to make Github page work. Github documentation gives us a hint on this
  4. Must know basic Git and Github terms, including branch, staging changes, remote url, and push. Github documentation are a good reference for this and the last point
  5. Must know how to create a repository through Github, and through your laptop

Deploy React App on Github Page in Six Steps

Here is a dense version of steps. For details, you may refer to the reference link below:

Step 1: Create React App

// install creat-react-app if it is the first time to use it
npm install -g create-react-app
// run command below to execute create-react-app
// personal-portfolio is the name of the new project
// you could change the name
npx create-react-app personal-portfolio

Step 2: Create Repository on Github

Step 3: Add NPM Package gh-pages to Our Project

Type in command line below instruction to add gh-pages to our project, and to create dependency.

npm install gh-pages --save-dev

Step 4: Update Configurations in Package.json File

  • Add a new property homepage with the link to our app as below:
"homepage": ""
  • Add two additional key and value inside property script
"predeploy": "npm run build",
"deploy": "gh-pages -d build"

Step 5: Commit and Push the App to Repo

Step 6: Deploy Our Github Page by One-Line Command

npm run deploy

Make Sense to What We Did

1) We created TWO branches to store different files for our project

The first branch is called master by default, which stores our HTML, CSS, JavaScript, React Environment Configurations and other assets used to create a React application. I usually change the branch name from master to primary by using the command below

// this will change the branch name both in remote and local
git push origin :master primary
// ensure our local branch upstream is correctly linked to remote
git push origin -u primary
// scroll down to reference section if you want to learn more about
// what is upstream
// how to change branch name

2) We only write code in Primary/Master branch

The one-line command from step 6 npm run deploy it actually runs two commands we added in step 4:

npm run build
gh-pages -d build

npm run build goes through the files in development environment, and generate production files in another folder called build

gh-pages -d build pushes all files in a folder called build to a branch named gh-pages

  • if branch gh-pages does not exit, this command will create one
  • if we do not specify a file or folder name, likegh-pages -d, it pushes all the files under current branch to a branch named gh-pages

3) Github page is connected to gh-pages but not primary/master

It means if only modify code in primary branch, Github pages won’t update itself because there is no changes in gh-pages branch.

Remember to run npm run deploy to update what is inside gh-pages



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Yu-Ming, CHANG (he/him)

Yu-Ming, CHANG (he/him)

I enjoy the positive mind flow when writing code to solve a problem. This is my journey to become a software developer