fix: resolve 404 error on page reload for GitHub Pages SPA routing

[Gitjay11]

Addressed Issues:

Fixes #112

Screenshots/Recordings:

Before — As shown in the issue, navigating to orgexplorer.aossie.org/repositories
and refreshing shows GitHub Pages' 404 error (see #112 for the recording).

After — The fix will be verified post-merge once deployed to GitHub Pages.

How it works:
When GitHub Pages can't find a file at a path like /repositories, it serves our custom 404.html, which encodes the path and redirects to /?/repositories. A decode script in index.html then restores the real URL via history.replaceState() before React mounts, so React Router renders the correct page seamlessly.

Refresh /repositories
  → GitHub Pages serves 404.html
  → 404.html redirects to /?/repositories
  → index.html script decodes → restores /repositories
  → React Router renders <RepositoriesPage /> ✅

Additional Notes:

• Uses the well-known spa-github-pages technique — a zero-dependency, server-config-free solution specifically designed for GitHub Pages SPAs.
• Two files changed:
  • public/404.html (new) — intercepts GitHub Pages 404s and encodes the path as a query string redirect.
  • index.html (modified) — decodes the redirected path and restores the correct URL before React Router mounts.
• No changes to routing logic, dependencies, or existing components.

Checklist

• My code follows the project's code style and conventions
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have joined the Discord server and I will share a link to this PR with the project maintainers there
• I have read the Contributing Guidelines

⚠️ AI Notice - Important!

We encourage contributors to use AI tools responsibly when creating Pull Requests. While AI can be a valuable aid, it is essential to ensure that your contributions meet the task requirements, build successfully, include relevant tests, and pass all linters. Submissions that do not meet these standards may be closed without warning to maintain the quality and integrity of the project. Please take the time to understand the changes you are proposing and their impact.

Summary by CodeRabbit

• Bug Fixes
  • Improved single-page application routing on GitHub Pages.
  • Restores direct navigation to nested routes after 404 redirects.
  • Supports deployments hosted under a subpath while preserving the requested URL.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: cb25aecc-1d26-447f-9e1d-c011224bc7df

📥 Commits

Reviewing files that changed from the base of the PR and between d83fe88 and 0196c30.

📒 Files selected for processing (2)

• index.html
• public/404.html

---

Walkthrough

Added GitHub Pages SPA fallback handling: public/404.html redirects failed routes to the site root with encoded route data, while index.html restores the original route using browser history.

Changes

SPA route recovery

Layer / File(s)	Summary
GitHub Pages route recovery flow public/404.html, index.html	public/404.html encodes the requested route and redirects to the site root; index.html decodes the route and removes the redirect query through window.history.replaceState.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• AOSSIE-Org/OrgExplorer issue 105 — Addresses the same GitHub Pages 404 behavior affecting direct navigation and refreshes of SPA routes.

Suggested labels: Typescript Lang

Poem

I’m a rabbit hopping through routes,
Past 404s and broken boots.
The root now knows where paths should go,
While history keeps the trail in tow.
Hop, hop—your SPA is home! 🐇

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: fixing GitHub Pages SPA reload 404s.
Linked Issues check	✅ Passed	The changes implement the requested reload fix by adding 404 redirect handling and route restoration for non-root SPA paths.
Out of Scope Changes check	✅ Passed	The PR stays focused on GitHub Pages routing recovery and does not introduce unrelated code changes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}