Deploying Your React Project to GitHub Pages Using Git Worktrees

2024-10-14

Deploying a React project to GitHub Pages can be quite straightforward once you know the steps. In this post, I'll guide you through setting up a gh-pages branch for deployment using Git worktrees. This method is efficient, clean, and helps keep your Git repository well-organized. Special thanks to Sangsoo Nam for his excellent guide, which inspired this process.

Other platforms which use a build step like Svelte, can also be deployed using this method.

🤔 Why GitHub Pages?

GitHub Pages is a convenient, free service provided by GitHub that allows you to host static websites straight from your repository. It's perfect for deploying personal projects, demos, and portfolio pages without incurring any costs or dealing with complex hosting solutions. Let's dive into the step-by-step process of deploying a React app using a dedicated branch for GitHub Pages deployment.

Step 1️⃣: Set Up the gh-pages Branch

To host the built site, you will need a dedicated branch called gh-pages. Follow these commands to create this branch and set it up for deployment.

🛠️ Create the gh-pages Branch

Start by creating a branch named gh-pages in your repository. This branch will hold the static files for your GitHub Pages deployment.

git branch gh-pages
git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initial commit"
git checkout master
  • git branch gh-pages: Creates a new branch named gh-pages.
  • git checkout --orphan gh-pages: Creates a new branch without any history. This is useful for making gh-pages independent of your main development branch.
  • git reset --hard: Resets the branch to an empty state.
  • git commit --allow-empty -m "Initial commit": Creates an empty initial commit on gh-pages.
  • git checkout master: Returns to the main development branch (usually master or main).

🗂️ Set Up Worktree for Deployment

Git's worktree feature allows us to work with multiple branches simultaneously in different folders, making it easier to manage the gh-pages branch.

rm -rf dist
git worktree add dist gh-pages
  • rm -rf dist: Removes any existing dist directory (to avoid any conflicts). Be careful as this command deletes files permanently.
  • git worktree add dist gh-pages: Adds a worktree for the gh-pages branch in a folder called dist. This folder will be used to manage the deployment.

Step 2️⃣: Build Your React Project

Once your gh-pages branch is set up, it is time to build your React project. The built version will be placed in the dist folder, ready to be deployed.

If you are using pnpm, simply run the following command:

pnpm build

This will generate all the necessary static files (usually in a build or dist directory, depending on your configuration) needed to deploy the website.

If you're not using pnpm, you can replace it with your preferred package manager, such as npm or yarn.

Step 3️⃣: Deploy to GitHub Pages

Now that your site is built, you can deploy it to GitHub Pages.

📂 Navigate to the dist Directory

Change to the directory where your worktree is set up for the gh-pages branch:

cd dist

📤 Commit and Push the Changes

Commit your changes and push them to the gh-pages branch to deploy the website.

git add .
git commit -m "Deploy"
git push origin gh-pages
  • git add .: Stages all changes for commit.
  • git commit -m "Deploy": Commits the staged files with the message "Deploy".
  • git push origin gh-pages: Pushes the changes to the remote gh-pages branch, which triggers GitHub Pages to update your live site.

Next time you want to deploy updates, simply repeat the build process, navigate to the dist directory, commit the changes, and push them to the remote gh-pages branch.

Step 4️⃣: (Optional) Remove the Worktree

Once you have deployed your site, you can remove the dist worktree if you don't need it anymore. However, if you plan to continue deploying updates, you can keep the worktree for future deployments.

git worktree remove dist

This step is optional but helps keep your project directory clean, especially if you don't want an extra dist directory hanging around.

🏁 Wrapping Up

That's it! You've successfully deployed your React project to GitHub Pages using a dedicated gh-pages branch and Git worktree. This approach is efficient for keeping your project organized while still benefiting from easy deployment.

The key benefit of this method is that your deployment branch gh-pages is isolated from your main branch master or main, keeping your project clean. Additionally, by using Git worktrees, you can manage multiple branches in separate folders seamlessly.

📋 Summary

  • Set up a gh-pages branch for deployment.
  • Use Git worktree to manage the gh-pages branch in a separate folder (dist).
  • Build your React project and deploy it to GitHub Pages by pushing to the gh-pages branch.
  • Optionally remove the worktree to keep your project directory clean.

I hope this guide has been helpful for deploying your React project to GitHub Pages! Feel free to reach out if you have any questions or suggestions for improving this process.