Skip to content

DEPLOYMENT_GUIDE.md

Latest commit

 

History

History
562 lines (435 loc) · 10.6 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

562 lines (435 loc) · 10.6 KB

🚀 Deployment Configuration Guide

For: Webpage Quality Analyzer (WQA)
Date: October 11, 2025
Platforms: Vercel, Netlify, GitHub Pages

🎯 Platform Recommendation: Vercel (Best for React + Vite + WASM)

Why Vercel?

  • ✅ Zero-config deployment for Vite projects
  • ✅ Automatic HTTPS
  • ✅ Edge network with fast WASM delivery
  • ✅ Easy environment variable management
  • ✅ Built-in analytics
  • ✅ Supports custom headers (required for WASM)

Option 1: Vercel Deployment (Recommended) ⭐

Step 1: Install Vercel CLI

npm i -g vercel

Step 2: Create vercel.json

{
  "version": 2,
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite",
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin"
        },
        {
          "key": "Cross-Origin-Embedder-Policy",
          "value": "require-corp"
        },
        {
          "key": "Cross-Origin-Resource-Policy",
          "value": "cross-origin"
        },
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    },
    {
      "source": "/assets/(.*).wasm",
      "headers": [
        {
          "key": "Content-Type",
          "value": "application/wasm"
        },
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ],
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ],
  "env": {
    "VITE_CORS_PROXY": "https://api.allorigins.win/raw?url="
  }
}

Step 3: Deploy

# Login to Vercel
vercel login

# Deploy to preview
vercel

# Deploy to production
vercel --prod

Step 4: Environment Variables (Vercel Dashboard)

Go to: Project Settings → Environment Variables

Add:

  • VITE_CORS_PROXY = https://api.allorigins.win/raw?url=
  • (Optional) NODE_ENV = production

Step 5: Custom Domain (Optional)

  1. Go to Project Settings → Domains
  2. Add your custom domain
  3. Update DNS records as instructed

Option 2: Netlify Deployment 🌐

Step 1: Install Netlify CLI

npm i -g netlify-cli

Step 2: Create netlify.toml

