jquery.app
English
EnglishDeutschFrancaisEspanol日本語Nederlands

GitHub Pages Tools

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.

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.

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