Guide Serving Apps via Github Pages - ProjectEvergreen/create-evergreen-app GitHub Wiki

Table of Contents

Quick Setup - Evergreen Scripts

Evergreen Scripts is a module of scripts built specifically for extending the functionality of evergreen applications. One of those scripts is the gh-pages serve script.

Install

npm i -D evergreen-scripts

Configure

First make sure you've created a github repository and added the remote url to your project:

git init
git remote add YOUR_REPO

Edit your package.json file with your repository url and the gh-pages script:

"homepage": "https://YOUR_GIT_USER.github.io/YOUR_REPO/",
"scripts": {
    "gh-pages": "evergreen-scripts gh-pages"
}

Usage

Build, update, and serve files on github pages:

npm run gh-pages

Your app should now be available at https://YOUR_GIT_USER.github.io/YOUR_REPO/

Manual Setup

If you wish to do it step-by-step, the following is what the above script is automating.

Init git repository

  1. First make sure you've created a github repository and added the remote url to your project:
git init
git remote add YOUR_REPO
  1. We need to create the master branch, as none is created by default. To do this we'll add all files and commit them. You'll also want a gitignore file so we aren't committing node_modules accidentally.
echo "node_modules" > .gitignore
git add .
git commit -m "Initial Commit"

Add git worktree

Create a new git worktree which is using our new gh-pages branch. We're detaching it from the current branch because we want to create an empty new repository

git worktree add --detach dist
cd dist
git checkout --orphan gh-pages

A new folder will be created called dist which uses a separate gh-pages branch. Anything you want to serve on gh-pages put in here, commit and push.

Routing config with webpack

One way to accomplish this is to modify the default webpack.config.prod.js with the following:

const publicPath = '/YOUR_REPO/';

module.exports = webpackMerge(commonConfig, {

  mode: 'production',

  output: {
    publicPath
  },

  plugins: [
    ...
    new HtmlWebpackPlugin({
      filename: 'index.html',
      template: 'index.html',
      publicPath
    }),
    new HtmlWebpackPlugin({
      filename: '404.html',
      template: '404.html',
      publicPath
    }),
   ...
  ]
});

It's likely your 404.html redirect doesn't exist yet. We'll create one in the next step.

404 redirect and index state

In your src directory, create a new 404.html redirect with the following contents:

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="utf-8" />

  <title>Create Evergreen App</title>

  <script>
    sessionStorage.redirect = location.href;
  </script>

  <meta http-equiv="refresh" content="0;URL='<%= htmlWebpackPlugin.options.publicPath %>'"></meta>
</head>

<body>

</body>
</html>

In your src/index.html file add the following script to replace state when clients are redirected.

    <script>
      (function(){
          var redirect = sessionStorage.redirect;
          delete sessionStorage.redirect;
          if (redirect && redirect != location.href) {
          history.replaceState(null, null, redirect);
          }
      })();
    </script>

Add build script

Finally to make sure our builds are copied into our worktree(dist) folder after every build, we need to create a script to do that in our package.json file:

"scripts": {
  "gh-pages": "npm run build && git -C dist rm -rf . && cp -r ./public/. ./dist/ && git -C dist add . && git -C commit -m 'Updating gh-pages' && git -C dist push origin gh-pages",
}

Manual Usage

Build, update, and serve files on github pages:

npm run gh-pages

Your app should now be available at https://YOUR_GIT_USER.github.io/YOUR_REPO/

⚠️ **GitHub.com Fallback** ⚠️