Frontend Deployment - Athena ERP

Overview

The Athena ERP frontend is a React application built with Vite. This guide covers deploying to various static hosting platforms.

Prerequisites

Node.js 18 or higher
Backend API deployed and accessible
Environment variables configured

Technology Stack

Framework: React 19
Build Tool: Vite 6.2
Routing: React Router v7
State Management: Zustand 5
Data Fetching: TanStack Query (React Query) v5
UI Framework: Tailwind CSS v4
Forms: React Hook Form + Zod
HTTP Client: Axios
Authentication: Supabase JS Client (optional)

Directory Structure

athena-front/
├── src/
│   ├── components/       # Reusable components
│   ├── pages/           # Page components
│   ├── hooks/           # Custom React hooks
│   ├── services/        # API services
│   ├── store/           # Zustand stores
│   ├── utils/           # Utilities
│   ├── App.tsx          # Main app component
│   └── main.tsx         # Entry point
├── public/              # Static assets
├── .env.example         # Environment template
├── package.json         # Dependencies
├── vite.config.ts       # Vite configuration
├── tailwind.config.ts   # Tailwind configuration
└── tsconfig.json        # TypeScript config

Environment Configuration

Create a .env file in the athena-front directory:

# Backend API URL (required)
VITE_API_URL=https://your-backend-api.railway.app

# Supabase (optional)
VITE_SUPABASE_URL=https://xxxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGc...

All VITE_ prefixed variables are embedded in the client bundle and visible to users. Never put secrets here!

Deployment to Vercel

Vercel is the recommended platform for React/Vite applications.

Step 1: Install Vercel CLI

npm install -g vercel

vercel login

Step 3: Deploy from Local

cd athena-front
vercel

Follow the prompts:

Set up and deploy? Yes
Which scope? Your account/organization
Link to existing project? No
Project name? athena-frontend
Directory? ./
Override settings? No

Step 4: Configure Environment Variables

In Vercel dashboard → Settings → Environment Variables, add:

VITE_API_URL = https://your-backend-api.railway.app
VITE_SUPABASE_URL = https://xxxx.supabase.co
VITE_SUPABASE_ANON_KEY = eyJhbGc...

Select Production, Preview, and Development environments.

Step 5: Redeploy

vercel --prod

Step 6: Custom Domain (Optional)

In Vercel dashboard → Settings → Domains:

Add your custom domain (e.g., app.yourdomain.com)
Configure DNS records as instructed
SSL is automatic

Deployment to Netlify

Netlify is another excellent option.

Step 1: Install Netlify CLI

npm install -g netlify-cli

netlify login

Step 3: Initialize Project

cd athena-front
netlify init

Configure:

Build command: npm run build
Publish directory: dist

Step 4: Configure Environment Variables

In Netlify dashboard → Site settings → Environment variables, add:

VITE_API_URL = https://your-backend-api.railway.app
VITE_SUPABASE_URL = https://xxxx.supabase.co
VITE_SUPABASE_ANON_KEY = eyJhbGc...

Step 5: Deploy

netlify deploy --prod

Step 6: Configure Redirects

Create public/_redirects for React Router:

