Merge pull request #11 from jamesmontemagno/copilot/fix-subpage-url-navigation

jamesmontemagno · web-flow · commit 2847bda637bd · 2025-10-30T12:06:21.000-07:00
Fix direct URL navigation for SPA routes on GitHub Pages
diff --git a/.vscode/memory/spa-routing-fix.md b/.vscode/memory/spa-routing-fix.md
@@ -0,0 +1,49 @@
+# SPA Routing Fix for GitHub Pages
+
+## Problem
+Single Page Applications (SPAs) using client-side routing (like React Router's `BrowserRouter`) face a common issue when deployed to GitHub Pages: direct navigation to subpages results in 404 errors.
+
+## Why This Happens
+- SPAs have only one `index.html` file at the root
+- All routing is handled client-side by JavaScript
+- When you visit `/mcp` directly, GitHub Pages looks for `/mcp/index.html`
+- Since this file doesn't exist, GitHub Pages returns a 404 error
+
+## Solution
+We implement the standard GitHub Pages SPA workaround using a two-step redirect:
+
+### Step 1: 404.html Redirect
+- Located in `public/404.html`
+- When GitHub Pages returns 404, it serves this file
+- The script captures the requested path (e.g., `/mcp`)
+- Converts it to a query parameter: `/?/mcp`
+- Redirects to the root with the path preserved
+
+### Step 2: index.html Path Restoration
+- Located in `index.html` (added script in `<head>`)
+- When the root loads, checks for the special query parameter format
+- Restores the original URL using `history.replaceState()`
+- React Router then handles the routing normally
+
+## How It Works (Example)
+1. User visits `https://mcpbadge.dev/mcp`
+2. GitHub Pages: "No file at /mcp/index.html" → Returns 404.html
+3. 404.html script: Redirect to `/?/mcp`
+4. Browser loads index.html with query parameter
+5. index.html script: Restore URL to `/mcp` 
+6. React Router: Route to MCP component
+
+## Files Modified
+- `public/404.html` - New file with redirect script
+- `index.html` - Added path restoration script
+- `src/App.tsx` - Fixed useLocation hook import (unrelated lint warning)
+
+## Testing
+Direct navigation to any route should now work:
+- `/` - Home page
+- `/mcp` - MCP Badges page
+- `/extensions` - VS Code Extensions page
+- `/settings` - Settings page
+
+## References
+This solution is based on the [spa-github-pages](https://github.com/rafgraph/spa-github-pages) approach, which is widely used by SPAs deployed to GitHub Pages.
diff --git a/.vscode/memory/spa-routing-visual-flow.md b/.vscode/memory/spa-routing-visual-flow.md
@@ -0,0 +1,86 @@
+# SPA Routing Fix - Visual Flow
+
+## Before Fix (Problem)
+```
+User visits: https://mcpbadge.dev/mcp
+         ↓
+GitHub Pages: "Looking for /mcp/index.html"
+         ↓
+GitHub Pages: "File not found!"
+         ↓
+Result: 404 Error Page ❌
+```
+
+## After Fix (Solution)
+```
+User visits: https://mcpbadge.dev/mcp
+         ↓
+GitHub Pages: "Looking for /mcp/index.html"
+         ↓
+GitHub Pages: "File not found! Serving 404.html"
+         ↓
+404.html script executes:
+  - Captures path: "/mcp"
+  - Encodes as query param: "?/mcp"
+  - Redirects to: https://mcpbadge.dev/?/mcp
+         ↓
+Browser loads: https://mcpbadge.dev/?/mcp
+         ↓
+GitHub Pages: "Serving /index.html"
+         ↓
+index.html script executes BEFORE React loads:
+  - Detects query param: "?/mcp"
+  - Decodes back to: "/mcp"
+  - Uses history.replaceState to change URL
+  - URL now shows: https://mcpbadge.dev/mcp
+         ↓
+React loads and sees URL: /mcp
+         ↓
+React Router routes to: MCP component
+         ↓
+Result: MCP page displays correctly ✅
+```
+
+## Key Technical Details
+
+### 404.html Script
+```javascript
+// Converts: /mcp → /?/mcp
+var segmentCount = 0; // Set to 0 for root domain
+l.replace(
+  l.protocol + '//' + l.hostname + 
+  '/?/' + l.pathname.slice(1) + 
+  l.hash
+);
+```
+
+### index.html Script
+```javascript
+// Converts: /?/mcp → /mcp
+if (l.search[1] === '/' ) {
+  var decoded = l.search.slice(1);
+  window.history.replaceState(null, null,
+    l.pathname.slice(0, -1) + decoded + l.hash
+  );
+}
+```
+
+## Why This Works
+
+1. **GitHub Pages behavior**: Always serves 404.html when file not found
+2. **Query parameters**: Don't trigger file lookups, always route to root
+3. **history.replaceState**: Changes URL without triggering navigation
+4. **Timing**: Redirect happens before React/Router initialize
+
+## Works With
+- All client-side routes: `/mcp`, `/extensions`, `/settings`
+- Hash fragments: `/mcp#section`
+- Query parameters: `/mcp?param=value`
+- Browser back/forward buttons
+- Bookmarks and direct links
+
+## Doesn't Break
+- Home page (`/`)
+- Existing navigation
+- Browser history
+- SEO (search engines see correct URLs)
diff --git a/index.html b/index.html
@@ -9,6 +9,31 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#24bfa5" />
     
+    <!-- Start Single Page Apps for GitHub Pages -->
+    <script type="text/javascript">
+      // Single Page Apps for GitHub Pages
+      // MIT License
+      // https://github.com/rafgraph/spa-github-pages
+      // This script checks to see if a redirect is present in the query string,
+      // converts it back into the correct url and adds it to the
+      // browser's history using window.history.replaceState(...),
+      // which won't cause the browser to attempt to load the new url.
+      // When the single page app is loaded further down in this file,
+      // the correct url will be waiting in the browser's history for
+      // the single page app to route accordingly.
+      (function(l) {
+        if (l.search[1] === '/' ) {
+          var decoded = l.search.slice(1).split('&').map(function(s) { 
+            return s.replace(/~and~/g, '&')
+          }).join('?');
+          window.history.replaceState(null, null,
+              l.pathname.slice(0, -1) + decoded + l.hash
+          );
+        }
+      }(window.location))
+    </script>
+    <!-- End Single Page Apps for GitHub Pages -->
+    
     <!-- Primary Meta Tags -->
     <title>README Badge Creator - Generate Install Badges for MCP Servers & VS Code Extensions</title>
     <meta name="title" content="README Badge Creator - Generate Install Badges for MCP Servers & VS Code Extensions" />
diff --git a/public/404.html b/public/404.html
@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>README Badge Creator</title>
+    <script>
+      // Single Page Apps for GitHub Pages
+      // MIT License
+      // https://github.com/rafgraph/spa-github-pages
+      // This script takes the current url and converts the path and query
+      // string into just a query string, and then redirects the browser
+      // to the new url with only a query string and hash fragment,
+      // e.g. https://www.foo.tld/one/two?a=b&c=d#qwe, becomes
+      // https://www.foo.tld/?/one/two&a=b~and~c=d#qwe
+      // Note: this 404.html file must be at least 512 bytes for it to work
+      // with Internet Explorer (it is currently > 512 bytes)
+
+      // If you're creating an SPA that will use a custom domain, and there is no
+      // path segment in the domain (e.g. https://example.tld/ instead of
+      // https://example.tld/path-to-spa), then set segmentCount to 0.
+      // If you're creating an SPA that will use a subdirectory path
+      // (e.g. https://example.tld/path-to-spa), then set segmentCount to the
+      // number of path segments in the subdirectory (e.g. 1 for /path-to-spa,
+      // 2 for /path/to/spa, etc.)
+      var segmentCount = 0;
+
+      var l = window.location;
+      l.replace(
+        l.protocol +
+          '//' +
+          l.hostname +
+          (l.port ? ':' + l.port : '') +
+          l.pathname
+            .split('/')
+            .slice(0, 1 + segmentCount)
+            .join('/') +
+          '/?/' +
+          l.pathname
+            .slice(1)
+            .split('/')
+            .slice(segmentCount)
+            .join('/')
+            .replace(/&/g, '~and~') +
+          (l.search ? '&' + l.search.slice(1).replace(/&/g, '~and~') : '') +
+          l.hash
+      );
+    </script>
+  </head>
+  <body></body>
+</html>
diff --git a/src/App.tsx b/src/App.tsx
@@ -1,5 +1,5 @@
 import { useState, useEffect } from 'react'
-import { NavLink, Outlet, Route, BrowserRouter, Routes } from 'react-router-dom'
+import { NavLink, Outlet, Route, BrowserRouter, Routes, useLocation } from 'react-router-dom'
 import './App.css'
 import Home from './pages/Home'
 import MCP from './pages/MCP'
@@ -15,6 +15,7 @@ const navItems = [
 ]
 
 function Layout() {
+  const location = useLocation()
   const [theme, setTheme] = useState<ThemeType>(() => {
     const savedTheme = localStorage.getItem('readme-badge-theme') as ThemeType
     return savedTheme || 'system'
diff --git a/tests/direct-navigation.spec.ts b/tests/direct-navigation.spec.ts
@@ -0,0 +1,97 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Direct URL Navigation', () => {
+  test('should navigate directly to /mcp page', async ({ page }) => {
+    // Navigate directly to the MCP page URL
+    await page.goto('/mcp');
+    
+    // Wait for the page to load
+    await page.waitForLoadState('networkidle');
+    
+    // Verify the URL is correct
+    expect(page.url()).toContain('/mcp');
+    
+    // Verify the page content is loaded (check for MCP specific content)
+    const heading = page.locator('h1, h2').first();
+    await expect(heading).toBeVisible();
+    
+    // Check that the MCP nav link is active
+    const mcpNavLink = page.locator('a.nav-link.active', { hasText: 'MCP Badges' });
+    await expect(mcpNavLink).toBeVisible();
+  });
+
+  test('should navigate directly to /extensions page', async ({ page }) => {
+    // Navigate directly to the Extensions page URL
+    await page.goto('/extensions');
+    
+    // Wait for the page to load
+    await page.waitForLoadState('networkidle');
+    
+    // Verify the URL is correct
+    expect(page.url()).toContain('/extensions');
+    
+    // Verify the page content is loaded
+    const heading = page.locator('h1, h2').first();
+    await expect(heading).toBeVisible();
+    
+    // Check that the Extensions nav link is active
+    const extensionsNavLink = page.locator('a.nav-link.active', { hasText: 'VS Code Extensions' });
+    await expect(extensionsNavLink).toBeVisible();
+  });
+
+  test('should navigate directly to /settings page', async ({ page }) => {
+    // Navigate directly to the Settings page URL
+    await page.goto('/settings');
+    
+    // Wait for the page to load
+    await page.waitForLoadState('networkidle');
+    
+    // Verify the URL is correct
+    expect(page.url()).toContain('/settings');
+    
+    // Verify the page content is loaded
+    const heading = page.locator('h1, h2').first();
+    await expect(heading).toBeVisible();
+    
+    // Check that the Settings nav link is active
+    const settingsNavLink = page.locator('a.nav-link.settings-link.active');
+    await expect(settingsNavLink).toBeVisible();
+  });
+
+  test('should handle deep linking with query parameters', async ({ page }) => {
+    // Navigate to a page with query parameters
+    await page.goto('/mcp?test=value');
+    
+    // Wait for the page to load
+    await page.waitForLoadState('networkidle');
+    
+    // Verify the URL preserves query parameters
+    expect(page.url()).toContain('/mcp');
+    expect(page.url()).toContain('test=value');
+    
+    // Verify the page loaded correctly
+    const heading = page.locator('h1, h2').first();
+    await expect(heading).toBeVisible();
+  });
+
+  test('should navigate from home to subpage and back', async ({ page }) => {
+    // Start at home
+    await page.goto('/');
+    await page.waitForLoadState('networkidle');
+    
+    // Navigate to MCP page
+    await page.click('a.nav-link:has-text("MCP Badges")');
+    await page.waitForLoadState('networkidle');
+    
+    // Verify we're on the MCP page
+    expect(page.url()).toContain('/mcp');
+    
+    // Navigate back to home
+    await page.click('a.nav-link:has-text("Home")');
+    await page.waitForLoadState('networkidle');
+    
+    // Verify we're back at home
+    expect(page.url()).not.toContain('/mcp');
+    expect(page.url()).not.toContain('/extensions');
+  });
+});
