Skip to main content

Build Scripts

This document details all build scripts and automation tools used in the STO Education Platform.

Package.json Scripts

Development Scripts

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "build:seo": "tsc && vite build --mode seo",
    "preview": "vite preview",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "type-check": "tsc --noEmit"
  }
}

npm run dev

  • Purpose: Start development server with hot module replacement
  • Command: vite
  • Features:
    • Hot module replacement (HMR)
    • TypeScript compilation
    • Source maps for debugging
    • Fast refresh for React components
    • Environment variable loading

npm run build

  • Purpose: Build production bundle
  • Command: tsc && vite build
  • Process:
    1. TypeScript type checking (tsc)
    2. Vite production build with optimizations
    3. Asset optimization and minification
    4. Chunk splitting for better caching

npm run build:seo

  • Purpose: Build optimized for SEO and static hosting
  • Command: tsc && vite build --mode seo
  • Features:
    • Static asset optimization
    • SEO-friendly meta tags
    • Sitemap generation
    • Static page pre-rendering

npm run preview

  • Purpose: Preview production build locally
  • Command: vite preview
  • Use Case: Test production build before deployment

npm run lint

  • Purpose: Run ESLint for code quality checks
  • Command: eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0
  • Features:
    • TypeScript and React linting
    • Unused directive reporting
    • Zero warnings policy

npm run type-check

  • Purpose: TypeScript type checking without emitting files
  • Command: tsc --noEmit
  • Use Case: CI/CD type validation

SEO and Sitemap Scripts

{
  "scripts": {
    "generate-sitemap": "node scripts/generate-sitemap.js",
    "generate-sitemap:simple": "node scripts/generate-sitemap-simple.js"
  }
}

npm run generate-sitemap

  • Purpose: Generate comprehensive sitemap with dynamic content
  • File: scripts/generate-sitemap.js
  • Features:
    • Dynamic route generation from database
    • Static page inclusion
    • Priority and frequency settings
    • XML sitemap format

npm run generate-sitemap:simple

  • Purpose: Generate simple static sitemap
  • File: scripts/generate-sitemap-simple.js
  • Use Case: Quick sitemap generation for static sites

Build Configuration

Vite Configuration

// vite.config.ts
export default defineConfig(({ mode }) => ({
  plugins: [react(), versionPlugin()],
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),
    },
  },
  define: {
    __APP_VERSION__: JSON.stringify(process.env.npm_package_version || '1.0.0'),
    __BUILD_TIME__: JSON.stringify(new Date().toISOString()),
    __BUILD_HASH__: JSON.stringify(generateBuildHash()),
  },
  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'],
        },
      },
    },
  },
}))

Build Optimizations

Production Optimizations

  • Code Splitting: Automatic chunk splitting for better caching
  • Tree Shaking: Remove unused code
  • Minification: JavaScript and CSS minification
  • Asset Optimization: Image and font optimization
  • Console Removal: Remove console statements in production

Manual Chunk Configuration

manualChunks: {
  vendor: ['react', 'react-dom'],        // Core React libraries
  router: ['react-router-dom'],          // Routing library
  supabase: ['@supabase/supabase-js'],   // Backend client
}

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 = generateBuildHash()
      
      // 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() {
      const version = {
        version: process.env.npm_package_version || '1.0.0',
        buildTime: new Date().toISOString(),
        hash: generateBuildHash(),
        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)
      })
    }
  }
}

Sitemap Generation Scripts

Comprehensive Sitemap Generator

// scripts/generate-sitemap.js
const fs = require('fs')
const path = require('path')

async function generateSitemap() {
  const baseUrl = process.env.VITE_APP_URL || 'https://sto-education.com'
  
  // Static pages
  const staticPages = [
    '/',
    '/about',
    '/courses',
    '/teachers',
    '/contact',
    '/privacy',
    '/terms'
  ]
  
  // Dynamic pages (from database)
  const dynamicPages = await fetchDynamicPages()
  
  // Generate sitemap XML
  const sitemap = generateSitemapXML([...staticPages, ...dynamicPages], baseUrl)
  
  // Write to public directory
  fs.writeFileSync(path.join(__dirname, '../public/sitemap.xml'), sitemap)
  
  console.log('✅ Sitemap generated successfully')
}

function generateSitemapXML(pages, baseUrl) {
  const urls = pages.map(page => `
  <url>
    <loc>${baseUrl}${page}</loc>
    <lastmod>${new Date().toISOString()}</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>`).join('')
  
  return `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${urls}
</urlset>`
}

Simple Sitemap Generator

// scripts/generate-sitemap-simple.js
const fs = require('fs')
const path = require('path')

function generateSimpleSitemap() {
  const baseUrl = 'https://sto-education.com'
  
  const pages = [
    { url: '/', priority: '1.0' },
    { url: '/courses', priority: '0.9' },
    { url: '/teachers', priority: '0.8' },
    { url: '/about', priority: '0.7' },
    { url: '/contact', priority: '0.6' }
  ]
  
  const sitemap = generateXML(pages, baseUrl)
  
  fs.writeFileSync(path.join(__dirname, '../public/sitemap.xml'), sitemap)
  console.log('✅ Simple sitemap generated')
}

function generateXML(pages, baseUrl) {
  const urls = pages.map(page => `
  <url>
    <loc>${baseUrl}${page.url}</loc>
    <priority>${page.priority}</priority>
    <changefreq>weekly</changefreq>
  </url>`).join('')
  
  return `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${urls}
</urlset>`
}

Build Process Flow

Development Build

Production Build

SEO Build

Build Output Structure

Production Build Output

dist/
├── index.html                 # Main HTML file
├── assets/
│   ├── index-[hash].js       # Main application bundle
│   ├── index-[hash].css      # Main stylesheet
│   ├── vendor-[hash].js      # Vendor libraries chunk
│   ├── router-[hash].js      # Router chunk
│   └── supabase-[hash].js    # Supabase chunk
├── version.json              # Build version information
└── sitemap.xml               # Generated sitemap

Version Information

{
  "version": "1.0.0",
  "buildTime": "2024-01-15T10:30:00.000Z",
  "hash": "build-20240115-1030",
  "environment": "production"
}

Build Performance

Optimization Strategies

  1. Code Splitting:
    • Separate vendor libraries
    • Route-based splitting
    • Dynamic imports for large components
  2. Asset Optimization:
    • Image compression
    • Font optimization
    • CSS purging
  3. Bundle Analysis:
    npm run build -- --analyze
    
  4. Tree Shaking:
    • Remove unused code
    • Optimize imports
    • Dead code elimination

Build Metrics

  • Bundle Size: Target < 500KB for main bundle
  • Load Time: < 3 seconds for initial load
  • Cache Efficiency: Long-term caching for vendor chunks
  • Compression: Gzip compression for all assets

Deployment Integration

Vercel Deployment

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm install",
  "framework": "vite"
}

CI/CD Pipeline

# .github/workflows/deploy.yml
name: Build and Deploy
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install
      - run: npm run type-check
      - run: npm run lint
      - run: npm run build
      - run: npm run generate-sitemap

Troubleshooting

Common Build Issues

  1. TypeScript Errors:
    npm run type-check
    
  2. Linting Errors:
    npm run lint
    
  3. Build Failures:
    • Check environment variables
    • Verify dependencies
    • Check for circular dependencies
  4. Performance Issues:
    • Analyze bundle size
    • Check for large dependencies
    • Optimize imports

Debug Build Process

# Verbose build output
npm run build -- --debug

# Analyze bundle
npm run build -- --analyze

# Check build size
npm run build && npx vite-bundle-analyzer dist