Deploy Simple React App on Github Page Using NPM in Six Steps
Check out all my other posts in My Technical Articles
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.
- Pick Up the Prerequisites Before Continuing
- Deploy React App on Github Page Using NPM in Six Steps
- Make Sense to What We Did
- 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:
- 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
- Must understand and know how to use React to render HTML element. React official documentation is a good starting point
- Must understand WHAT folder structure is required to make Github page work. Github documentation gives us a hint on this
- 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
- 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": "https://yumingchang1991.github.io/personal-portfolio/"
- 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, like
gh-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