docs: Configure routing for GitHub Pages deployment

ishansasika · ishansasika · commit 1b90b03f4388 · 2025-12-13T11:26:13.000+05:30
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -119,6 +119,15 @@ Contact form (src/app/pages/contact/Contact.tsx:6):
 - onSubmit handler prevents default, logs data, shows alert, resets form
 - No backend integration - implement API call in handleSubmit as needed
 
+### GitHub Pages Routing
+The app is configured to work with GitHub Pages base paths:
+- `BrowserRouter` uses `basename={import.meta.env.BASE_URL}` (src/App.tsx:22)
+- `BASE_URL` comes from `vite.config.ts` base setting
+- `public/404.html` handles client-side routing on GitHub Pages
+- `index.html` includes redirect handler for SPA navigation
+
+When deployed to GitHub Pages, the base path (e.g., `/react-tailwind-template/`) is automatically applied to all routes. For local development, `BASE_URL` is `/`.
+
 ### File Extensions
 - `.tsx` - React components with JSX
 - `.ts` - TypeScript without JSX (barrel exports, utils)
diff --git a/index.html b/index.html
@@ -5,6 +5,16 @@
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>React Vite Tailwind Template</title>
+    <script>
+      // GitHub Pages SPA redirect handler
+      (function() {
+        var redirect = sessionStorage.getItem('redirect');
+        sessionStorage.removeItem('redirect');
+        if (redirect && redirect !== location.href) {
+          history.replaceState(null, null, redirect);
+        }
+      })();
+    </script>
   </head>
   <body>
     <div id="root"></div>
diff --git a/public/404.html b/public/404.html
@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>Redirecting...</title>
+    <script>
+      // GitHub Pages 404 handler for client-side routing
+      // This script takes the current full path and redirects to the index page
+      // with the path as a query parameter, which is then handled by the SPA
+      sessionStorage.setItem('redirect', location.href);
+      location.replace(location.origin + location.pathname.split('/').slice(0, -1).join('/') + '/?redirect=' + encodeURIComponent(location.pathname + location.search + location.hash));
+    </script>
+  </head>
+  <body>
+  </body>
+</html>
diff --git a/src/App.tsx b/src/App.tsx
@@ -19,7 +19,7 @@ const AppRoutes = () => {
 
 const App = () => {
   return (
-    <BrowserRouter>
+    <BrowserRouter basename={import.meta.env.BASE_URL}>
       <div className="page-container">
         <Header />
         <div className="content-wrapper">
diff --git a/vite.config.ts b/vite.config.ts
@@ -4,6 +4,5 @@ import react from '@vitejs/plugin-react'
 // https://vite.dev/config/
 export default defineConfig({
   plugins: [react()],
-  // IMPORTANT: Update this to match your GitHub repository name
-  base: '/react-vite-tailwind-template/',
+  base: '/react-tailwind-template/',
 })