/*    /index.html   200

Or create netlify.toml:

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

Deployment to Cloudflare Pages

Cloudflare Pages offers excellent performance with their global CDN.

Step 1: Connect Repository

Go to pages.cloudflare.com
Click Create a project
Connect your GitHub repository
Select the repository

Step 2: Configure Build

Framework preset: Vite
Build command: npm run build
Build output directory: dist
Root directory: athena-front

Step 3: Add Environment Variables

In Cloudflare Pages → Settings → Environment variables:

VITE_API_URL = https://your-backend-api.railway.app
VITE_SUPABASE_URL = https://xxxx.supabase.co
VITE_SUPABASE_ANON_KEY = eyJhbGc...

Step 4: Deploy

Cloudflare will automatically deploy on every push to main.

Step 5: Configure SPA Routing

Create public/_redirects:

/*    /index.html   200

Manual Build & Deploy

For custom hosting or CDN.

Step 1: Build Locally

cd athena-front

# Install dependencies
npm install

# Build for production
npm run build

This creates a dist/ directory with optimized static files.

Step 2: Test Build Locally

npm run preview

Open http://localhost:4173 to test the production build.

Step 3: Deploy to Static Hosting

Upload the dist/ directory to:

AWS S3 + CloudFront
Google Cloud Storage + CDN
Azure Static Web Apps
DigitalOcean Spaces
Any static file hosting service

Example: AWS S3 + CloudFront

# Install AWS CLI
aws configure

# Sync to S3
aws s3 sync dist/ s3://your-bucket-name --delete

# Invalidate CloudFront cache
aws cloudfront create-invalidation --distribution-id YOUR_DIST_ID --paths "/*"

Docker Deployment

For container-based deployments.

Create Dockerfile

Create athena-front/Dockerfile:

# Build stage
FROM node:18-alpine AS build

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

# Build with environment variables
ARG VITE_API_URL
ARG VITE_SUPABASE_URL
ARG VITE_SUPABASE_ANON_KEY

ENV VITE_API_URL=$VITE_API_URL
ENV VITE_SUPABASE_URL=$VITE_SUPABASE_URL
ENV VITE_SUPABASE_ANON_KEY=$VITE_SUPABASE_ANON_KEY

RUN npm run build

# Production stage
FROM nginx:alpine

COPY --from=build /app/dist /usr/share/nginx/html

# Configure nginx for SPA routing
RUN echo 'server { \
  listen 80; \
  location / { \
    root /usr/share/nginx/html; \
    try_files $uri $uri/ /index.html; \
  } \
}' > /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Build and Run

# Build
docker build -t athena-frontend \
  --build-arg VITE_API_URL=https://your-api.com \
  --build-arg VITE_SUPABASE_URL=https://xxxx.supabase.co \
  --build-arg VITE_SUPABASE_ANON_KEY=eyJhbGc... \
  .

# Run
docker run -d -p 80:80 athena-frontend

GitHub Actions CI/CD

Automate deployments with GitHub Actions.

Create `.github/workflows/deploy-frontend.yml`

name: Deploy Frontend

on:
  push:
    branches: [main]
    paths:
      - 'athena-front/**'
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: athena-front
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
          cache-dependency-path: athena-front/package-lock.json
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        env:
          VITE_API_URL: ${{ secrets.VITE_API_URL }}
          VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL }}
          VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
        run: npm run build
      
      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          working-directory: athena-front
          vercel-args: '--prod'

Add secrets in GitHub → Settings → Secrets:

VITE_API_URL
VITE_SUPABASE_URL
VITE_SUPABASE_ANON_KEY
VERCEL_TOKEN
VERCEL_ORG_ID
VERCEL_PROJECT_ID

Post-Deployment

Verify Deployment

Visit your frontend URL
Test login with superadmin credentials
Check browser console for errors
Test API connectivity:
- Open browser DevTools → Network tab
- Perform actions that call the API
- Verify requests go to correct backend URL

Configure CORS

Update backend CORS_ORIGINS to include your frontend domain:

CORS_ORIGINS=https://athena.yourdomain.com,https://app.yourdomain.com

Redeploy backend after updating CORS.

Update Backend Environment

Ensure backend knows about frontend URL for any redirects or webhooks.

Performance Optimization

Code Splitting

Vite automatically code-splits by route. Verify in build output:

vite v6.2.0 building for production...
✓ 152 modules transformed.
dist/index.html                   0.50 kB │ gzip:  0.32 kB
dist/assets/index-BwZ7Ujbm.css    8.24 kB │ gzip:  2.31 kB
dist/assets/index-C2fG8uLp.js   215.67 kB │ gzip: 69.85 kB

Lazy Loading

Use dynamic imports for routes:

import { lazy, Suspense } from 'react';

const Dashboard = lazy(() => import('./pages/Dashboard'));

<Suspense fallback={<Loading />}>
  <Dashboard />
</Suspense>

CDN Caching

Most platforms (Vercel, Netlify, Cloudflare) automatically optimize caching. Verify cache headers:

curl -I https://your-frontend.com/assets/index-C2fG8uLp.js

Should see:

cache-control: public, max-age=31536000, immutable

Troubleshooting

Blank page after deployment

Check browser console for errors. Common causes:

Base path issue: Verify vite.config.ts doesn’t have incorrect base
Environment variables not set: Check build logs
404 on routes: Configure SPA redirects (see platform-specific sections)

API calls failing

Check Network tab in DevTools:

CORS errors: Update backend CORS_ORIGINS
Wrong API URL: Verify VITE_API_URL is correct
Mixed content: If frontend is HTTPS, backend must be HTTPS

Build fails

# Clear cache and rebuild
rm -rf node_modules dist
npm install
npm run build

Environment variables not working

Verify variables are prefixed with VITE_
Check variables are set in hosting platform
Redeploy after adding new variables
In Vite, access with import.meta.env.VITE_API_URL

Monitoring

Analytics

Add analytics to track usage:

// src/main.tsx
import ReactGA from 'react-ga4';

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

Error Tracking

Integrate Sentry for frontend errors:

npm install @sentry/react

// src/main.tsx
import * as Sentry from '@sentry/react';

if (import.meta.env.PROD) {
  Sentry.init({
    dsn: 'https://[email protected]/xxxx',
    environment: 'production',
  });
}

Next Steps

Backend Deployment

Ensure backend is deployed and accessible

Environment Variables

Review all configuration options

User Guide

Learn how to use Athena ERP

API Reference

Explore API endpoints

Getting Started

Services

​Overview

​Prerequisites

​Technology Stack

​Directory Structure

​Environment Configuration

​Deployment to Vercel

​Step 1: Install Vercel CLI

​Step 2: Login

​Step 3: Deploy from Local

​Step 4: Configure Environment Variables

​Step 5: Redeploy

​Step 6: Custom Domain (Optional)

​Deployment to Netlify

​Step 1: Install Netlify CLI

​Step 2: Login

​Step 3: Initialize Project

​Step 4: Configure Environment Variables

​Step 5: Deploy

​Step 6: Configure Redirects

​Deployment to Cloudflare Pages

​Step 1: Connect Repository

​Step 2: Configure Build

​Step 3: Add Environment Variables

​Step 4: Deploy

​Step 5: Configure SPA Routing

​Manual Build & Deploy

​Step 1: Build Locally

​Step 2: Test Build Locally

​Step 3: Deploy to Static Hosting

​Example: AWS S3 + CloudFront

​Docker Deployment

​Create Dockerfile

​Build and Run

​GitHub Actions CI/CD

​Create .github/workflows/deploy-frontend.yml

​Post-Deployment

​Verify Deployment

​Configure CORS

​Update Backend Environment

​Performance Optimization

​Code Splitting

​Lazy Loading

​CDN Caching

​Troubleshooting

​Blank page after deployment

​API calls failing

​Build fails

​Environment variables not working

​Monitoring

​Analytics

​Error Tracking

​Next Steps

Backend Deployment

Environment Variables

User Guide

API Reference

Build docs developers (and LLMs) love

Overview

Prerequisites

Technology Stack

Directory Structure

Environment Configuration

Deployment to Vercel

Step 1: Install Vercel CLI

Step 2: Login

Step 3: Deploy from Local

Step 4: Configure Environment Variables

Step 5: Redeploy

Step 6: Custom Domain (Optional)

Deployment to Netlify

Step 1: Install Netlify CLI

Step 2: Login

Step 3: Initialize Project

Step 4: Configure Environment Variables

Step 5: Deploy

Step 6: Configure Redirects

Deployment to Cloudflare Pages

Step 1: Connect Repository

Step 2: Configure Build

Step 3: Add Environment Variables

Step 4: Deploy

Step 5: Configure SPA Routing

Manual Build & Deploy

Step 1: Build Locally

Step 2: Test Build Locally

Step 3: Deploy to Static Hosting

Example: AWS S3 + CloudFront

Docker Deployment

Create Dockerfile

Build and Run

GitHub Actions CI/CD

Create `.github/workflows/deploy-frontend.yml`

Post-Deployment

Verify Deployment

Configure CORS

Update Backend Environment

Performance Optimization

Code Splitting

Lazy Loading

CDN Caching

Troubleshooting

Blank page after deployment

API calls failing

Build fails

Environment variables not working

Monitoring

Analytics

Error Tracking

Next Steps