Production Deployment

Overview

After building and testing your application, you’re ready to deploy to production. This guide covers deploying the SAAC Frontend to various hosting platforms.

Build Requirements

All deployment platforms need the following information:

Build Command

npm run build

Output Directory

dist

The build command (tsc -b && vite build) performs TypeScript validation and creates an optimized production bundle in the dist/ directory.

Environment Variables

For production deployments, configure environment variables with the VITE_ prefix:

.env.production

VITE_API_URL=https://api.yourdomain.com
VITE_APP_NAME=SAAC Frontend
VITE_ENABLE_ANALYTICS=true

Never commit .env files containing secrets to version control. Use your hosting platform’s environment variable management instead.

Deployment Platforms

Vercel (Recommended)

Vercel provides zero-configuration deployment for Vite applications with automatic builds and global CDN.

Install Vercel CLI

npm install -g vercel

Deploy from Command Line

vercel

Follow the prompts to link your project and deploy.

Configure Project (if needed)

Vercel auto-detects Vite projects, but you can create a vercel.json for custom configuration:

vercel.json

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "devCommand": "npm run dev",
  "installCommand": "npm install"
}

Set Environment Variables

In the Vercel dashboard or via CLI:

vercel env add VITE_API_URL production

Vercel Features:

Automatic deployments from Git
Preview deployments for pull requests
Global CDN with edge caching
Custom domains and SSL
Serverless functions (if needed)

For GitHub/GitLab integration, connect your repository in the Vercel dashboard for automatic deployments on every push.

Netlify

Netlify offers similar features to Vercel with excellent static site hosting capabilities.

Install Netlify CLI

npm install -g netlify-cli

Initialize and Deploy

netlify deploy --prod

Or connect via Git in the Netlify dashboard.

Configure Build Settings

Create a netlify.toml file:

netlify.toml

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

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

The redirect rule ensures client-side routing works correctly.

Set Environment Variables

In Netlify dashboard: Site settings → Build & deploy → EnvironmentOr via CLI:

netlify env:set VITE_API_URL "https://api.yourdomain.com"

Netlify Features:

Deploy previews for branches
Form handling
Serverless functions
Split testing
Analytics

GitHub Pages

Deploy static sites directly from your GitHub repository.

Install gh-pages Package

npm install --save-dev gh-pages

Update vite.config.ts

Set the base path to your repository name:

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  base: '/your-repo-name/',
  plugins: [react(), tailwindcss()],
})

Add Deploy Script

Add to package.json:

package.json

{
  "scripts": {
    "build": "tsc -b && vite build",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  }
}

Deploy

npm run deploy

This builds and pushes to the gh-pages branch.

Enable GitHub Pages

In your repository settings:

Go to Pages
Select gh-pages branch
Save

Your site will be available at https://username.github.io/repo-name/

GitHub Pages doesn’t support server-side routing. Client-side routing works with hash-based routing or the 404.html trick.

Traditional Web Hosting

For shared hosting, VPS, or dedicated servers:

Build Locally

npm run build

Upload dist/ Contents

Upload the contents of the dist/ directory to your web server’s public directory (e.g., public_html, www, or htdocs).Use FTP, SFTP, or your hosting provider’s file manager.

Configure Web Server

For client-side routing, configure your server to serve index.html for all routes.Apache (.htaccess):

.htaccess

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

Nginx:

nginx.conf

server {
  listen 80;
  server_name yourdomain.com;
  root /var/www/html;
  index index.html;
  
  location / {
    try_files $uri $uri/ /index.html;
  }
}

Static File Serving

Your production deployment serves static files. Key considerations:

File Structure

The dist/ directory contains:

index.html - Entry point
assets/ - JS, CSS, and other assets with content hashes
Static files from public/ directory

Content Types

Ensure your server sends correct MIME types:

.js → application/javascript
.css → text/css
.html → text/html
.svg → image/svg+xml

Most hosting platforms handle this automatically.

CDN and Caching

Cache Headers

Optimal caching strategy for Vite builds:

index.html:
  Cache-Control: no-cache, must-revalidate

