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

cd sut/frontend

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

Build for Deployment

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:

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:

- 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)

<!-- 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)

<!-- 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

# 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

# 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
• Open Graph Protocol
• Sitemap Protocol