Deploying Your React Project to GitHub Pages Using Git Worktrees
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 namedgh-pages
.git checkout --orphan gh-pages
: Creates a new branch without any history. This is useful for makinggh-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 ongh-pages
.git checkout master
: Returns to the main development branch (usuallymaster
ormain
).
🗂️ 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 existingdist
directory (to avoid any conflicts). Be careful as this command deletes files permanently.git worktree add dist gh-pages
: Adds a worktree for thegh-pages
branch in a folder calleddist
. 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 asnpm
oryarn
.
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 remotegh-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.