Deployment

Complete guide to deploying the portfolio with multi-version support to GitHub Pages.

🚀 Multi-Version Deployment System

This portfolio uses a custom deployment system that supports hosting multiple versions simultaneously:

V2 (Current) at root: https://abishek-maharajan.online
V1 (Legacy) at /v1: https://abishek-maharajan.online/v1

Quick Deploy

Windows (PowerShell):

.\scripts\deploy-composite.ps1

Linux/Mac (Bash):

chmod +x scripts/deploy-composite.sh
./scripts/deploy-composite.sh

What It Does

The deployment script automatically:

Builds V1 with basePath: '/v1' configuration
Builds V2 at root with default paths
Merges both builds into a single deployment artifact
Creates CNAME file for custom domain
Deploys to gh-pages branch with force push
Returns you to your original branch

Duration: ~8-10 minutes total

Pre-Deployment Verification

Before deploying, run the local verification script:

.\scripts\verify-local.ps1

This checks:

✅ Dev server is running
✅ All docs pages load correctly
✅ Test suite passes (45/45 tests)
✅ TypeScript compiles without errors
✅ Production build succeeds
✅ Git status is clean

GitHub Pages Setup

1. Enable GitHub Pages

Go to repository Settings → Pages
Set source to gh-pages branch
Set folder to / (root)
Click Save

2. Configure Custom Domain

The deployment script automatically creates a CNAME file with:

abishek-maharajan.online

DNS Configuration:

Type: A
Name: @
Value: 185.199.108.153
       185.199.109.153
       185.199.110.153
       185.199.111.153

Type: CNAME
Name: www
Value: tentaciopro.github.io

3. Enable HTTPS

GitHub Pages automatically provisions SSL certificates for custom domains.

Deployment Architecture

GitHub Repository (feat/factory-floor)
           ↓
    Deployment Script
           ↓
    ┌──────┴──────┐
    ↓             ↓
V2 Build      V1 Build
(root)        (basePath: /v1)
    ↓             ↓
    └──────┬──────┘
           ↓
    Merged Artifact
    ├── index.html (V2)
    ├── _next/ (V2 assets)
    ├── v1/
    │   ├── index.html (V1)
    │   └── _next/ (V1 assets)
    ├── CNAME
    └── .nojekyll
           ↓
    gh-pages Branch
           ↓
    GitHub Pages
           ↓
  abishek-maharajan.online

Build Configuration

V2 (Current) - Root Deployment

File: apps/web/next.config.mjs

const nextConfig = {
  output: "export",
  basePath: "",                  // Root directory
  assetPrefix: "",               // Default assets path
  trailingSlash: true,
  images: { unoptimized: true },
}

V1 (Legacy) - Subdirectory Deployment

The deployment script automatically modifies V1's config:

const nextConfig = {
  output: "export",
  basePath: "/v1",               // Subdirectory
  assetPrefix: "/v1",            // Prefixed assets
  trailingSlash: true,
  images: { unoptimized: true },
}

Build Output

V2 Directory: apps/web/out
V1 Directory: out (from release/may-2025-v1 branch)

Merged Output:

245 files total
~51 MB deployed
Static HTML, CSS, JS
Optimized assets

Deployment Scripts

Main Deployment Script

Location: scripts/deploy-composite.ps1 (Windows) / scripts/deploy-composite.sh (Linux/Mac)

Features:

Automatic branch switching
Dual build process (V1 + V2)
Config modification for V1
Artifact merging
Git worktree deployment
Force push handling
Automatic cleanup

Verification Script

Location: scripts/verify-deployment.ps1

Tests both deployed versions:

.\scripts\verify-deployment.ps1

Checks:

V2 accessibility at root
V1 accessibility at /v1
HTTP status codes
Response times

Local Verification

Location: scripts/verify-local.ps1

Pre-deployment checks:

.\scripts\verify-local.ps1

Troubleshooting

Common Issues

Issue: Sidebar not showing in docs

Solution: Ensure head in theme.config.jsx is a function:

head: () => (<>...</>)  // ✅ Correct
head: (<>...</>)        // ❌ Wrong

Issue: CSP blocking Google Fonts

Solution: Update CSP in next.config.mjs:

"style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
"font-src 'self' data: https://fonts.gstatic.com",

Issue: Assets 404 on GitHub Pages

Solution:

Check basePath configuration
Verify CNAME file exists
Ensure custom domain is configured in GitHub Settings

Issue: Deployment fails with "rejected" error

Solution: The script uses --force push. If it still fails:

git checkout gh-pages
git pull origin gh-pages
git checkout feat/factory-floor
.\scripts\deploy-composite.ps1

Deployment Checklist

Pre-Deployment

Post-Deployment

Performance Optimization

Build Optimizations

Static Export (pure HTML/CSS/JS)
Code Splitting (automatic)
Tree Shaking (remove unused code)
Minification (compress assets)

Asset Optimization

Images: Use WebP format
Videos: Compress with FFmpeg
Fonts: Subset and preload
Icons: Use SVG or icon fonts

Monitoring & Analytics

Web Vitals

Track performance metrics:

LCP (Largest Contentful Paint)
INP (Interaction to Next Paint)
CLS (Cumulative Layout Shift)
FCP (First Contentful Paint)
TTFB (Time to First Byte)

Implementation: src/lib/webVitals.ts

Troubleshooting

Build Errors

Error: Image Optimization using Next.js' default loader is not compatible with export

Solution: Set images: { unoptimized: true } in next.config.mjs

Error: Module not found: Can't resolve 'fs'

Solution: Add webpack fallback in next.config.mjs

Deployment Issues

Issue: Assets not loading on GitHub Pages

Solution:

Check basePath and assetPrefix
Use getAssetPath() utility
Ensure trailingSlash: true

Security Considerations

Security Headers

Implemented in next.config.mjs:

Strict-Transport-Security (HSTS)
X-Frame-Options
X-Content-Type-Options
Content-Security-Policy

Best Practices

Always use HTTPS in production
Keep dependencies updated
Never commit secrets
Configure CSP properly
Restrict cross-origin requests

Resources

Components Agent Development Log