How to deploy React projects on GitHub Pages
Hi, fellow developers!
We know how important it is to us to create and maintain a decent portfolio. GitHub is the main professional platform to do so.
Today, I intend to focus on one particular feature: GitHub Pages, created for you to easily deploy your projects and make them visible to the world.
How to deploy HTML projects on GitHub Pages
On that matter, there is not much I can add to the excellent official documentation. The process is easy, linear and surpriseless.
How to deploy React projects on GitHub Pages
I normally follow this guide to deploy a React App on GitHub Pages. I truly appreciate and recommend it but I wanted to add a few details so as to prevent others to make the same mistakes and failed attempts that I did.
Filling in the blanks, here is my consolidated guide to deploy your React App on GitHub Pages:
1. Check your node version is compatible
You will need Node 8.10.0 or later installed.
To check what version your local machine has, you only need to open a Terminal and digit:
node -v
2. Create or prepare your React App
You then need your React App ready for use.
If you need to create it now, digit the following command in your Terminal:
npx create-react-app your-app-name
Else, let’s get you to the next step.
3. Install the GitHub Pages dependency
cd your-app-name
npm install gh-pages — save-dev
4. Modify the package.json file
You need to add a top homepage property as follows:
“homepage”: “http://{username}.github.io/{your-app-name}"
Also, add these elements to the scripts property:
“scripts”: {
“predeploy”: “npm run build”,
“deploy”: “gh-pages -d build”,
…
}
5. Create a new empty repository
Create the GitHub repository that will host your React app.
Here, it is crucial that you DO NOT select the “Add a README file” option that would set main as the default branch, because it will later create conflicts with your master.
6. Connect the app with the repository
To do that, you may already know that you need both these commands:
git init (optional)
git remote add origin your-repository-url
However, I marked git init as optional because it is important that you recall where your app comes from. In my case, they often come from other project repositories and have already been initialized. If you are in doubt, you can digit:
ls -a
And see if a .git file appears. If not and only if not, proceed to git init!
7. Push what you need to
If you want your code to be visible on your repository, you need to add, commit and push it directly on your master, like so:
git add .
git commit -m “message”
git push origin master
8. Deploy
Finally, when all previous steps were implemented, digit the command:
npm run deploy
When successful, its message ends with “Published”.
Note that a gh-pages branch was created on your repository, responsible for hosting your app and deploying it.
It is important that this step is the last one you execute!
9. Patience
It already happened that freshly created URLs presented a 404 error. Sometimes, the best advice may be to just sleep on it, and it might work when trying again 24h later.
Restrictions and alternatives
Usage limits of GitHub Pages
You should be aware that some apps do not meet GitHub requirements to be deployed on its Pages, for instance if it proves too heavy.
Alternatives
Here are practical alternatives to still be able to deploy your projects:
Basically, they all offer the option to synchronize your GitHub repository with their deploy service.
If you try them after a failed attempt at GitHub Pages, make sure you first clean the package.json and gh-pages branch, or create a new repository from scratch.
Now, enjoy your deployed page and post about it!
References
Hope it helps!
Cheers,
Juliette.
