Build Configuration Documentation

This document provides comprehensive documentation for all build configuration files in the STO Education Platform.

Vite Configuration

Location: `vite.config.ts`

Overview

Vite is the primary build tool and development server for the application, providing fast development experience and optimized production builds.

Configuration Details

Import Configuration

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { resolve } from 'path'

Version Plugin

function versionPlugin() {
  return {
    name: 'version-plugin',
    transformIndexHtml(html: string) {
      const version = process.env.npm_package_version || '1.0.0';
      const buildTime = new Date().toISOString();
      const buildHash = `build-${new Date().toISOString().split('T')[0].replace(/-/g, '')}-${new Date().getHours().toString().padStart(2, '0')}${new Date().getMinutes().toString().padStart(2, '0')}`;
      
      // Update meta tags in HTML
      let updatedHtml = html
        .replace(/<meta name="app-version" content="[^"]*">/g, `<meta name="app-version" content="${version}">`)
        .replace(/<meta name="build-time" content="[^"]*">/g, `<meta name="build-time" content="${buildTime}">`)
        .replace(/<meta name="build-hash" content="[^"]*">/g, `<meta name="build-hash" content="${buildHash}">`);

      return updatedHtml;
    },
    generateBundle(this: any) {
      const version = {
        version: process.env.npm_package_version || '1.0.0',
        buildTime: new Date().toISOString(),
        hash: `build-${new Date().toISOString().split('T')[0].replace(/-/g, '')}-${new Date().getHours().toString().padStart(2, '0')}${new Date().getMinutes().toString().padStart(2, '0')}`,
        environment: process.env.NODE_ENV || 'development'
      };

      // Write version info to public directory
      this.emitFile({
        type: 'asset',
        fileName: 'version.json',
        source: JSON.stringify(version, null, 2)
      });
    }
  };
}

Purpose: Custom plugin for version management and update detection
Features:

Injects version information into HTML meta tags
Generates version.json file for update detection
Creates build hash for cache busting
Tracks build time for deployment monitoring

Main Configuration

export default defineConfig(({ mode }) => ({
  plugins: [react(), versionPlugin()],
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),
    },
  },
  define: {
    // Inject version info into the app
    __APP_VERSION__: JSON.stringify(process.env.npm_package_version || '1.0.0'),
    __BUILD_TIME__: JSON.stringify(new Date().toISOString()),
    __BUILD_HASH__: JSON.stringify(`build-${new Date().toISOString().split('T')[0].replace(/-/g, '')}-${new Date().getHours().toString().padStart(2, '0')}${new Date().getMinutes().toString().padStart(2, '0')}`),
  },
  esbuild: mode === 'production'
    ? { 
        pure: ['console.log', 'console.info', 'console.debug', 'console.trace'],
        drop: ['debugger']
      }
    : {},
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          router: ['react-router-dom'],
          supabase: ['@supabase/supabase-js'],
        },
      },
    },
  },
}))

Configuration Breakdown

Plugins

React Plugin: Enables React Fast Refresh and JSX transformation
Version Plugin: Custom plugin for version management

Path Resolution

Alias: @ maps to ./src directory for clean imports

Global Definitions

Version Info: Injects build information into the application
Build Time: Timestamp of the build
Build Hash: Unique hash for cache busting

ESBuild Configuration

Production Mode: Removes console logs and debugger statements
Development Mode: Preserves debugging information

Build Optimization

Manual Chunks: Splits code into logical chunks for better caching
- vendor: React and React DOM
- router: React Router
- supabase: Supabase client

TypeScript Configuration

Location: `tsconfig.json`

Root Configuration

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ]
}

Purpose: Project references for different build targets
Structure: Uses project references for modular configuration

Application Configuration: `tsconfig.app.json`

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"]
}

Configuration Details

Compiler Options

Target: ES2020 for modern JavaScript features
Module: ESNext for latest module syntax
JSX: React JSX transformation
Strict Mode: Enables all strict type checking options

Path Mapping

