Installation

Overview

This guide provides comprehensive instructions for installing and configuring the FHEVM Developer Bootcamp on your local machine. Follow these steps to set up your complete development environment.

Looking for a quick setup? Check out the Quick Start guide for a streamlined installation process.

System Requirements

Before installing the bootcamp, ensure your system meets these requirements:

Hardware Requirements

RAM: Minimum 4GB, recommended 8GB+
Storage: At least 1GB free disk space
CPU: Any modern processor (2+ cores recommended)
Network: Stable internet connection for package installation

Operating System Support

macOS
Linux
Windows

macOS 10.15 (Catalina) or later
Both Intel and Apple Silicon (M1/M2/M3) supported
Xcode Command Line Tools (installed automatically with Homebrew)

Prerequisites

1. Node.js and npm

The bootcamp requires Node.js 18.x or higher.

Check Current Version

Verify if Node.js is already installed:

node --version
npm --version

Expected output:

v18.x.x  # or v20.x.x, v22.x.x
9.x.x    # or 10.x.x

Install Node.js (if needed)

Using nvm (Recommended)
macOS (Homebrew)
Ubuntu/Debian
Windows

Install Node Version Manager for easy version switching:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc on macOS

# Install Node.js LTS
nvm install --lts
nvm use --lts

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node@20

# Update package index
sudo apt update

# Install Node.js from NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Download the installer from nodejs.org and run it, or use Chocolatey:

# Using Chocolatey
choco install nodejs-lts

Verify Installation

Confirm Node.js and npm are installed correctly:

node --version && npm --version

2. Git Version Control

Git is required to clone the bootcamp repository.

# Using Homebrew
brew install git

Verify installation:

git --version

3. Code Editor (Recommended)

While any text editor works, we recommend Visual Studio Code with these extensions:

ES7+ React/Redux/React-Native snippets - Code snippets
Tailwind CSS IntelliSense - Tailwind autocomplete
ESLint - Code quality
Prettier - Code formatting
Solidity (if you plan to modify smart contracts) - Solidity syntax

# Install VS Code on macOS
brew install --cask visual-studio-code

# Install VS Code on Ubuntu
sudo snap install code --classic

Installation Steps

Step 1: Clone the Repository

Clone the bootcamp repository to your local machine:

# Clone via HTTPS
git clone https://github.com/your-org/fhevm-bootcamp.git

# Or clone via SSH (if you have SSH keys configured)
git clone git@github.com:your-org/fhevm-bootcamp.git

# Navigate to the project directory
cd fhevm-bootcamp

Replace your-org/fhevm-bootcamp with the actual repository URL. If you’re running this for your own community, consider forking the repository first.

Step 2: Install Dependencies

Install all required npm packages:

npm install

This will install:

82 direct dependencies including React, TypeScript, Vite, wagmi, fhevmjs, and more
All transitive dependencies (approximately 350MB total)

Installation takes too long?

If npm install is slow, you can try alternative package managers:Using pnpm (faster):

npm install -g pnpm
pnpm install

Using bun (fastest):

curl -fsSL https://bun.sh/install | bash
bun install

Note: The project includes a bun.lockb file, so Bun is fully supported.

Step 3: Environment Configuration

Configure environment variables for the bootcamp:

Copy Environment Template

cp .env.example .env

Edit Environment Variables

Open .env in your editor and configure the following:

.env

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

# Contract Addresses (update if deploying your own contracts)
VITE_CONTRACT_ADDRESS=0x0000000000000000000000000000000000000000

# Use mock FHE client for tutorials (recommended for learning)
VITE_USE_MOCKS=true

# App Metadata (customize for your bootcamp)
VITE_APP_NAME=FHEVM Developer Bootcamp
VITE_APP_DESCRIPTION=Learn to build confidential applications on Zama Protocol
VITE_GITHUB_REPO=https://github.com/your-org/fhevm-bootcamp

Understanding Environment Variables

VITE_RPC_URL

Purpose: RPC endpoint for blockchain connectionOptions:

https://devnet.zama.ai - Zama’s development network (default)
https://rpc.sepolia.org - Ethereum Sepolia testnet
Custom RPC endpoint for your network

VITE_USE_MOCKS

Purpose: Toggle between mock and real FHE clientValues:

true - Use mock FHE client (recommended for tutorials)
false - Use real fhevmjs library (requires proper network setup)

The mock client simulates encryption/decryption without requiring a live FHEVM network, perfect for learning.

VITE_CONTRACT_ADDRESS

Purpose: Deployed smart contract addressLeave as 0x0000... for tutorial mode. Update with actual deployed contract address when ready for live interactions.

Never commit your .env file to version control if it contains sensitive information like private keys or API keys. The .gitignore is already configured to exclude it.

Step 4: Verify Installation

Test that everything is set up correctly:

# Start the development server
npm run dev

You should see:

VITE v5.4.19  ready in 342 ms