assets/*:
  Cache-Control: public, max-age=31536000, immutable

Reasoning:

index.html should not be cached (or short cache) to get latest asset references
Assets have content hashes, so they can be cached forever
When code changes, new hashes are generated, bypassing cache

CDN Configuration

For platforms with CDN (Vercel, Netlify, Cloudflare):

Edge caching: Static assets served from nearest edge location
Automatic compression: Gzip/Brotli compression
HTTP/2: Multiplexed connections
SSL/TLS: Automatic HTTPS

Vite’s content-hashed filenames enable aggressive caching. When you deploy new versions, new hash values ensure users get fresh code.

Deployment Checklist

Before deploying to production:

Test Production Build

npm run build
npm run preview

Verify everything works locally.

Set Environment Variables

Configure production environment variables on your hosting platform.

Configure Domain

Set up your custom domain and SSL certificate.

Enable Compression

Ensure Gzip/Brotli compression is enabled.

Configure Routing

Set up fallback to index.html for client-side routing.

Set Cache Headers

Configure appropriate cache headers for HTML and assets.

Monitor Performance

Use tools like Lighthouse to verify performance.

Continuous Deployment

Automate deployments with Git integration:

Vercel/Netlify GitHub Integration

Connect your GitHub repository
Configure production branch (usually main)
Every push to main triggers automatic deployment
Pull requests get preview deployments

GitHub Actions

For custom deployment workflows:

.github/workflows/deploy.yml

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Build
        run: npm run build
        env:
          VITE_API_URL: ${{ secrets.VITE_API_URL }}
          
      - name: Deploy
        # Add your deployment step here
        run: echo "Deploy dist/ to your hosting"

Troubleshooting

Blank Page After Deployment

Cause: Incorrect base path or routing configuration. Solution:

Check base in vite.config.ts
Verify server routing fallback to index.html
Check browser console for errors

Assets Not Loading

Cause: Wrong base path or CORS issues. Solution:

Set correct base in Vite config
Verify assets are in dist/assets/
Check network tab for 404 errors

Environment Variables Not Working

Cause: Missing VITE_ prefix or not set on platform. Solution:

Prefix all client-side variables with VITE_
Set variables in hosting platform dashboard
Rebuild after changing environment variables

Build Fails on Platform

Cause: Node version mismatch or missing dependencies. Solution:

Specify Node version (e.g., in .nvmrc or package.json)
Ensure all dependencies are in package.json
Check build logs for specific errors

Next Steps

Monitor Performance

Use Lighthouse, Web Vitals, and analytics to monitor your production app.

Set Up CI/CD

Automate testing and deployment with GitHub Actions or similar tools.

Configure Analytics

Add analytics to track user behavior and application performance.

Error Tracking

Integrate error tracking (Sentry, LogRocket) to catch production issues.

Get Started

Development

Configuration

Deployment

Overview

Build Requirements

Build Command

Output Directory

Environment Variables

Deployment Platforms

Vercel (Recommended)

Netlify

GitHub Pages

Traditional Web Hosting

Static File Serving

File Structure

Content Types

CDN and Caching

Cache Headers

CDN Configuration

Deployment Checklist

Continuous Deployment

Vercel/Netlify GitHub Integration

GitHub Actions

Troubleshooting

Blank Page After Deployment

Assets Not Loading

Environment Variables Not Working

Build Fails on Platform

Next Steps

Monitor Performance

Set Up CI/CD

Configure Analytics

Error Tracking

Build docs developers (and LLMs) love

Get Started

Development

Configuration

Deployment

​Overview

​Build Requirements

Build Command

Output Directory

​Environment Variables

​Deployment Platforms

​Vercel (Recommended)

​Netlify

​GitHub Pages

​Traditional Web Hosting

​Static File Serving

​File Structure

​Content Types

​CDN and Caching

​Cache Headers

​CDN Configuration

​Deployment Checklist

​Continuous Deployment

​Vercel/Netlify GitHub Integration

​GitHub Actions

​Troubleshooting

​Blank Page After Deployment

​Assets Not Loading

​Environment Variables Not Working

​Build Fails on Platform

​Next Steps

Monitor Performance

Set Up CI/CD

Configure Analytics

Error Tracking

Build docs developers (and LLMs) love

Overview

Build Requirements

Environment Variables

Deployment Platforms

Vercel (Recommended)

Netlify

GitHub Pages

Traditional Web Hosting

Static File Serving

File Structure

Content Types

CDN and Caching

Cache Headers

CDN Configuration

Deployment Checklist

Continuous Deployment

Vercel/Netlify GitHub Integration

GitHub Actions

Troubleshooting

Blank Page After Deployment

Assets Not Loading

Environment Variables Not Working

Build Fails on Platform

Next Steps