Deployment Guide

This guide covers how to build and deploy the FHEVM Developer Bootcamp platform to production hosting services.

Overview

The bootcamp is a static single-page application (SPA) built with Vite, React, and TypeScript. It can be deployed to any static hosting service including Netlify, Vercel, GitHub Pages, or AWS S3.

The entire application runs client-side with no backend required. All student progress is stored locally using Zustand with localStorage persistence.

Prerequisites

Before deploying, ensure you have:

Node.js 18+ installed
npm or bun package manager
Git repository with the bootcamp source code
Account on your chosen hosting platform

Build Process

Development Build

Install Dependencies

Install all required packages:

npm install

Or with bun:

bun install

Run Development Server

Start the local development server:

npm run dev

The app will be available at http://localhost:8080.

The dev server is configured in vite.config.ts to run on port 8080 with IPv6 support (host: "::")

Test Locally

Verify all features work:

Navigation through curriculum
Progress tracking persistence
Quiz functionality
Instructor mode toggle
Dark mode theme switching
Internationalization (language switcher)

Production Build

Configure Environment Variables

Create a .env file based on .env.example:

.env

# Network Configuration
VITE_RPC_URL=https://devnet.zama.ai
VITE_CHAIN_ID=8009
VITE_NETWORK_NAME=Zama Devnet

# Contract Addresses
VITE_CONTRACT_ADDRESS=0x0000000000000000000000000000000000000000
VITE_USE_MOCKS=true

# UI Configuration
VITE_COMICY_FONT_URL=https://example.com/path/to/comicy.ttf

# App Metadata
VITE_APP_NAME=FHEVM Developer Bootcamp
VITE_APP_DESCRIPTION=Learn to build confidential applications on Zama Protocol
VITE_GITHUB_REPO=https://github.com/zama-ai/fhevm-bootcamp

All environment variables must be prefixed with VITE_ to be accessible in the frontend.

Build for Production

Create an optimized production build:

npm run build

This compiles TypeScript, bundles assets, and outputs to the dist/ directory.Build configuration in vite.config.ts:

React SWC plugin for fast compilation
Node.js polyfills for crypto libraries
Path aliases (@ → ./src)
Global shims for Buffer, process, global

Build Slides (Optional)

If you’re using the Marp presentation slides:

npm run build:slides

This converts Markdown slides in public/slides/ to HTML using Marp CLI.

Preview Production Build

Test the production build locally:

npm run preview

This serves the dist/ folder to verify the build works correctly.

Deployment Options

Option 1: Netlify

Netlify CLI
Netlify UI

Install Netlify CLI

npm install -g netlify-cli

netlify login

Initialize Site

netlify init

Follow the prompts to:

Create a new site or link to existing
Set build command: npm run build
Set publish directory: dist

Deploy

netlify deploy --prod

Connect Repository

Go to Netlify
Click “Add new site” → “Import an existing project”
Connect your Git provider and select the repository

Configure Build Settings

Set the following:

Build command: npm run build
Publish directory: dist
Node version: 18 or higher

Add Environment Variables

In Site settings → Build & deploy → Environment:

Add all VITE_* variables from your .env file

Deploy

Click “Deploy site” - Netlify will automatically build and deploy.

The public/_redirects file is already configured for SPA routing:

