How to Deploy React Application On GitLab Page With Router For Free

Checkout this site — Garrick.monster. It is completely free to deploy and navigation ready. Want to know how it is done? Here is how.

1. Setting Up GitLab

I assume you are familiar with setting up a GitLab account and creating a GitLab repo, but if you don’t here is the link

Make sure you have your gitlab repo ready, if you are shy to share your code to the public, you may choose to private your repo.

2. Init React Project

Run this command, I am using typescript here, why not.

yarn create react-app my-app --template typescript

If you have your repo create ready, you may run this to create react in your current repo

yarn create react-app . --template typescript

Change the display text to your desire text and commit it.

3. Create GitLab Pipeline

Building The React Page

To build the react pages, we need to ask GitLab to pull the latest or desired NodeJS image and compile the react project into a single page application which can be run by GitLab pages.

Create a yaml file name .gitlab-ci.yml in your project root directory.

The first stage that we need to ask GitLab CI to do is build stage where GitLab will compile the application and store it at build folder.

Setting Up The Page According to Gitlab Requirement

The second stage that we need to ask GitLab CI to do is move all the build folder files to public as GitLab will take public path folder as the root directory to serve to the outside world.

- mv build public # Move whole build folder to public
- cp public/index.html public/404.html # copy index.html to 404.html so that if there is a page not found error, we can still display our desire custom 404 page.

The default domain rules for GitLab pages is listed here — GitLab Pages Default Domain

In this case, GitLab pages will be using this format

http(s)://groupname.example.io/projectname
https://garrick-open-source.gitlab.io/gitlab-pages-with-react-router/

At package.json, you will need to add homepage:gitlab-pages-with-react-router as this path will serve as the react root directory for the react application — https://garrick-open-source.gitlab.io/gitlab-pages-with-react-router/

{
"name": "gitlab-pages-with-react-router",
"homepage": "gitlab-pages-with-react-router",
}

In order for the assets to work perfectly, PUBLIC_URL has to be set to the GitLab page url which is https://garrick-open-source.gitlab.io/gitlab-pages-with-react-router so that your public assets can point correctly.

Final Yaml File

After committing your .gitlab-ci.yml file to the repo, GitLab will start to run the pipeline accordingly to build and release your application.

After all stages is passed and completed, you should be able to browse your website at https://garrick-open-source.gitlab.io/gitlab-pages-with-react-router

Tips: Sometimes you might be facing some issue where the page has been
rebuild but there is no changes in the website, press CRTL+F5 to clear
the cached.

4. Setting Up Custom Domain

To setup custom domain what you need to do is make sure you have a custom domain or subdomain and DNS point is point to GitLab. Gitlab Custom Domain

Go to gitlab Setting -> Pages -> New Domain , follow the instruction and update your DNS record. After setting up the DNS record, click verify to verify if the domain has been attached to the pages successfully.

Then we need to have some tweaks at our GitLab CI

Remove the homepage value in package.json as now we are pointing to the root domain.
Change the PUBLIC_URL path to your domain, in this case https://gitlab-react-page.garrick.monster

When GitLab CI finished buidling your repo, your page should be accessible by the custom domain. Take note that the old GitLab Default pages url will not be able to access anymore due to the change of PUBLIC_URL setting and homepage value.

5. Adding Router

We are going to use react-router-dom as our router module.

Take note that GitLab Pages is not a server, it only serve static html file. Hence you cant expect the routing work exactly like a traditional server.

When you are trying to access https://gitlab-react-page.garrick.monster/hello-world , GitLab pages will serve you https://gitlab-react-page.garrick.monster/hello-world/index.html instead which cause error 404 and you will stuck in a loop thinking what goes wrong.

To avoid this issue , instead of using BrowserRouter, we are going to use HashRouter instead. By adding a #/ between the domain and the path, we are not going to trigger the browser to reload the page which brings to error 404.