Improve Routes

Problem

When deploying docs-angular to a subdirectory (e.g., gograb.space/docs/), Angular's default routing strategy causes 404 errors on sub-routes like /docs/select-project.

Root Cause

Server-side routing vs. Client-side routing mismatch:

• User navigates to gograb.space/docs/select-project
• Web server looks for physical file at /docs/select-project
• File doesn't exist → Server returns 404 Not Found
• Angular never gets a chance to handle the routing

This is a classic SPA (Single Page Application) deployment issue.

Current Solution (Temporary)

Hash-based routing implemented in apps/docs-angular/src/app/app.config.ts:

import { withHashLocation } from '@angular/router';

provideRouter([], withPreloading(PreloadAllModules), withHashLocation())

How it works:

• URLs use hash fragment: gograb.space/docs/#/select-project
• Server only sees: gograb.space/docs/
• Everything after # is client-side only
• No server configuration needed ✅

Trade-offs:

• ✅ Works immediately without server changes
• ✅ No 404 errors
• ✅ Bookmarkable URLs
• ❌ URLs contain # (less clean)
• ❌ Hash can't be used for page anchors

Proper Solution (Future Implementation)

Remove hash routing and configure server rewrites to serve index.html for all routes under /docs/.

Required Server Configuration

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /docs/
  
  # If the requested resource doesn't exist, serve index.html
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule ^(.*)$ /docs/index.html [L]
</IfModule>

location /docs/ {
  alias /var/www/html/docs/;
  try_files $uri $uri/ /docs/index.html;
}

app.use('/docs', express.static('dist/docs-angular/browser'));
app.get('/docs/*', (req, res) => {
  res.sendFile(path.join(__dirname, 'dist/docs-angular/browser/index.html'));
});

Implementation Steps

1. Remove hash routing from app.config.ts:

   // Remove withHashLocation()
   provideRouter([], withPreloading(PreloadAllModules))
   

2. Configure web server with appropriate rewrite rules (see above)

3. Rebuild application:

   nx build docs-angular --configuration=production
   

4. Deploy and test all routes

Benefits of Clean URLs

• ✅ Professional appearance (/docs/page vs /docs/#/page)
• ✅ Better SEO (search engines prefer clean URLs)
• ✅ Can use hash fragments for page anchors (#section)
• ✅ Standard Angular routing behavior

Related Files

• apps/docs-angular/src/app/app.config.ts - Router configuration
• apps/docs-angular/project.json - Build configuration (baseHref: "/docs/")

References

• Angular Deployment Guide
• Hash vs Path Location Strategy