Base URL: Current directory
Paths: @/* maps to ./src/* for clean imports

Type Checking

Strict: Enables strict type checking
No Unused Locals: Warns about unused variables
No Unused Parameters: Warns about unused function parameters
No Fallthrough Cases: Prevents switch statement fallthrough

Module Resolution

Bundler: Uses bundler-specific module resolution
Allow TS Extensions: Allows importing .ts files
Isolated Modules: Treats each file as a separate module

Node Configuration: `tsconfig.node.json`

{
  "compilerOptions": {
    "composite": true,
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "noEmit": true
  },
  "include": ["vite.config.ts"]
}

Purpose: TypeScript configuration for Node.js build tools
Features:

Composite: Enables project references
Build Info: Caches build information for faster subsequent builds
Strict: Strict type checking for build tools

ESLint Configuration

Location: `eslint.config.js`

Configuration Overview

import js from '@eslint/js'
import globals from 'globals'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'
import tseslint from 'typescript-eslint'

export default tseslint.config(
  { ignores: ['dist'] },
  {
    extends: [js.configs.recommended, ...tseslint.configs.recommended],
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      ecmaVersion: 2020,
      globals: globals.browser,
    },
    plugins: {
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      'react-refresh/only-export-components': [
        'warn',
        { allowConstantExport: true },
      ],
    },
  },
)

Configuration Breakdown

Extends

JavaScript Recommended: Standard JavaScript linting rules
TypeScript Recommended: TypeScript-specific linting rules

Files

Target: TypeScript and TSX files
Ignore: Dist directory

Language Options

ECMA Version: ES2020
Globals: Browser globals

Plugins

React Hooks: React Hooks linting rules
React Refresh: React Refresh linting rules

Rules

React Hooks: Recommended React Hooks rules
React Refresh: Only export components rule

PostCSS Configuration

Location: `postcss.config.js`

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Purpose: PostCSS configuration for CSS processing
Plugins:

Tailwind CSS: Utility-first CSS framework
Autoprefixer: Automatic vendor prefixing

Tailwind CSS Configuration

Location: `tailwind.config.js`

Configuration Overview

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f0fdf4',
          100: '#dcfce7',
          200: '#bbf7d0',
          300: '#86efac',
          400: '#4ade80',
          500: '#22c55e',
          600: '#16a34a',
          700: '#15803d',
          800: '#166534',
          900: '#14532d',
          950: '#052e16',
        },
        // Additional color definitions
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
    },
  },
  plugins: [],
}

Configuration Details

Content Sources

HTML: index.html
Source Files: All TypeScript and TSX files in src directory

Theme Extension

Colors: Custom primary color palette
Fonts: Inter font family configuration
Spacing: Custom spacing values
Breakpoints: Custom responsive breakpoints

Plugins

Empty Array: No additional plugins configured

Vercel Configuration

Location: `vercel.json`

Deployment Configuration

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite",
  "functions": {
    "app/api/version.json": {
      "runtime": "nodejs18.x"
    }
  },
  "headers": [
    {
      "source": "/api/(.*)",
      "headers": [
        {
          "key": "Access-Control-Allow-Origin",
          "value": "*"
        },
        {
          "key": "Access-Control-Allow-Methods",
          "value": "GET, POST, PUT, DELETE, OPTIONS"
        },
        {
          "key": "Access-Control-Allow-Headers",
          "value": "Content-Type, Authorization"
        }
      ]
    }
  ],
  "rewrites": [
    {
      "source": "/api/(.*)",
      "destination": "/api/$1"
    }
  ]
}

Configuration Details

Build Configuration

Build Command: npm run build
Output Directory: dist
Framework: Vite

Functions

Version API: Node.js 18.x runtime for version endpoint

Headers

CORS: Cross-origin resource sharing headers
API Routes: Headers for API endpoints

Rewrites

API Routes: Rewrites for API endpoints

Environment Configuration

Environment Variables

Required Variables

# Supabase Configuration
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

# Payment Configuration
VITE_PAYMOB_SECRET_KEY=your_paymob_secret_key
VITE_PAYMOB_PUBLIC_KEY=your_paymob_public_key

# Video Conferencing
VITE_WHEREBY_API_KEY=your_whereby_api_key
VITE_WHEREBY_SUBDOMAIN=your_whereby_subdomain

# Communication
VITE_SENDBIRD_APP_ID=your_sendbird_app_id
VITE_SENDBIRD_API_TOKEN=your_sendbird_api_token

# Analytics
VITE_POSTHOG_HOST=your_posthog_host
VITE_POSTHOG_KEY=your_posthog_key

# Maps
VITE_MAPBOX_ACCESS_TOKEN=your_mapbox_token

# App Configuration
VITE_APP_URL=your_app_url

Variable Prefixes

VITE_: Exposed to client-side code
Server-side: Used only in Edge Functions

Build Scripts

Development Scripts

Development Server

npm run dev

Purpose: Start development server
Features:

Hot module replacement
Fast refresh
Error overlay
Source maps

Production Build

npm run build

Purpose: Create production build
Features:

TypeScript checking disabled for speed
Sitemap generation
Asset optimization
Code splitting

Preview Build

npm run preview

Purpose: Preview production build locally
Features:

Production build serving
Local testing
Performance testing

Sitemap Scripts

Advanced Sitemap

npm run generate-sitemap

Purpose: Generate comprehensive sitemap
Features:

All routes included
Metadata generation
SEO optimization

Simple Sitemap

npm run generate-sitemap:simple

Purpose: Generate basic sitemap
Features:

Quick generation
Basic route listing

Build Optimization

Code Splitting

Vendor Chunks: Separate vendor libraries
Route Chunks: Route-based code splitting
Dynamic Imports: Lazy loading of components

Asset Optimization

Image Optimization: Automatic image optimization
CSS Purging: Unused CSS removal
Tree Shaking: Dead code elimination

Performance Features

Bundle Analysis: Bundle size monitoring
Source Maps: Debug-friendly builds
Hot Reload: Fast development experience

Deployment Configuration

Vercel Deployment

Automatic Deployments: GitHub integration
Environment Variables: Secure variable management
Custom Domains: Domain configuration
CDN: Global content delivery

Build Process

Install Dependencies: npm install
Type Checking: TypeScript validation
Build Application: Vite build process
Generate Sitemap: SEO optimization
Deploy: Vercel deployment

Environment Management

Development: Local environment variables
Staging: Staging environment variables
Production: Production environment variables

Monitoring and Analytics

Build Monitoring

Build Times: Track build performance
Bundle Sizes: Monitor bundle size changes
Error Tracking: Build error monitoring

Performance Monitoring

Core Web Vitals: Performance metrics
User Experience: Real user monitoring
Error Tracking: Application error tracking

Security Configuration

Build Security

Environment Variables: Secure variable handling
Source Maps: Production source map management
Dependencies: Regular security updates

Deployment Security

HTTPS: Automatic HTTPS enforcement
Headers: Security headers configuration
CORS: Cross-origin resource sharing

Maintenance and Updates

Regular Maintenance

Dependency Updates: Regular package updates
Security Patches: Immediate security updates
Build Optimization: Performance improvements

Monitoring

Build Success: Monitor build success rates
Performance: Track build performance
Errors: Monitor build errors

Troubleshooting

Common Issues

Build Failures: TypeScript errors, dependency issues
Performance: Slow builds, large bundles
Deployment: Environment variable issues

Solutions

TypeScript Errors: Fix type issues, update types
Performance: Optimize imports, reduce bundle size
Deployment: Check environment variables, verify configuration

​Build Configuration Documentation

​Vite Configuration

​Location: vite.config.ts

​Overview

​Configuration Details

​Import Configuration

​Version Plugin

​Main Configuration

​Configuration Breakdown

Plugins

Path Resolution

Global Definitions

ESBuild Configuration

Build Optimization

​TypeScript Configuration

​Location: tsconfig.json

​Root Configuration

​Application Configuration: tsconfig.app.json

​Configuration Details

Compiler Options

Path Mapping

Type Checking

Module Resolution

​Node Configuration: tsconfig.node.json

​ESLint Configuration

​Location: eslint.config.js

​Configuration Overview

​Configuration Breakdown

Extends

Files

Language Options

Plugins

Rules

​PostCSS Configuration

​Location: postcss.config.js

​Tailwind CSS Configuration

​Location: tailwind.config.js

​Configuration Overview

​Configuration Details

Content Sources

Theme Extension

Plugins

​Vercel Configuration

​Location: vercel.json

​Deployment Configuration

​Configuration Details

Build Configuration

Functions

Headers

Rewrites

​Environment Configuration

​Environment Variables

​Required Variables

​Variable Prefixes

​Build Scripts

​Development Scripts

​Development Server

​Production Build

​Preview Build

​Sitemap Scripts

​Advanced Sitemap

​Simple Sitemap

​Build Optimization

​Code Splitting

​Asset Optimization

​Performance Features

​Deployment Configuration

​Vercel Deployment

​Build Process

​Environment Management

​Monitoring and Analytics

​Build Monitoring

​Performance Monitoring

​Security Configuration

​Build Security

​Deployment Security

​Maintenance and Updates

​Regular Maintenance

​Monitoring

​Troubleshooting

Build Configuration Documentation

Vite Configuration

Location: `vite.config.ts`

Overview

Configuration Details

Import Configuration

Version Plugin

Main Configuration

Configuration Breakdown

TypeScript Configuration

Location: `tsconfig.json`

Root Configuration

Application Configuration: `tsconfig.app.json`

Configuration Details

Node Configuration: `tsconfig.node.json`

ESLint Configuration

Location: `eslint.config.js`

Configuration Overview

Configuration Breakdown

PostCSS Configuration

Location: `postcss.config.js`

Tailwind CSS Configuration

Location: `tailwind.config.js`

Configuration Overview

Configuration Details

Vercel Configuration

Location: `vercel.json`

Deployment Configuration

Configuration Details

Environment Configuration

Environment Variables

Required Variables

Variable Prefixes

Build Scripts

Development Scripts

Development Server

Production Build

Preview Build

Sitemap Scripts

Advanced Sitemap

Simple Sitemap

Build Optimization

Code Splitting

Asset Optimization

Performance Features

Deployment Configuration

Vercel Deployment

Build Process

Environment Management

Monitoring and Analytics

Build Monitoring

Performance Monitoring

Security Configuration

Build Security

Deployment Security

Maintenance and Updates

Regular Maintenance

Monitoring

Troubleshooting

Common Issues

Solutions