lucas/namecard

Fork 0

Lucas Tan 27c78e2ac4 initial app

2025-08-19 11:49:57 +08:00

3.9 KiB

Raw Blame History

Deployment Guide

🚀 Deploy to a VPS with Nginx (Reverse Proxy)

This project exports fully static assets in out/. You can serve them directly with Nginx.

1) Build static files

npm run build

By default, the app is built for the root path /. If you want to serve it under a subpath (e.g. /namecard), build with:

BASE_PATH=/namecard NEXT_PUBLIC_BASE_URL=https://example.com/namecard npm run build

2) Upload to server

scp -r out/ user@server:/var/www/namecard

3) Nginx config (root path)

server {
    listen 80;
    server_name example.com; # your domain

    root /var/www/namecard;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

4) Nginx config (subpath, e.g. /namecard)

Build with BASE_PATH=/namecard and then:

server {
    listen 80;
    server_name example.com;

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

5) Reload Nginx

sudo nginx -t && sudo systemctl reload nginx

🌐 Custom Domain Setup

Configure DNS:
- Add A record pointing to your VPS IP address
- Or CNAME if using a subdomain (e.g., card.rooftop.my)
SSL Certificate:
- Use Let's Encrypt: sudo certbot --nginx
- Auto-renewal for free SSL certificates

📱 PWA Configuration (Optional)

To enable "Add to Home Screen" functionality:

Create manifest.json:

{
  "name": "Rooftop Energy Namecard",
  "short_name": "Rooftop",
  "description": "Digital namecard for Rooftop Energy staff",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#0a0a0a",
  "theme_color": "#fcd913",
  "icons": [
    {
      "src": "/logo.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ]
}

Add to layout.tsx:

<head>
  <link rel="manifest" href="/manifest.json" />
</head>

🔧 Environment Variables

Set at build time (locally or in CI):

# Base URL used for Open Graph/Twitter image URLs and absolute links
NEXT_PUBLIC_BASE_URL=https://example.com

# Optional: if serving under a subpath, set both
BASE_PATH=/namecard
NEXT_PUBLIC_BASE_URL=https://example.com/namecard

📊 Performance Monitoring

Web Analytics:
- Use Google Analytics or similar service
- Monitor Core Web Vitals with PageSpeed Insights
Server Monitoring:
- Monitor server resources (CPU, memory, disk)
- Set up alerts for high resource usage

🚨 Troubleshooting

Build Errors

Node version: Ensure Node.js 18+ is used
Dependencies: Run npm install locally first
TypeScript errors: Run npm run type-check locally

Runtime Issues

Logo not loading: Check public/logo.png exists
Styling issues: Verify Tailwind CSS is building correctly
Query params not working: Check URL encoding

Performance Issues

Large bundle: Check for unused dependencies
Slow loading: Optimize images and enable compression
SEO issues: Verify meta tags and Open Graph

📈 Post-Deployment Checklist

Logo displays correctly
All CTAs work (Call, Email, WhatsApp, LinkedIn)
vCard download functions
Copy details works
Mobile responsive design
URL query overrides work
Performance scores meet targets
Analytics tracking (if enabled)
Custom domain configured (if applicable)

🔄 Updates & Maintenance

Regular Updates

Dependencies: Run npm audit and update packages
Content: Edit src/config/staff.ts for staff changes
Logo: Replace public/logo.png when needed

Deployment Updates

Build locally: npm run build
Sync out/ to your server: rsync -az out/ user@server:/var/www/namecard
Reload Nginx: sudo systemctl reload nginx

Need help? Check the main README.md or contact the development team.

3.9 KiB Raw Blame History