https://github.com/pjnalls/spa-404-fix
A Guide to resolve a common 404 error for SPA apps deployed to GitHub Pages
https://github.com/pjnalls/spa-404-fix
404 file-not-found gh-pages page-not-found single-page-applications spa
Last synced: about 2 months ago
JSON representation
A Guide to resolve a common 404 error for SPA apps deployed to GitHub Pages
- Host: GitHub
- URL: https://github.com/pjnalls/spa-404-fix
- Owner: pjnalls
- License: mit
- Created: 2023-12-22T12:25:28.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-31T21:58:20.000Z (4 months ago)
- Last Synced: 2025-07-22T02:05:42.277Z (2 months ago)
- Topics: 404, file-not-found, gh-pages, page-not-found, single-page-applications, spa
- Homepage: https://problemesolvers.github.io/about/
- Size: 169 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GitHub Pages 404 Error Page Fix
⚡️🐞🧑🏫 How to resolve a common 404 error when deploying a SPA (single-page application) as static content to GitHub Pages
## Problem Description
After a SPA with client-side routing is deployed to Pages successfully, the app will return a 404-error page under the following conditions:
1️⃣ if the user refreshes the page on a non-root route
2️⃣ if the user navigates via the browser's address bar to a non-root route
## Solution Description
Create a `404.html` and add it to your `public` folder.
`404.html` should redirect to the root of your SPA (`index.html`) with a param of the current route name (e.g., "`currentRoute`") the user requested.
Once the SPA returns to the root of the app once again, it can parse the URL to get the current route and navigate to it with the client-side router.
## `router` Solution Steps
### **Step** 1️⃣, add `~/public/404.html` and following code to it:
```html
```
### **Step** 2️⃣, add `~/public/redirect.js` and following code to it:
```javascript
(function () {
window.location.href = `/${
window.location.pathname
? `?currentRoute=${window.location.pathname.slice(1)}`
: ""
}`;
})();
```
### **Step** 3️⃣, add line after app is instantiated (e.g., `~/src/main.jsx`):
```diff
/** ... **/
ReactDOM.createRoot(document.getElementById("root")).render(
);
+router.navigate(window.location.href.split("?")[1]?.split("=")[1]);
```
### Done.
## `router` Solution References
### **Step** 1️⃣, Create a `~/src/router.jsx` file and add code:
```jsx
import { createBrowserRouter } from "react-router-dom";
import App from "./App/App";
import Home from "./Home";
import About from "./About";
export const router = createBrowserRouter([
{
path: "/",
element: ,
children: [
{
path: "/",
element: ,
},
{
path: "/about",
element: ,
},
],
},
]);
```
### **Step** 2️⃣, Add the following code to `~/src/main.jsx` below for basic web app instantiation reference:
```jsx
import React from "react";
import ReactDOM from "react-dom/client";
import { RouterProvider } from "react-router-dom";
import { router } from "./router";
import "./index.css";
ReactDOM.createRoot(document.getElementById("root")).render(
);
router.navigate(window.location.href.split("?")[1]?.split("=")[1]);
```
---
There's another pattern to the solution that has the same effect documented below:
## `Routes` Solution Steps
### **Step** 1️⃣, add `~/public/404.html` and following code to it:
```html
```
### **Step** 2️⃣, add `~/public/redirect.js` and following code to it:
```javascript
(function () {
window.location.href = `/${
window.location.pathname
? `?currentRoute=${window.location.pathname.slice(1)}`
: ""
}`;
})();
```
### Step 3️⃣, ensure `Routes` have been added correctly in `App`:
```tsx
}
/>
} />
} />
} />
} />
```
### Done.
## `Routes` Solution References
### 🌐 See `~/src/main.tsx` below for basic web app instantiation reference:
```tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import { MantineProvider } from "@mantine/core";
import "@mantine/core/styles.css";
import App from "./pages/App";
import "./styles/index.scss";
ReactDOM.createRoot(document.getElementById("root")!).render(
);
```