[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"

[[headers]]
  for = "/*"
  [headers.values]
    Cross-Origin-Opener-Policy = "same-origin"
    Cross-Origin-Embedder-Policy = "require-corp"
    Cross-Origin-Resource-Policy = "cross-origin"
    X-Content-Type-Options = "nosniff"
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"

[[headers]]
  for = "/*.wasm"
  [headers.values]
    Content-Type = "application/wasm"
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[dev]
  command = "npm run dev"
  port = 5173
  targetPort = 5173

Step 3: Create _headers file (backup)

/*
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp
  Cross-Origin-Resource-Policy: cross-origin
  X-Content-Type-Options: nosniff
  X-Frame-Options: DENY

/*.wasm
  Content-Type: application/wasm
  Cache-Control: public, max-age=31536000, immutable

Step 4: Deploy

# Login to Netlify
netlify login

# Initialize project
netlify init

# Deploy to preview
netlify deploy

# Deploy to production
netlify deploy --prod

Step 5: Environment Variables (Netlify Dashboard)

Go to: Site Settings → Environment Variables

Add:

  • VITE_CORS_PROXY = https://api.allorigins.win/raw?url=

Option 3: GitHub Pages (Advanced) 📚

⚠️ Warning: GitHub Pages doesn't support custom headers, which WASM requires. You'll need workarounds.

Step 1: Install gh-pages

npm install --save-dev gh-pages

Step 2: Update package.json

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  },
  "homepage": "https://yourusername.github.io/WQA"
}

Step 3: Update vite.config.js

export default defineConfig({
  base: '/WQA/', // Your repo name
  // ... rest of config
});

Step 4: Deploy

npm run deploy

⚠️ WASM Headers Workaround

Since GitHub Pages doesn't support custom headers, you need to:

  1. Use Service Worker (Complex)
  2. Use meta tags (Limited): 
    <!-- In index.html -->
<meta http-equiv="Cross-Origin-Opener-Policy" content="same-origin">
<meta http-equiv="Cross-Origin-Embedder-Policy" content="require-corp">

Recommendation: Use Vercel or Netlify instead of GitHub Pages.

🔧 Pre-Deployment Configuration

1. Update package.json

{
  "name": "webpage-quality-analyzer",
  "version": "1.0.0",
  "description": "React + WASM webpage quality analyzer with Halloween theme",
  "author": "Your Name",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/WQA"
  },
  "keywords": [
    "webpage-analysis",
    "quality-analyzer",
    "wasm",
    "react",
    "vite"
  ]
}

2. Create .env.production

VITE_CORS_PROXY=https://api.allorigins.win/raw?url=
NODE_ENV=production

3. Create .env.example

# CORS Proxy URL (required for URL mode)
VITE_CORS_PROXY=https://api.allorigins.win/raw?url=

# Node environment
NODE_ENV=development

4. Update .gitignore

# Environment variables
.env
.env.local
.env.production

# Build output
dist/
dist-ssr/

# Logs
*.log

# Dependencies
node_modules/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Vercel
.vercel

# Netlify
.netlify

🧪 Testing Production Build Locally

Step 1: Build

npm run build

Step 2: Preview

npm run preview

Step 3: Test

Open: http://localhost:4173

Test Checklist:

  • WASM loads successfully
  • All 8 profiles work
  • URL mode works (with CORS proxy)
  • HTML paste mode works
  • Configuration panel works
  • Export/import works
  • Results display correctly
  • Mobile responsive
  • No console errors
  • Halloween theme renders correctly

📊 Performance Optimization (Optional)

1. Enable Gzip/Brotli Compression

Vercel: Automatic ✅
Netlify: Automatic ✅
Manual: Add to your server config

2. Add Service Worker for Caching

// public/sw.js
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open('wqa-v1').then((cache) => {
      return cache.addAll([
        '/',
        '/index.html',
        '/assets/index.js',
        '/assets/index.css',
      ]);
    })
  );
});

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((response) => {
      return response || fetch(event.request);
    })
  );
});

Register in main.jsx:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}

3. Preload WASM Module

<!-- In index.html -->
<link rel="preload" href="/assets/webpage_quality_analyzer_bg.wasm" as="fetch" crossorigin="anonymous">

🔍 Monitoring & Analytics (Post-Deployment)

1. Vercel Analytics (Free)

Enable in Vercel dashboard:

  • Project Settings → Analytics
  • Add @vercel/analytics package:
npm install @vercel/analytics
// In main.jsx
import { Analytics } from '@vercel/analytics/react';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
    <Analytics />
  </React.StrictMode>
);

2. Error Tracking with Sentry (Recommended)

npm install @sentry/react
// In main.jsx
import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: 'your-sentry-dsn',
  environment: import.meta.env.MODE,
  tracesSampleRate: 0.1,
});

ReactDOM.createRoot(document.getElementById('root')).render(
  <Sentry.ErrorBoundary fallback={<ErrorFallback />}>
    <App />
  </Sentry.ErrorBoundary>
);

3. Google Analytics (Optional)

npm install react-ga4
// In main.jsx
import ReactGA from 'react-ga4';

if (import.meta.env.PROD) {
  ReactGA.initialize('G-XXXXXXXXXX');
}

🛡️ Security Checklist

  • HTTPS enabled (automatic on Vercel/Netlify)
  • CORS headers configured
  • Content-Security-Policy header (optional)
  • X-Frame-Options: DENY
  • X-Content-Type-Options: nosniff
  • No API keys in client-side code
  • Environment variables properly configured
  • Dependencies up to date (npm audit)

🚦 Post-Deployment Checklist

Immediate (Within 1 hour):

  • Test all features on production URL
  • Test on mobile devices (iPhone, Android)
  • Test on different browsers (Chrome, Firefox, Safari, Edge)
  • Verify WASM loads correctly
  • Check CORS proxy works
  • Verify all 8 profiles load
  • Test error scenarios (invalid URL, timeout, etc.)

Within 24 hours:

  • Monitor error logs
  • Check analytics for user behavior
  • Verify performance metrics (Lighthouse)
  • Test with real user feedback
  • Monitor CORS proxy reliability

Within 1 week:

  • Review error patterns
  • Optimize based on usage data
  • Address user-reported issues
  • Consider A/B testing variants

📞 Troubleshooting

WASM Not Loading

  1. Check browser console for errors
  2. Verify CORS headers are set correctly
  3. Check WASM file is in /assets/ folder
  4. Try clearing browser cache

CORS Proxy Failing

  1. Verify VITE_CORS_PROXY environment variable
  2. Test proxy URL directly in browser
  3. Consider backup proxy: https://corsproxy.io/?
  4. Recommend HTML paste mode to users

Build Failing

  1. Check Node version (need 18+)
  2. Clear node_modules and reinstall: rm -rf node_modules package-lock.json && npm install
  3. Check for TypeScript errors: npm run lint
  4. Verify all dependencies installed

Deployment 404 Errors

  1. Check vercel.json or netlify.toml redirects
  2. Verify build output directory is correct (dist)
  3. Check base path in vite.config.js

🎉 Success Metrics

Your deployment is successful when:

  • ✅ WASM loads in <3 seconds
  • ✅ Analysis completes in <500ms
  • ✅ No console errors
  • ✅ Mobile responsive (tested on iOS/Android)
  • ✅ All 8 profiles work
  • ✅ Error messages are user-friendly
  • ✅ Lighthouse score >90

Last Updated: October 11, 2025
Platform: Vercel (recommended), Netlify (alternative)
Status: Ready to deploy