jquery.app
English
EnglishDeutschFrancaisEspanol日本語Nederlands

GitHub Pages Tools

Free GitHub Pages SPA 404 Helper

Create a small GitHub Pages 404 fallback snippet for client-side routing and static SPA deployments.

Loading tool...

What is GitHub Pages SPA 404 Helper?

GitHub Pages serves static files and does not know client-side routes unless a matching file exists. A single-page app can show 404 when a visitor opens a deep route directly. A 404 fallback can redirect the browser back to the app entry point while preserving the requested path for the router.

quickAnswer

Generate a 404.html fallback for single-page apps deployed on GitHub Pages. The fallback redirects deep client-side routes to the app entry point while preserving the original path for the router to handle.

Last updated: 2026-06-11

limitations

  • This is a generic client-side fallback, not a server-side redirect configuration. It relies on JavaScript in the browser to extract the original path and pass it to the router.
  • The client-side router must be configured to read the preserved path from the query string or hash and render the matching route. Not all routers handle this redirect pattern automatically.
  • This approach does not fix navigation or refresh behavior within the SPA after the initial redirect. Router-level configuration is still needed for full client-side routing support.

Sources:MDN Web Docs · W3C Specifications · jquery.app on GitHub

How to use this tool

  1. Enter the app base path. Use / for a user or custom domain site, or /repo-name/ for a project page.
  2. Choose whether the fallback should store the original path in the query string or hash.
  3. Copy the generated 404.html file into the published site root.
  4. Test a deep route directly after deployment.

What you can use it for

  • Fix direct visits to client-side routes on GitHub Pages.
  • Prepare a 404 fallback for React, Vue, Svelte, or vanilla routers.
  • Document the base path needed for project pages.

Use cases

Practical examples

example

Custom domain SPA

A site at www.example.com uses client-side routing. The helper generates a fallback that redirects deep routes back to / with the path preserved.

example

Project page SPA

A project deployed under /my-app/ needs the base path included so routes do not redirect to the domain root.

Common mistakes

  • Using / as the base path for a project page deployed under /repo-name/.
  • Forgetting to copy 404.html into the final dist folder.
  • Expecting this fallback to replace server-side redirects.

verification

  1. Deploy the site with the generated 404.html at the root, then open a deep route URL such as https://yoursite.com/some/deep/route directly in a browser.
  2. Confirm the page loads the SPA entry point and the router navigates to the deep route without showing a 404 or blank page.

FAQ

Questions about GitHub Pages SPA 404 Helper

Does this work for every router?

No. It is a generic fallback. Your router still needs to read the preserved path and render the matching route.

Where should 404.html go?

Place it in the published site root, next to index.html, CNAME, robots.txt, or other final output files.

Should normal static sites use this?

Usually no. A normal static site should publish real HTML files for important pages instead of routing everything through a fallback.

Related tools

More github pages tools

Github Pages

COOP/COEP/CORP Header Builder

Build Cross-Origin isolation headers for SharedArrayBuffer, WebAssembly threads, and cross-origin security. Choose from presets with debugging checklists.

Open tool

Also try

Also try

Seo

AI Crawler robots.txt Builder

Build a robots.txt policy for AI crawlers. Choose from open, selective, or strict presets and block specific AI training bots while allowing search engines.

Open tool