memory-infrastructure-palace/docs/projects/Pokedex.Online/setup/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

# 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

# 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

# Build both frontend and backend
npm run build

# Then verify the build
npm run build:verify

Build Verification

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

# 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)

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)

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

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

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)

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

# 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

# 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

# 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