> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixlnext.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Build scripts

# Build Scripts

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

## Package.json Scripts

### Development Scripts

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```typescript theme={null}
// 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

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

### Version Plugin

```typescript theme={null}
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

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```mermaid theme={null}
graph TD
    A[npm run dev] --> B[Load Environment Variables]
    B --> C[Initialize Vite Dev Server]
    C --> D[TypeScript Compilation]
    D --> E[React Fast Refresh]
    E --> F[Hot Module Replacement]
    F --> G[Development Server Running]
```

### Production Build

```mermaid theme={null}
graph TD
    A[npm run build] --> B[TypeScript Type Check]
    B --> C[Load Production Environment]
    C --> D[Vite Build Process]
    D --> E[Code Splitting & Optimization]
    E --> F[Asset Optimization]
    F --> G[Version Plugin Execution]
    G --> H[Generate version.json]
    H --> I[Write Build Output]
```

### SEO Build

```mermaid theme={null}
graph TD
    A[npm run build:seo] --> B[TypeScript Type Check]
    B --> C[Load SEO Environment]
    C --> D[Vite Build with SEO Mode]
    D --> E[Static Asset Optimization]
    E --> F[Generate Sitemap]
    F --> G[Pre-render Static Pages]
    G --> H[SEO Optimized 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

```json theme={null}
{
  "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**:
   ```bash theme={null}
   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

```json theme={null}
{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm install",
  "framework": "vite"
}
```

### CI/CD Pipeline

```yaml theme={null}
# .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**:
   ```bash theme={null}
   npm run type-check
   ```

2. **Linting Errors**:
   ```bash theme={null}
   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

```bash theme={null}
# Verbose build output
npm run build -- --debug

# Analyze bundle
npm run build -- --analyze

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

## Related Documentation

* [Package Configuration](/docs/configuration/package-json) - Dependencies and scripts
* [Environment Configuration](/docs/configuration/environment) - Environment variables
* [TypeScript Configuration](/docs/configuration/typescript-config) - TypeScript setup
* [Deployment Guide](/docs/deployment) - Production deployment