lotr-sut/sut/frontend/ENV_URL_SETUP.md

# Environment-Aware URL Configuration

This document explains how analytics and SEO URLs adapt to different deployment environments.

## Overview

The Fellowship Quest List uses environment-aware URLs in critical files:
- **`index.html`**: Meta tags (canonical, og:url, og:image, twitter:image)
- **`sitemap.xml`**: All routes and API endpoints

This ensures that regardless of whether you're deploying to:
- Development: `http://localhost:5173`
- Staging: `https://lotr-staging.testingfantasy.com`
- Production: `https://lotr-prod.testingfantasy.com`

The URLs in these files are always correct.

## Environment Variables

### Primary Variable
`VITE_APP_SITE_URL` - The full site URL without trailing slash
- Example: `https://lotr-prod.testingfantasy.com`
- Example: `https://lotr-staging.testingfantasy.com`
- Example: `http://localhost:5173`

## How It Works

### For `index.html`
URLs are set dynamically at **runtime** using JavaScript:
1. Base URLs in HTML use placeholders: `%VITE_APP_SITE_URL%`
2. At page load, JavaScript reads `window.location.origin`
3. Dynamic updates to `<meta>` and `<link>` tags ensure they reflect the actual deployment URL
4. This works for all deployment scenarios without rebuilding

### For `sitemap.xml`
URLs are substituted **at build time**:
1. Source file uses placeholders: `%VITE_APP_SITE_URL%`
2. Build script replaces placeholders with actual environment URL
3. Final `sitemap.xml` has concrete URLs for search engines

## Setup Instructions

### Development

```bash
cd sut/frontend

# Run dev server (uses http://localhost:5173 automatically)
npm run dev
```

### Build for Deployment

```bash
cd sut/frontend

# Set the environment-specific URL
export VITE_APP_SITE_URL="https://lotr-prod.testingfantasy.com"

# Build the application
npm run build

# Run setup script to update XML files with correct URLs
node scripts/setup-env-urls.js
```

### Docker Deployment

In your Dockerfile:

```dockerfile
ARG SITE_URL=https://lotr-prod.testingfantasy.com

# ... build steps ...

# Setup environment-aware URLs
ENV VITE_APP_SITE_URL=${SITE_URL}
RUN cd sut/frontend && node scripts/setup-env-urls.js
```

### CI/CD Pipeline

Example GitHub Actions:

```yaml
- name: Setup environment-aware URLs
  env:
    VITE_APP_SITE_URL: ${{ secrets.SITE_URL }}
  run: |
    cd sut/frontend
    node scripts/setup-env-urls.js    
```

## File Examples

### index.html (Runtime Dynamic)
```html
<!-- Placeholder URLs in source -->
<meta property="og:url" content="%VITE_APP_SITE_URL%/" id="og-url" />
<link rel="canonical" href="%VITE_APP_SITE_URL%/" id="canonical" />

<!-- JavaScript updates them at runtime -->
<script>
  const origin = window.location.origin;
  document.getElementById('og-url').content = origin + '/';
  document.getElementById('canonical').href = origin + '/';
</script>
```

### sitemap.xml (Build-time Substitution)
```xml
<!-- Before build (source) -->
<loc>%VITE_APP_SITE_URL%/login</loc>

<!-- After build with VITE_APP_SITE_URL=https://lotr-prod.testingfantasy.com -->
<loc>https://lotr-prod.testingfantasy.com/login</loc>
```

## Testing URLs

### Verify index.html Dynamic URLs
```bash
# Open browser DevTools and check the Console when page loads
# Meta tags should update to match your current URL

# Example: If accessed at https://mysite.com
# - og:url should be "https://mysite.com/"
# - canonical should be "https://mysite.com/"
```

### Verify sitemap.xml
```bash
# Download sitemap.xml and check the URLs
curl https://lotr-prod.testingfantasy.com/sitemap.xml | head -20

# All <loc> entries should use the correct domain
```

## Benefits

✅ **Single codebase** - Deploy to any environment without code changes
✅ **Search engines** - Correct canonical URLs prevent duplicate content penalties
✅ **Social media** - Correct og: tags for rich previews on any domain
✅ **Analytics** - Proper tracking in GA regardless of deployment URL
✅ **No rebuilds** - index.html works without rebuild for different domains

## Troubleshooting

### URLs not updating in sitemap.xml
- Ensure `VITE_APP_SITE_URL` is set before building
- Run `node scripts/setup-env-urls.js` after build
- Check that `public/sitemap.xml` contains your domain, not `%VITE_APP_SITE_URL%`

### Meta tags not updating in index.html
- Open browser DevTools (F12)
- Go to Elements/Inspector and check `<meta id="og-url">` etc.
- Verify JavaScript ran: check Console for any errors
- URL should match `window.location.origin`

### Staging environment has wrong URLs
- Verify `VITE_APP_SITE_URL` environment variable is set
- Run setup script before deploying
- Check that sitemap.xml contains staging URL, not production

## References

- [Google Canonical URLs](https://developers.google.com/search/docs/beginner/seo-starter-guide#declare-the-canonical-version-of-a-page)
- [Open Graph Protocol](https://ogp.me/)
- [Sitemap Protocol](https://www.sitemaps.org/protocol.html)