[BUG]: Refreshing on any non-root route (e.g. /settings) returns GitHub Pages 404

[AditthyaSS]

Bug Description

Navigating to any page other than the home page (e.g. Settings) works fine
when reached by clicking links inside the app. However, refreshing the
browser while on that route, or opening that URL directly/in a new tab,
returns GitHub Pages' native 404 page instead of loading the app -and it
does not redirect back to the home page either.

This is likely because the app uses client-side routing (react-router-dom),
but GitHub Pages has no rewrite rule to fall back to index.html for unknown
paths, so direct requests to non-root routes 404 at the hosting level before
React Router ever gets a chance to handle them.

Steps to Reproduce

1. Go to https://orgexplorer.aossie.org/
2. Click through to the Settings page (or any non-home page)
3. Refresh the browser (F5), or copy the current URL and open it in a new tab
4. Observe GitHub Pages' 404 "File not found" page instead of the app

Logs and Screenshots

Environment Details

• OS: Windows 11
• Browser: Chrome 120
• Node.js: v24.13.0

Impact

Medium - Feature works but has issues

Code of Conduct

• I have joined the Discord server and will post updates there
• I have searched existing issues to avoid duplicates

[sawastik7-bit]

hi @AditthyaSS
can i work on this issue, I think its a react router issue.
I am very confident that i can solve this issue.

[AditthyaSS]

Hi @sawastik7-bit , thanks for the interest! Since I found and filed
this issue, I've already dug into the root cause and have started looking
at a fix - I've asked the maintainer @rahul-vyas-dev to assign it to me and I'm just
waiting on confirmation.

Will update here once I hear back.

[kpj2006]

@CodeRabbit what would be the possible reason behind this?

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
gh issue view 105 --repo AOSSIE-Org/OrgExplorer --comments

Length of output: 900

---

🏁 Script executed:

#!/bin/bash
gh issue view 105 --repo AOSSIE-Org/OrgExplorer --json title,body,labels

Length of output: 1885

---

G'day @kpj2006! Good question, mate.

The root cause is basically what's already spelled out in the issue and what sawastik7-bit suspected — it's a static-hosting quirk rather than a bug in react-router-dom itself:

• The app uses client-side routing (react-router-dom), which means React Router only takes over navigation after the app's JS has loaded in the browser.
• When you click a link inside the app, React Router intercepts it and handles the route change on the client — no problem there.
• But when you refresh on a route like /settings, or paste that URL straight into a new tab, the browser sends a fresh HTTP request straight to GitHub Pages for the path /settings.
• GitHub Pages is a static file server — it has no server-side rewrite rules, so it looks for an actual file/folder at that path, doesn't find one, and serves its own generic 404 page before React or React Router ever gets loaded.

This is a well-known limitation of SPA deployments on GitHub Pages. A couple of common fixes:

1. 404.html redirect trick (works with BrowserRouter) — Add a custom 404.html in the public/build output that redirects to index.html with the intended path encoded in the query string, plus a small script in index.html that decodes it and pushes the correct route via history.replaceState. This is the pattern used by the popular spa-github-pages project.
2. Switch to HashRouter — Simplest fix, since routes become /#/settings, and GitHub Pages always serves index.html for the root regardless of the hash fragment. Trade-off: URLs look less clean and it can complicate some SEO/analytics setups.
3. Some CI/build setups also just copy index.html to 404.html post-build as a lightweight equivalent of option 1 (no redirect logic needed, since GitHub Pages serves 404.html verbatim, and once index.html's JS loads, React Router reads window.location and renders the right route immediately).

Given AditthyaSS is already looking into a fix with the maintainer's go-ahead, this context might help move things along once assigned.

🐰💭