➜  Local:   http://localhost:8080/
➜  Network: http://192.168.1.100:8080/
➜  press h + enter to show help

Open http://localhost:8080 in your browser. You should see the bootcamp dashboard.

Post-Installation Configuration

TypeScript Configuration

The bootcamp uses TypeScript with these configurations:

tsconfig.json (Root)
tsconfig.app.json
tsconfig.node.json

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]  // Enables @ imports
    }
  }
}

Vite Configuration Details

The vite.config.ts includes important configurations:

vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import path from "path";
import { nodePolyfills } from "vite-plugin-node-polyfills";

export default defineConfig(({ mode }) => ({
  server: {
    host: "::",      // Listen on all network interfaces
    port: 8080,      // Development server port
  },
  plugins: [
    react(),  // React with SWC for fast refresh
    nodePolyfills({
      // Required for fhevmjs and ethers.js compatibility
      include: ["buffer", "process", "util", "events", "stream"],
      globals: { Buffer: true, global: true, process: true },
      protocolImports: true,
    }),
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  define: {
    global: "globalThis",
    "process.env": {},
  },
  optimizeDeps: {
    esbuildOptions: {
      define: { global: "globalThis" },
    },
  },
}));

Why Node.js polyfills? The fhevmjs library and blockchain tools like ethers.js were designed for Node.js. The polyfills allow these libraries to work in the browser.

Tailwind CSS Configuration

The bootcamp uses Tailwind CSS with custom theme extensions:

tailwind.config.ts

import type { Config } from "tailwindcss";

export default {
  darkMode: ["class"],
  content: [
    "./pages/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
    "./app/**/*.{ts,tsx}",
    "./src/**/*.{ts,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        border: "hsl(var(--border))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        // ... more theme colors
      },
      // Custom animations, fonts, etc.
    },
  },
  plugins: [
    require("tailwindcss-animate"),
    require("@tailwindcss/typography"),
  ],
} satisfies Config;

Development Workflow

Available Scripts

# Development
npm run dev              # Start dev server with hot reload
npm run dev -- --port 3000  # Start on custom port

# Production Build
npm run build            # Create optimized production build
npm run build:dev        # Development mode build (with source maps)
npm run preview          # Preview production build locally

# Code Quality
npm run lint             # Run ESLint
npm run lint -- --fix    # Auto-fix linting issues

# Presentation Slides
npm run build:slides     # Generate HTML slides from markdown

Project Structure

Understanding the codebase organization:

fhevm-bootcamp/
├── public/                    # Static assets
│   ├── slides/               # Week presentation slides (Marp)
│   └── _redirects            # Netlify SPA routing config
├── src/
│   ├── components/
│   │   ├── layout/           # AppBar, Navigation, Sidebar
│   │   ├── lesson/           # Lesson sections, quizzes, objectives
│   │   ├── homework/         # Grading rubrics, code templates
│   │   └── ui/               # 50+ shadcn/ui components
│   ├── data/
│   │   ├── curriculum.ts     # Complete 4-week curriculum data
│   │   └── contractExamples.ts  # Contract library
│   ├── hooks/                # Custom React hooks
│   ├── lib/
│   │   ├── fhe/              # FHE client integration
│   │   └── wallet/           # Wagmi wallet configuration
│   ├── locales/              # i18n translations (en, fr, zh)
│   ├── pages/                # Route pages (Dashboard, Lessons, etc.)
│   ├── state/                # Zustand stores
│   ├── App.tsx               # Root app component
│   ├── main.tsx              # App entry point
│   └── index.css             # Global styles
├── vote-app/                  # Sample voting dApp (Week 3 project)
│   ├── contracts/            # Solidity smart contracts
│   ├── types/                # TypeScript contract types
│   └── hardhat.config.js     # Hardhat configuration
├── .env.example              # Environment variable template
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── vite.config.ts            # Vite bundler config
└── tailwind.config.ts        # Tailwind CSS config

Troubleshooting

Common Installation Issues

npm install fails with EACCES permission error

Problem: Permission denied when installing global packagesSolution: Fix npm permissions or use a Node version manager:

# Option 1: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Option 2: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

Module not found: Can't resolve '@/...'

Problem: TypeScript path aliases not workingSolution: Ensure tsconfig.json has the correct path configuration:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Then restart your development server and IDE.

Vite build fails with 'Buffer is not defined'

Problem: Node.js polyfills not loadedSolution: Verify vite-plugin-node-polyfills is installed and configured:

npm install vite-plugin-node-polyfills --save-dev

Check vite.config.ts includes the plugin with correct options (see configuration above).

Port 8080 already in use

Problem: Another service is using port 8080Solution: Kill the process or use a different port:

# Find process using port 8080 (macOS/Linux)
lsof -ti:8080

# Kill the process
kill -9 $(lsof -ti:8080)

# Or start on a different port
npm run dev -- --port 3000

React hooks error or duplicate React

