React's dynamic routing lets you create seamless navigation experiences within your single-page application (SPA). But when it comes to deploying your masterpiece on GitHub Pages, you might encounter a roadblock. GitHub Pages, while fantastic for hosting static content, doesn't natively support the magic of client-side routing. Fear not, fellow developer! This blog post equips you with the knowledge to get your React routes working smoothly on GitHub Pages.
Understanding the Challenge
By default, React Router utilizes the BrowserRouter to manage navigation based on the URL path. Unfortunately, GitHub Pages serves content based on file paths. This mismatch leads to 404 errors when users try to access specific routes directly (e.g., yourusername.github.io/about).
Conquering the Challenge: Two Routes to Success
There are two main approaches to make React routing work on GitHub Pages:
1. Embrace the Hash:
Swap
BrowserRouterforHashRouterfrom React Router DOM.This approach uses the hash fragment (#) in the URL to differentiate routes.
- Users will see URLs like
yourusername.github.io/#/about.
- Users will see URLs like
import React from 'react';
import { HashRouter, Routes, Route } from 'react-router-dom';
// Example components for different routes
const Home = () => <h2>Home</h2>;
const About = () => <h2>About Us</h2>;
const Contact = () => <h2>Contact Us</h2>;
function App() {
return (
<HashRouter>
<Routes>
{/* Route for the home page */}
<Route path="/" element={<Home />} />
{/* Route for the about page */}
<Route path="/about" element={<About />} />
{/* Route for the contact page */}
<Route path="/contact" element={<Contact />} />
{/* Catch-all route in case of unmatched paths */}
<Route path="*" element={<h1>404 Not Found</h1>} />
</Routes>
</HashRouter>
);
}
export default App;
2. The 404.html Rescue:
Create a custom
404.htmlfile within your React app'sbuildfolder (or wherever your deployment process outputs the production files).This file acts as a catch-all for unmatched routes.
Use JavaScript to redirect the user to the root (
/) of your application.
Here's a breakdown of the 404.html approach:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>404 Not Found</title>
</head>
<body>
<h1>Whoops! Looks like this page is lost.</h1>
<script>
window.location.href = "/"; // Redirect to root
</script>
</body>
</html>
Deployment Considerations
Ensure your build process for GitHub Pages includes the necessary routing configuration (e.g., using
HashRouter).Set the
homepagefield in yourpackage.jsonto the base URL of your deployed application. This helps React Router construct proper URLs.