Solve 404 when using BrowserRouter with GitHub pages

Context When you use the BrowserRouter component from the react-router-dom library, you will be able to set up routes in your React JS application that can be visited from the frontend. It works on your local development environment. But it stops working after deploying it to GitHub pages! You will see a 404 error whenever you try to visit any of the routes. One of the "fix" that I used to do was to use a HashRouter to solve this issue. This is because the original path remains the same. We just use anchors or "hashes" to switch between page content. Why Let's first look at why BrowserRouter is not friendly with GitHub Pages. GitHub Pages has this thing where when we access an URL other than the root URL, it looks for a physical folder there. So, when we visit /country/india for example, it will look for /country/india/index.html. This way of looking for files is not always feasible for us in production. Perhaps SSG would help fix this issue but even there we are limited because we need to know in advance about all the countries in the world so that we can generate html files for them. Fix So, how do we fix it now? There is this feature in GitHub Pages where if we put a file called "404.html", at the root of your static file deployment, it will use that as the 404 page instead of the one that GitHub shows by default. This is simply an out of the box GitHub feature that is provided to the user to show their own custom 404 page. We are going to take advantage of this custom 404 page

Mar 26, 2025 - 17:35

Solve 404 when using BrowserRouter with GitHub pages

Context

When you use the BrowserRouter component from the react-router-dom library, you will be able to set up routes in your React JS application that can be visited from the frontend.

It works on your local development environment. But it stops working after deploying it to GitHub pages! You will see a 404 error whenever you try to visit any of the routes.

One of the "fix" that I used to do was to use a HashRouter to solve this issue. This is because the original path remains the same. We just use anchors or "hashes" to switch between page content.

Why

Let's first look at why BrowserRouter is not friendly with GitHub Pages. GitHub Pages has this thing where when we access an URL other than the root URL, it looks for a physical folder there.

So, when we visit /country/india for example, it will look for /country/india/index.html. This way of looking for files is not always feasible for us in production. Perhaps SSG would help fix this issue but even there we are limited because we need to know in advance about all the countries in the world so that we can generate html files for them.

Fix

So, how do we fix it now?

There is this feature in GitHub Pages where if we put a file called "404.html", at the root of your static file deployment, it will use that as the 404 page instead of the one that GitHub shows by default. This is simply an out of the box GitHub feature that is provided to the user to show their own custom 404 page.

We are going to take advantage of this custom 404 page