Problem: Multiple React versions in node_modulesSolution: Clear dependencies and reinstall:

rm -rf node_modules package-lock.json
npm install

If using npm workspaces or linking packages, ensure React is de-duplicated:

npm dedupe

Tailwind styles not applying

Problem: Tailwind CSS not processing stylesSolution:

Verify tailwind.config.ts has correct content paths

Ensure @tailwind directives are in src/index.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

Restart the dev server (Ctrl+C, then npm run dev)

Type errors with fhevmjs or ethers

Problem: TypeScript can’t find type definitionsSolution: Install missing type definitions:

npm install --save-dev @types/node

If errors persist, add to tsconfig.json:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Platform-Specific Issues

Windows
macOS
Linux

Issue: Line ending problems

# Configure git to handle line endings
git config --global core.autocrlf true

Issue: Long path errors

# Enable long paths (requires admin)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Recommendation: Use WSL 2 for best compatibility

Issue: Xcode Command Line Tools required

xcode-select --install

Issue: Homebrew permissions

sudo chown -R $(whoami) $(brew --prefix)/*

Issue: Missing build tools

# Ubuntu/Debian
sudo apt-get install build-essential

# Fedora
sudo dnf groupinstall "Development Tools"

Issue: Node.js version from default repos is too old

# Use NodeSource for latest versions
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Updating the Bootcamp

To update to the latest version:

# Pull latest changes from repository
git pull origin main

# Update dependencies
npm install

# Rebuild (if needed)
npm run build

If you’ve made local customizations, use git stash before pulling to avoid conflicts:

git stash
git pull origin main
git stash pop

Production Deployment

When ready to deploy your bootcamp:

Build for Production

npm run build

This creates an optimized build in the dist/ directory.

Deploy to Static Hosting

The bootcamp works with any static hosting service:

Netlify
Vercel
GitHub Pages

# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod --dir=dist

The public/_redirects file handles SPA routing automatically.

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod

# Build with correct base path
npm run build -- --base=/fhevm-bootcamp/

# Deploy to gh-pages branch
npx gh-pages -d dist

Next Steps

Start Learning

Begin Week 1 and start your FHEVM journey

Curriculum Overview

Explore the complete 4-week learning path

Instructor Guide

Learn how to run this bootcamp for your community

Contributing

Help improve the bootcamp for future learners

Getting Help

If you encounter issues not covered in this guide:

Check the Console: Browser DevTools (F12) often show helpful error messages
Search Issues: Check the GitHub Issues for similar problems
Community Support: Join the Zama Discord or community forums
Report Bugs: Open a new issue with reproduction steps and system details

Include your Node.js version (node --version), operating system, and error messages when asking for help.

Getting Started

Core Features

Curriculum

Guides

Overview

System Requirements

Hardware Requirements

Operating System Support

Prerequisites

1. Node.js and npm

2. Git Version Control

3. Code Editor (Recommended)

Installation Steps

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Environment Configuration

Step 4: Verify Installation

Post-Installation Configuration

TypeScript Configuration

Vite Configuration Details

Tailwind CSS Configuration

Development Workflow

Available Scripts

Project Structure

Troubleshooting

Common Installation Issues

Platform-Specific Issues

Updating the Bootcamp

Production Deployment

Build for Production

Deploy to Static Hosting

Next Steps

Start Learning

Curriculum Overview

Instructor Guide

Contributing

Getting Help

Build docs developers (and LLMs) love

Getting Started

Core Features

Curriculum

Guides

Documentation Index

​Overview

​System Requirements

​Hardware Requirements

​Operating System Support

​Prerequisites

​1. Node.js and npm

​2. Git Version Control

​3. Code Editor (Recommended)

​Installation Steps

​Step 1: Clone the Repository

​Step 2: Install Dependencies

​Step 3: Environment Configuration

​Step 4: Verify Installation

​Post-Installation Configuration

​TypeScript Configuration

​Vite Configuration Details

​Tailwind CSS Configuration

​Development Workflow

​Available Scripts

​Project Structure

​Troubleshooting

​Common Installation Issues

​Platform-Specific Issues

​Updating the Bootcamp

​Production Deployment

​Build for Production

​Deploy to Static Hosting

​Next Steps

Start Learning

Curriculum Overview

Instructor Guide

Contributing

​Getting Help

Build docs developers (and LLMs) love

Overview

System Requirements

Hardware Requirements

Operating System Support

Prerequisites

1. Node.js and npm

2. Git Version Control

3. Code Editor (Recommended)

Installation Steps

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Environment Configuration

Step 4: Verify Installation

Post-Installation Configuration

TypeScript Configuration

Vite Configuration Details

Tailwind CSS Configuration

Development Workflow

Available Scripts

Project Structure

Troubleshooting

Common Installation Issues

Platform-Specific Issues

Updating the Bootcamp

Production Deployment

Build for Production

Deploy to Static Hosting

Next Steps

Getting Help