Hosting Custom React Websites via Github Pages

Photo by Halacious on Unsplash

I was cleaning up some spaghetti code I had written back in college and came across my unpublished personal website. It was something I built when I was first learning about web programming, and I had used it as a means to experiment with JavaScript and Webpack. Since the content was outdated and the site itself unfinished, I decided to take a second look, clean it up, and figure out the best way to host it.

While major rewrites did take place, the real challenge I came across was with hosting. I wanted to use Github Pages, as I heard it was free and supposedly easy to use. However, I wasn’t sure if it would pose a challenge for an application built with React, transpiled Babel and bundled with Webpack. I could restart my site and make a simple HTML page, but I thought it could be fun to see if I could still get it working in that state. I found an excellent article, How to deploy React App to GitHub Pages, but the solution it offered was built for developers that based their project off of create-react-app, as opposed to one built with custom Webpack like mine. I knew I could backtrack and start again using that solution, but that would involve scrapping the work I had done. Thankfully, after some time reviewing the docs for gh-pages, as well as the file structure for create-react-app , I was able to figure it out.

So, for anyone interested in building a React app using custom Webpack, and hosting it with GitHub Pages, here are the steps you can follow.

Step 1: Setting Up Webpack

The key to ensuring your application is readable to Github pages, is to make sure your Webpack configuration file is set up correctly.

Below is an example:

const SRC_DIR = path.join(__dirname, ‘/src’);
const DIST_DIR = path.join(__dirname, ‘/build’);

In lines 3-4, shown again above, I set variables to establish the source directory as /src, and the destination directory as /build. These variables set the source of where code is going to be transpiled & bundled from, and the destination of where the final bundle will be going. This part is extremely important for deploying to Github Pages, specifically because gh-pages will look for the /build directory contents when it deploys your code. If this is not present, you will get errors on deployment.

Within the next section where we set exports, we give Webpack some directions on how to read our code.

entry: `${SRC_DIR}/index.jsx`,

Line 7, shown above, specifies the entry point to your react code, usually an index.jsx file at the top level of /src directory.

output: { 
   path: DIST_DIR, 
   filename: ‘bundle.js’, 
},

Lines 8–11, shown above, specify the destination file for the transpiled and bundled code within the /build directory, usually bundle.js.

In the next set of lines, 12–14, pictured below, we set which types of extensions should be transpiled.

resolve: { 
   extensions: [‘.js’, ‘.jsx’, ‘.css’] 
},

In this case I am choosing to have webpack process only js, jsx, and css file types, as those are the types my application will be using.

Lines 15–34 describe what kinds of file loaders to use.

module: { 
  rules: [ 
    { 
      test: /\.scss$/, 
      use: [ ‘style-loader’, ‘css-loader’, ‘sass-loader’ ] 
    },{ 
      test : /\.jsx?/, 
      include : SRC_DIR, 
      loader : ‘babel-loader’, 
      query: { presets: [‘react’, ‘es2015’] } 
    }
  ] 
},

Per Webpack,

Out of the box, webpack only understands JavaScript and JSON files. Loaders allow webpack to process other types of files and convert them into valid modules that can be consumed by your application

The test key identifies the file types we will be processing. The use key identifies what loaders we will use to process them. There are different types of loaders recommended for each file type. I recommend looking at this documentation to find which ones suit your specific needs. In this case, I am using style-loader , css-loader , and sass-loader to process my Sass (scss) files, and babel-loader to process and transpile my jsx files.

Step 2: Link HTML to bundle.js

This next step is very short. In order to properly display your transpiled code, you need to embed it as a script into an index.html file within the /build directory.

If you look to line 8, you can see how I link it via script tag.

Step 3: Setting up a Server

I’m not sure how many of you would need this step, but this is how you set up a server. This helps with building and and running your code locally for testing purposes. I have this file existing as index.jsin a /server directory at the same level as my /src folder.

Step 4: Deploying Code

Assuming you wrote some working React code & it runs locally, and have followed along with these steps so far, this next section will help you make sure your website is deployed and hosted on Github Pages.

Assumptions:

• You have a Github account and
• Git installed and
• Have basic knowledge of how to push code into a Github repo

If not, please consider looking here, and coming back when you have read through that documentation.

First we need to install gh-pages, an npm module that helps with deploying to Github Pages, as a dev dependency.

npm install gh-pages --save-dev

Next we need to add a key to package.json, indicating the homepage address. Below would be the expected format:

"homepage": "http://{username}.github.io/"

In my case, this read as homepage: http://zmillard.github.io/

Per recommendation of gh-pages, you can set up a script to handle deployments as such:

"scripts": {
  "deploy": "gh-pages -d dist"
}

You will need to rebuild before you deploy after each change and then deploy in order to see changes properly affected. You could optionally set up a predeployment script to handle this. (Don’t understand what pre scripts are? Check out these npm docs)

When you run npm run deploy, you should be able to see your code available at the address listed under homepage in package.json.

Voila!