Hosting a Webpack Project on GitHub Pages

This guide will help you host your Webpack project on GitHub Pages by creating a dedicated hosting branch and setting up the deployment process.

1. Create and Switch to the `hosting` Branch

git checkout -b hosting

2. Install `gh-pages` and `copy-webpack-plugin`

Install the necessary packages (make sure to be in the correct directory):

npm install gh-pages copy-webpack-plugin --save-dev

Why we use the gh-pages is a little obvious. As of the copy-webpack-plugin, we use it to copy the files from one location to another in the build process. In this case, the 404.html file from src to the dist directory. Without this plugin, any files not referenced by webpack entry points would not be available in the deploy site. Put differently, it ensures that the 404.html file is included in the final build output.

3. Update Your Webpack Configuration

Modify webpack.config.js to use copy-webpack-plugin for copying 404.html to the dist directory.

const path = require('path');
const CopyWebpackPlugin = require('copy-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/'
  },
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        { from: 'src/404.html', to: '404.html' }
      ]
    })
  ],
  // other configuration settings 
};

4. Add `404.html` to Your `src` Directory

Ensure your 404.html file is located in the src directory.

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>404</title>
  <meta http-equiv="refresh" content="0;url=./index.html">
</head>
<body>
</body>
</html>

We use the 404.html with a redirect to index.html for the following reason. GitHub pages serves a 404.html file when a URL does not match any existing files in the repository. In single-page applications (SPAs) like those built using Webpack, all routing is typically handled client-side, meaning the server should always serve index.html regardless of the URL path.

By creating a 404.html file that redirects to index.html, we ensure that any unknown routes (i.e., those handles by the client-side router) will still load the SPA correctly. This prevents GitHub Pages 404 error page from appearing and allows client-side to handle the navigation. This HTML file uses a meta refresh tag to redirect the browser to index.html instantly.

5. Update `package.json` Scripts

Modify your package.json to include the build and deploy scripts:

{
  "scripts": {
    "build": "webpack --mode production",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  }
}

Updating the package.json scripts is crucial for automating the build and deployment process. Here's why each script is needed:

build: This script runs Webpack in production mode, creating an optimized build of your project in the dist directory. This is necessary because the deployment process should always use the latest build output.
predeploy: This script runs automatically before the deploy script. By setting it to run npm run build, we ensure that the build step is executed every time before deploying. This guarantees that the deployed version is always up-to-date.
deploy: This script uses gh-pages to publish the contents of the dist directory to the gh-pages branch. The gh-pages package simplifies the process of deploying to GitHub Pages by handling the creation and pushing of the gh-pages branch for you.

6. Add a `CNAME` File (Optional for Custom Domain)

If you’re using a custom domain, create a CNAME file in the root of your project:

echo 'www.yourdomain.com' > CNAME

If you don’t need a custom domain, you can skip this step. This can also be accessed on the "Pages" section in your GitHub repo if you need to add a custom domain name.

7. Deploy Your Project

Deploy your project to GitHub Pages using the deploy script:

npm run deploy

8. Commit and Push Your Changes

Commit your changes to the hosting branch:

git add .
git commit -m "Setup project for GitHub Pages deployment"
git push origin hosting

Create a pull request on GitHub. Review then merge PR.

9. Update GitHub Pages Settings

In your GitHub repository:

Go to Settings > Pages.
Set the source to the gh-pages branch.

10. Verify Deployment

After deployment, your site should be live at https://john-walter-munene.github.io/Restaurant--Page/, your directory details will be referenced here.

This setup will streamline your deployment process, keeping everything organized on the hosting branch.

john-walter-munene/host.md

Hosting a Webpack Project on GitHub Pages

1. Create and Switch to the hosting Branch

2. Install gh-pages and copy-webpack-plugin