Hosting on GitHub Pages

From the blog:
isomorphic-webpack - Universal module consumption using webpack - Interview with Gajus Kuizinas

A package known as gh-pages allows us host our application on GitHub easily. You point it to your build directory first. It will then pick up the contents and push them to the gh-pages branch.

Despite its name, the package works with other services that support hosting from a Git repository as well. But given GitHub is so popular, it's good enough for demonstrating the idea.

In practice, you would likely have more complicated setup in place that would push the result to some other service through a Continuous Environment (CI) system. The approach discussed here is enough for small projects and demonstrations that can be entirely static.

Setting Up gh-pages#

To get started, execute

npm i gh-pages --save-dev

We are also going to need an entry point at package.json:

package.json

{
  ...
  "scripts": {
"deploy": "gh-pages -d build",
... }, ... }

To make the asset paths work on GitHub Pages, we also need to tweak a webpack setting known as output.publicPath. Otherwise they will point at root and that won't work unless you are hosting behind a domain root (say survivejs.com) directly.

publicPath gives control over the resulting urls you see at index.html for instance. If you are hosting your assets on a CDN, this would be the place to tweak. In this case, it's enough to set it to point the GitHub project like this:

...

module.exports = function(env) {
  if (env === 'production') {
    return merge(
      common,
{ output: { // Tweak this to match your GitHub project name publicPath: '/webpack-demo/' } },
parts.loadJavaScript(PATHS.app), ... ); } ... };

After building (npm run build) and deploying (npm run deploy), you should have your application from the build/ directory hosted through GitHub Pages. You should find it at https://<name>.github.io/<project> (github.com/<name>/<project> at GitHub) assuming everything went fine.

If you need a more elaborate setup, use the Node.js API that gh-pages provides. The default CLI tool it provides is enough for simple purposes, though.
GitHub Pages allows you to choose the branch where you deploy. It is possible to use the master branch even. This is enough for minimal sites that don't need bundling. You can also point below the ./docs directory within your master branch and maintain your site. That is useful for small projects.

Archiving Old Versions#

gh-pages provides an add option that is useful for archival purposes. This is great especially for documentation sites. The idea goes as follows:

  1. Copy the old version of the site in a temporary directory and remove archive directory from it. You can name the archival directory as you want.
  2. Clean and build the project.
  3. Copy the old version below build/archive/
  4. Set up a script to call gh-pages through Node.js like this: ghpages.publish(path.join(__dirname, 'build'), { add: true }, callback);. You should capture possible error in that callback.

Deploying to Other Environments#

Even though you can push the problem of deployment outside of webpack, there are a couple of utilities that may come in handy:

Resolving output.publicPath Dynamically#

If you don't know publicPath beforehand, it's possible to resolve it based on the environment like this:

  1. Set __webpack_public_path__ = window.myDynamicPublicPath; in the application entry point and resolve it as you see fit.
  2. Remove output.publicPath setting from your webpack configuration.
  3. If you are using ESLint, set it to ignore the global:

.eslintrc.js

module.exports = {
  ...
  "globals": {
    "__webpack_public_path__": true
  },
  ...
};

When you compile, webpack picks up __webpack_public_path__ and rewrites it so that it points to webpack logic.

Conclusion#

The same idea works with other environments too. You can set up gh-pages to push into a branch you want. After this step, we have a complete development and production setup.

Previous chapterCleaning the Build
Next chapterOptimizing Build

This book is available through Leanpub. By purchasing the book you support the development of further content. A part of profit (~30%) goes to Tobias Koppers, the author of Webpack.

Need help?