memory-infrastructure-palace/code/websites/pokedex.online/BUILD.md

# Build Process Documentation

## Overview

Pokedex.Online uses a multi-stage build process for frontend and backend components.

## Prerequisites

- Node.js 20+ (LTS)
- npm 10+
- Docker & Docker Compose (for containerized builds)

## Build Scripts

### Frontend Build

```bash
# Build frontend only
npm run build:frontend

# Output: dist/ directory with optimized Vue.js app
```

**What it does:**
- Compiles Vue 3 components
- Bundles JavaScript with Vite (uses Rollup)
- Minifies with Terser
- Generates source maps
- Splits vendor chunks for better caching
- Optimizes CSS with code splitting
- Processes assets (images, fonts)

**Build Optimizations:**
- **Code Splitting**: Separate chunks for Vue, Highlight.js, Virtual Scroller
- **Tree Shaking**: Removes unused code
- **Minification**: Reduces bundle size
- **Source Maps**: Enables production debugging
- **Asset Optimization**: Inlines small assets, optimizes images

### Backend Build

```bash
# Build backend (validation only - Node.js doesn't need compilation)
npm run build:backend
```

**What it does:**
- Validates environment configuration
- Checks dependencies are installed
- No actual compilation (Node.js runs directly)

### Full Build

```bash
# Build both frontend and backend
npm run build

# Then verify the build
npm run build:verify
```

### Build Verification

```bash
npm run build:verify
```

**Checks:**
- ✅ dist/ directory exists
- ✅ index.html present
- ✅ JavaScript bundles created
- ✅ CSS files generated
- ✅ Assets directory populated
- ⚠️  Warns on large bundles (>1MB)
- 📊 Shows total build size

## Build Output

### Frontend (`dist/`)

```
dist/
├── index.html              # Entry point
├── assets/
│   ├── vue-vendor.*.js    # Vue + Vue Router chunk
│   ├── highlight.*.js     # Highlight.js chunk
│   ├── virtual-scroller.*.js  # Virtual Scroller chunk
│   ├── index.*.js         # Main app bundle
│   ├── index.*.css        # Compiled styles
│   └── *.{png,svg,ico}    # Optimized assets
└── vite.svg               # App icon
```

**Expected Sizes:**
- Total: 2-3 MB (uncompressed)
- vue-vendor chunk: ~500 KB
- Main bundle: ~300-500 KB
- Highlight.js: ~200-400 KB
- CSS: ~50-100 KB

### Backend (No build output)

Backend runs directly from source in production container.

## Docker Build

### Build Production Images

```bash
# Build both containers
npm run docker:build

# Or manually
docker compose -f docker-compose.production.yml build
```

**Images created:**
- `pokedex-frontend`: Nginx + built static files
- `pokedex-backend`: Node.js + Express server

### Frontend Dockerfile (`Dockerfile.frontend`)

```dockerfile
FROM nginx:alpine
COPY dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80 443
```

### Backend Dockerfile (`server/Dockerfile`)

```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "oauth-proxy.js"]
```

## Development vs Production

### Development Build

```bash
npm run dev        # Hot reload, no optimization
npm run dev:full   # Frontend + Backend with hot reload
```

**Features:**
- Hot Module Replacement (HMR)
- Fast rebuilds
- Detailed error messages
- No minification
- Source maps enabled

### Production Build

```bash
npm run build           # Full optimization
npm run build:verify    # Validate build
```

**Features:**
- Minified code
- Tree shaking
- Code splitting
- Asset optimization
- Production source maps
- Vendor chunk splitting

## Build Configuration

### Vite Config (`vite.config.js`)

```javascript
build: {
  target: 'es2015',           // Browser compatibility
  minify: 'terser',           // Minifier
  sourcemap: true,            // Source maps
  rollupOptions: {
    output: {
      manualChunks: {         // Chunk splitting
        'vue-vendor': ['vue', 'vue-router'],
        'highlight': ['highlight.js'],
        'virtual-scroller': ['vue-virtual-scroller']
      }
    }
  },
  chunkSizeWarningLimit: 600, // 600KB warning limit
  cssCodeSplit: true,         // Split CSS per chunk
  assetsInlineLimit: 10240    // Inline <10KB assets
}
```

## Troubleshooting

### Build Fails

```bash
# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build
```

### Build Verification Fails

**Missing index.html:**
- Check Vite config
- Verify `index.html` exists in project root

**No JavaScript bundles:**
- Check for build errors
- Verify Vue plugin is configured

**Large bundle warnings:**
- Review `manualChunks` configuration
- Consider lazy loading components
- Check for unnecessary dependencies

### Out of Memory

```bash
# Increase Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" npm run build
```

### Slow Builds

**Solutions:**
- Enable Vite cache
- Reduce bundle size with lazy loading
- Use faster disk (SSD)
- Upgrade Node.js version

## Performance Tips

1. **Lazy Load Routes**: Split Vue Router routes into separate chunks
2. **Optimize Images**: Use WebP format, compress before build
3. **Tree Shaking**: Ensure imports are ES modules
4. **Bundle Analysis**: Use `rollup-plugin-visualizer`
5. **CDN Assets**: Consider CDN for large vendor libraries

## CI/CD Integration

```yaml
# Example GitHub Actions
- name: Install dependencies
  run: npm ci
  
- name: Run tests
  run: npm run test:run
  
- name: Build frontend
  run: npm run build:frontend
  
- name: Verify build
  run: npm run build:verify
  
- name: Build Docker images
  run: npm run docker:build
```

## Environment Variables

### Build-time Variables

No build-time environment variables required for frontend.

### Runtime Variables (Backend)

See `server/.env.example` for required variables:
- `NODE_ENV`
- `PORT`
- `CHALLONGE_CLIENT_ID`
- `CHALLONGE_CLIENT_SECRET`
- `SESSION_SECRET`

## Next Steps

After successful build:

1. **Local Testing**: `npm run docker:up`
2. **Deployment**: `npm run deploy:internal` or `npm run deploy:external`
3. **Monitoring**: Check logs with `npm run docker:logs`