How to Create a React Application and Deploy It on GitHub Pages

In this guide, we will go through the process of creating a React application and deploying it using GitHub Pages to make it available to the world, requiring only a few command lines in your terminal.

Creating a React application from scratch can quickly become cumbersome and time-consuming. You have to initiate an npm project, create an entry point, setup webpack configuration for both development environment with hot-reloading and local HTTP server, and production with code minification and uglification, you will probably also want to define a linter and... I think you get the point, there is a lot of things to do before having an up and running application and no one wants to do all of that every time one creates a new React application.

Thanks to the React team because they came up with a nice solution. A CLI responsible for automating all of these tasks in a single line command.

This simple command will create a React application in a new folder called /demo-application with all of the aforementionned features already set up.

From here, you should be able to start your application by simply navigating into your application folder and starting it using either npm or yarn:

Your application, with a default home page generated by create-react-app CLI, should automatically start in your default browser.

Now that we have our application running locally, we really want to showcase all the magnificent work that we did to the world. A lot of platforms propose hosting front-end JavaScript applications. In this guide, we will focus on the one from GitHub, called GitHub Pages.

GitHub Pages is a service from GitHub that allows you to host your front-end application directly from your GitHub repository. All you have to do is to edit your code and push it on a specific git branch, or folder, of your repository and GitHub will automatically handle the rest for you. A prerequisite to using GitHub Pages is, obviously, to host your code in a GitHub repository. To do that, I would recommend the reading of this other Pluralsight guide Create a Git Repository and Branching Code about creating a Git repository and hosting it on GitHub.

At a glance, GitHub Pages will propose you to automatically deploy static resources that are present on a specific branch of your git project. By convention, people are generally using a gh-pages branch. So every time you need to push static resources (HTML, CSS, and JS) on this branch, they will automatically be deployed and accessible on https://yourusername.github.io/yourprojectname.

In order to build your React application and generate static resources that are ready to be deployed from it, create-react-app CLI automatically created a build script in your package.json file. This command will build your application using your Webpack configuration for production and output the static resources under a build/ folder.

Before doing that, we have to indicate to webpack that our application will not run at the root level of our host but under a subpath on a page like https://your_github_username.github.io/your_project_repository_name/.

In your package.json file, add the homepage property.

This will help Webpack build the right path for your resources links. By default, Webpack assumes that your application is running at the root level and, in this case, your application wouldn't be able to find any static resources on https://your_github_username.github.io/.

Now, to build your application, simply run the following command:

You will see that a build/ folder has been created at the root of your project containing all the static resources needed to make your application run on an HTTP server.

Now, the goal is to create a git branch called gh-pages that will contain only the content of the build/ folder.

We need to create the branch and check it out.

And then, we’ll delete everything except the git related files and the build folder. Following that, we’ll move the content of the build/ folder at the root level and then commit and push our changes.

To activate the automatic deployment of your branch, go into the settings of your project on GitHub and in the GitHub Pages section, choose your gh-pages branch as a source.

From here, GitHub will automatically handle the rest of the work for you. It will detect that you pushed on this specific branch, deploy its static resources, and expose it on an url like https://your_github_username.github.io/your_project_repository_name/.

You may have noticed that it is a bit cumbersome to remove everything in the gh-pages branch and to keep only the static resources each time we want to deploy our application. Some smart guys created a tool to automatically purge the unnecessary files from this branch, keeping only the ones having been generated during the build process and pushing your gh-pages branch on your GitHub repository.

This tool is called gh-pages.

In order to use it, we will install it as an npm dev dependency of our project.

While this tool can be used programmatically, in the context of this guide we will focus on using its command line feature. What we would like to have is an npm script that will allow us to deploy our application on GitHub Pages with a single command.

Let’s add a new script definition under the scripts section in our package.json file.

We are now able to deploy our application by simply running:

In this guide, we saw how we can quickly scaffold and deploy a React application. In a few minutes, and after some command lines execution, you have an application up-and-running and available to the world.

If you have been visiting some GitHub repositories from well-known libraries or tools, you may have seen that GitHub Pages is often used to host documentation or landing pages presenting the project. But it could also be used to host a little front-end application, showcase your personal portfolio to other people, or even present some of your work to colleagues as this feature is also available on GitHub Enterprise.

If you want to go further on this topic, here is a list of meaningful resources:

• gh-pages Repository

  This is the full documentation of the library as you may want to use it programmatically to customize some of its options.

• Official GitHub Pages Guides

• create-react-app CLI Repository