Deploying a React App* to GitHub Pages
* created using create-react-app
Introduction
In this tutorial, I'll show you how I deployed a React app—which I created using create-react-app—to GitHub Pages.
You can visit the deployed app, at https://gitname.github.io/react-gh-pages/.
This repository contains the files related to the app. The master branch contains the app's source code (the code the app's developers edit), and the gh-pages branch contains a built version of the app (i.e. the code that GitHub Pages serves to the app's visitors).
The remainder of this document contains a tutorial on creating a React app (using create-react-app) and deploying that app to GitHub Pages.
Tutorial
Prerequisites
-
An adequate version of
Node.jsis installed. Here's the adequate version I use:$ node --version v6.10.1
-
An adequate version of
npmis installed. Here's the adequate version I use:$ npm --version 3.10.10
-
An adequate version of
create-react-appis installed. Here's the adequate version I use:$ create-react-app --version 1.3.1
In the case of
create-react-app, you can either install it globally (i.e.$ npm install -g create-react-app) or install it locally (i.e.$ npm install create-react-app). If you choose the latter, you will have to specify its path whenever you invoke it (e.g.path/to/node_modules/.bin/create-react-app). -
(Optional) An adequate version of
sedis installed. Here's the adequate version I use:$ sed --version sed (GNU sed) 4.4
-
A GitHub account.
-
A command-line Git client setup according to GitHub.
Procedure
-
Create an empty repository on GitHub. (2 minutes)
- For this tutorial, I'll create a repository named
react-gh-pages. - By empty, I mean without a
README.mdfile, a.gitignorefile, aLICENSEfile, or any other files.
- For this tutorial, I'll create a repository named
-
Create a new React app on your computer. (5 minutes)
$ create-react-app react-gh-pages
- This is the app you will deploy to GitHub Pages in step 7.
- I opted to give the app the same name as my GitHub repository (i.e.
react-gh-pages). However, you can name them differently from one another (e.g. you can name your appapp-123and your GitHub Repositoryrepo-456). - This will create a new folder named
react-gh-pages(or whatever you named your app) on your computer.
-
Install the
gh-pagespackage as a "dev-dependency" of the app. (1 minute)$ cd react-gh-pages $ npm install gh-pages --save-dev- The commands shown in the following steps can all be issued from within the app's folder.
-
Add some properties to the app's
package.jsonfile. (3 minutes)- At the top level, add a
homepageproperty. Define its value to be the stringhttp://{username}.github.io/{repo-name}, where{username}is your GitHub username, and{repo-name}is the name of the GitHub repository you created in step 1. Since my GitHub username isgitnameand the name of my GitHub repository isreact-gh-pages, I added the following property:
//... "homepage": "http://gitname.github.io/react-gh-pages"
- In the existing
scriptsproperty, add apredeployproperty and adeployproperty, each having the values shown below:
"scripts": { //... "predeploy": "npm run build", "deploy": "gh-pages -d build" }
- Shortcut: Instead of adding those properties using a text editor; if I have
sedinstalled on my system, I can add the properties by issuing the following shell commands:
$ sed -i '5i\ "homepage": "http://gitname.github.io/react-gh-pages",' ./package.json $ sed -i '15i\ "predeploy": "npm run build",' ./package.json $ sed -i '16i\ "deploy": "gh-pages -d build",' ./package.json
- At the top level, add a
-
Create a git repository in the app's folder. (1 minute)
$ git init Initialized empty Git repository in C:/path/to/react-gh-pages/.git/ -
Add the GitHub repository as a "remote" in your local git repository. (1 minute)
$ git remote add origin https://github.com/gitname/react-gh-pages.git- This will make it so the
gh-pagespackage knows where you want it to deploy your app in step 7. - It will also make it so git knows where you want it to push your source code (i.e. the commits on your
masterbranch) in step 8.
- This will make it so the
-
Generate a production build of your app, and deploy it to GitHub Pages. (2 minutes)
$ npm run deploy- That's it! Your app is now accessible at the URL you specified in step 4.
- In my case, my app is now accessible at: https://gitname.github.io/react-gh-pages/
- I recommend exploring the GitHub repository at this point. When I explored it, I noticed that, although a
masterbranch did not exist, agh-pagesbranch did exist. I noticed the latter contained the built app code, as opposed to the app's source code.
-
Optionally, commit your source code to the "master" branch and push your commit to GitHub. (1 minute)
$ git add . $ git commit -m "Create a React app and publish it to GitHub Pages" $ git push origin master- I recommend exploring the GitHub repository once again at this point. When I did that, I noticed that a
masterbranch now existed, and it contained the app's source code. - So, the
masterbranch held the source code, and thegh-pagesbranch held the built app code.
- I recommend exploring the GitHub repository once again at this point. When I did that, I noticed that a
References
Notes
- I created this React app using
create-react-app. By default, apps created usingcreate-react-apphave a README.md file that looks like this. Indeed, the README.md file you're now reading originally looked like that. I have since changed it to look the way it looks today. - Special thanks to GitHub, Inc., for providing us with the GitHub Pages hosting functionality at no extra charge.
- And now, time to turn the default
create-react-appapp into something unique!