/*    /index.html   200

Option 2: Vercel

Install Vercel CLI

npm install -g vercel

vercel

Follow the prompts. Vercel auto-detects Vite and configures correctly.

Set Environment Variables

vercel env add VITE_RPC_URL
vercel env add VITE_CHAIN_ID
# ... add all VITE_* variables

Or configure in the Vercel dashboard under Settings → Environment Variables.

Production Deployment

vercel --prod

Option 3: GitHub Pages

Update vite.config.ts

Add the base path for your repository:

vite.config.ts

export default defineConfig({
  base: '/fhevm-bootcamp/', // Replace with your repo name
  // ... rest of config
});

Install gh-pages

npm install --save-dev gh-pages

Add Deploy Script

In package.json:

package.json

{
  "scripts": {
    "deploy": "npm run build && gh-pages -d dist"
  }
}

Deploy

npm run deploy

This builds and pushes the dist/ folder to the gh-pages branch.

Enable GitHub Pages

In your repository:

Go to Settings → Pages
Set source to gh-pages branch
Save

Your site will be available at https://<username>.github.io/<repo>/

Option 4: AWS S3 + CloudFront

Create S3 Bucket

aws s3 mb s3://fhevm-bootcamp
aws s3 website s3://fhevm-bootcamp --index-document index.html --error-document index.html

Upload Build

npm run build
aws s3 sync dist/ s3://fhevm-bootcamp --delete

Configure CloudFront (Optional)

For HTTPS and CDN:

Create CloudFront distribution
Set origin to S3 bucket
Configure custom error response: 404 → 200 → /index.html (for SPA routing)
Add SSL certificate via ACM

Environment Variables Reference

All environment variables used in the bootcamp platform:

VITE_RPC_URL

string

required

RPC endpoint for blockchain connections (e.g., https://devnet.zama.ai)

VITE_CHAIN_ID

number

required

Chain ID for the network (e.g., 8009 for Zama Devnet)

VITE_NETWORK_NAME

string

required

Display name for the network (e.g., "Zama Devnet")

VITE_CONTRACT_ADDRESS

string

Default contract address for demos. Use 0x0000... for mock mode.

VITE_USE_MOCKS

boolean

default:"true"

Enable mock contract interactions for testing without blockchain

VITE_COMICY_FONT_URL

string

URL to custom Comicy font file (optional)

VITE_APP_NAME

string

default:"FHEVM Developer Bootcamp"

Application name displayed in title and meta tags

VITE_APP_DESCRIPTION

string

SEO description for the bootcamp

VITE_GITHUB_REPO

string

GitHub repository URL for “View Source” links

Build Optimization

Bundle Size Analysis

Analyze your build size:

npm run build -- --mode analyze

Or use rollup-plugin-visualizer by adding to vite.config.ts:

import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    // ... existing plugins
    visualizer({ open: true })
  ]
});

Performance Tips

Code Splitting

The bootcamp already uses React Router lazy loading for pages. Further split large components:

const ContractExplorer = lazy(() => import('@/components/lesson/ContractExplorer'));

Asset Optimization

Compress images before adding to public/
Use WebP format for better compression
Serve fonts from CDN (already configured for Telegraf)

Caching Strategy

Configure cache headers in your hosting:Netlify (netlify.toml):

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

Vercel (vercel.json):

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

Continuous Deployment

Automated Deploys with Git

Most platforms support automatic deployment on git push:

Connect Repository

Link your Git repository in the hosting dashboard

Configure Branch

Set production branch (usually main or master)

Enable Auto-Deploy

Every push to the production branch triggers a build and deploy

Preview Deploys (Optional)

Enable preview deployments for pull requests to test changes before merging

GitHub Actions Example

.github/workflows/deploy.yml

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run build
        env:
          VITE_RPC_URL: ${{ secrets.VITE_RPC_URL }}
          VITE_CHAIN_ID: ${{ secrets.VITE_CHAIN_ID }}
          VITE_NETWORK_NAME: ${{ secrets.VITE_NETWORK_NAME }}
      
      - name: Deploy to Netlify
        uses: nwtgck/actions-netlify@v2
        with:
          publish-dir: './dist'
          production-deploy: true
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

Troubleshooting

404 on Page Refresh

Problem: Refreshing any route except / returns 404.Solution: Ensure your hosting is configured for SPA routing:

Netlify: Check public/_redirects exists with /* /index.html 200
Vercel: Add vercel.json with rewrites configuration
GitHub Pages: Use hash router or configure 404.html

Environment Variables Not Working

Problem: import.meta.env.VITE_* is undefined.Solution:

Ensure variables are prefixed with VITE_
Rebuild after changing .env
For hosting platforms, set variables in the dashboard
Check variables are set in build environment, not just runtime

Large Bundle Size

Problem: Build size is too large.Solution:

Check for duplicate dependencies: npm dedupe
Analyze bundle: npm run build -- --mode analyze
Remove unused Radix UI components
Use dynamic imports for heavy components

Build Fails on Hosting Platform

Problem: Build succeeds locally but fails on hosting.Solution:

Check Node.js version matches (18+)
Ensure lock file is committed (package-lock.json)
Check build logs for missing environment variables
Try npm ci instead of npm install locally

Custom Domain Setup

After deploying, configure a custom domain:

Netlify
Vercel
GitHub Pages

Go to Site settings → Domain management
Click “Add custom domain”
Follow DNS configuration instructions
Netlify auto-provisions SSL via Let’s Encrypt

In repository Settings → Pages
Enter custom domain
Create CNAME record pointing to <username>.github.io
Enable “Enforce HTTPS”

Monitoring and Analytics

Add Analytics

Integrate analytics in index.html:

<!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>

Or use Plausible for privacy-friendly analytics:

<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.js"></script>

Error Monitoring

Add Sentry for error tracking:

npm install @sentry/react

src/main.tsx

import * as Sentry from "@sentry/react";

Sentry.init({
  dsn: "YOUR_SENTRY_DSN",
  environment: import.meta.env.MODE,
});

Next Steps

After deployment:

Customize branding and content
Set up instructor access
Review the student experience
Monitor analytics and user feedback

Need Help?

Open an issue on GitHub for deployment support

Getting Started

Core Features

Curriculum

Guides

Overview

Prerequisites

Build Process

Development Build

Production Build

Deployment Options

Option 1: Netlify

Option 2: Vercel

Option 3: GitHub Pages

Option 4: AWS S3 + CloudFront

Environment Variables Reference

Build Optimization

Bundle Size Analysis

Performance Tips

Continuous Deployment

Automated Deploys with Git

GitHub Actions Example

Troubleshooting

Custom Domain Setup

Monitoring and Analytics

Add Analytics

Error Monitoring

Next Steps

Need Help?

Getting Started

Core Features

Curriculum

Guides

Documentation Index

​Overview

​Prerequisites

​Build Process

​Development Build

​Production Build

​Deployment Options

​Option 1: Netlify

​Option 2: Vercel

​Option 3: GitHub Pages

​Option 4: AWS S3 + CloudFront

​Environment Variables Reference

​Build Optimization

​Bundle Size Analysis

​Performance Tips

​Continuous Deployment

​Automated Deploys with Git

​GitHub Actions Example

​Troubleshooting

​Custom Domain Setup

​Monitoring and Analytics

​Add Analytics

​Error Monitoring

​Next Steps

Need Help?

Overview

Prerequisites

Build Process

Development Build

Production Build

Deployment Options

Option 1: Netlify

Option 2: Vercel

Option 3: GitHub Pages

Option 4: AWS S3 + CloudFront

Environment Variables Reference

Build Optimization

Bundle Size Analysis

Performance Tips

Continuous Deployment

Automated Deploys with Git

GitHub Actions Example

Troubleshooting

Custom Domain Setup

Monitoring and Analytics

Add Analytics

Error Monitoring

Next Steps