Build Engineer Skill

Build Engineer

Purpose

Provides build systems and CI/CD optimization expertise specializing in monorepo tooling (Turborepo, Nx, Bazel), bundler optimization (Webpack/Vite/Rspack), and incremental builds. Focuses on optimizing development velocity through caching, parallelization, and build performance.

When to Use

• Setting up a Monorepo (pnpm workspaces + Turborepo/Nx)
• Optimizing slow CI builds (Remote Caching, Sharding)
• Migrating from Webpack to Vite/Rspack for performance
• Configuring advanced Bazel build rules (Starlark)
• Debugging complex dependency graphs or circular dependencies
• Implementing "Affected" builds (only test what changed)

--- ---

2. Decision Framework

Monorepo Tool Selection

Bundler Selection

What is the priority?
│
├─ **Development Speed (HMR)**
│  ├─ Web App? → **Vite** (ESModules based, instant start)
│  └─ Legacy App? → **Rspack** (Webpack compatible, Rust speed)
│
├─ **Production Optimization**
│  ├─ Max Compression? → **Webpack** (Mature ecosystem of plugins)
│  └─ Speed? → **Rspack / Esbuild**
│
└─ **Library Authoring**
   └─ Dual Emit (CJS/ESM)? → **Rollup** (Tree-shaking standard)

Red Flags → Escalate to `devops-engineer`:

• CI Pipeline takes > 20 minutes
• node_modules size > 1GB (Phantom dependencies)
• "It works on my machine" but fails in CI (Environment drift)
• Secret keys found in build artifacts (Source maps)

--- ---

4. Core Workflows

Workflow 1: Turborepo Setup (Remote Caching)

Goal: Reduce CI time by 80% by reusing cache artifacts.

Steps:

1. Configuration (`turbo.json`)

    {
      "$schema": "https://turbo.build/schema.json",
      "pipeline": {
        "build": {
          "dependsOn": ["^build"],
          "outputs": ["dist/**", ".next/**"]
        },
        "test": {
          "dependsOn": ["build"],
          "inputs": ["src/**/*.tsx", "test/**/*.ts"]
        },
        "lint": {}
      }
    }

2. Remote Cache

• Link to Vercel Remote Cache: npx turbo link.
• In CI (GitHub Actions):

        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

3. Execution

• turbo run build test lint
• First run: 5 mins. Second run: 100ms (FULL TURBO).

--- ---

Workflow 3: Nx Affected Commands

Goal: Only run tests for changed projects in a monorepo.

Steps:

1. Analyze Graph

• nx graph (Visualizes dependencies: App A depends on Lib B).

2. CI Pipeline

    # Only test projects affected by PR
    npx nx affected -t test --base=origin/main --head=HEAD
    
    # Only lint affected
    npx nx affected -t lint --base=origin/main

--- ---

Workflow 5: Bazel Concepts for JS Developers

Goal: Understand BUILD files vs package.json.

Mapping:

Code Example (`BUILD.bazel`):

load("@aspect_rules_js//js:defs.bzl", "js_library")

js_library(
    name = "pkg",
    srcs = ["index.js"],
    deps = [
        "//:node_modules/lodash",
        "//libs/utils"
    ],
)

--- ---

5. Anti-Patterns & Gotchas

❌ Anti-Pattern 1: Phantom Dependencies

What it looks like:

• import foo from 'foo' works locally but fails in CI.

Why it fails:

• 'foo' is hoisted by the package manager but not listed in package.json.

Correct approach:

• Use pnpm (Strict mode). It prevents accessing undeclared dependencies via symlinks.

❌ Anti-Pattern 2: Circular Dependencies

What it looks like:

• Lib A imports Lib B. Lib B imports Lib A.
• Build fails with "Maximum call stack exceeded" or "Undefined symbol".

Why it fails:

• Logic error in architecture.

Correct approach:

• Extract Shared Code: Move common logic to Lib C.
• A → C, B → C.
• Use madge tool to detect circular deps: npx madge --circular .

❌ Anti-Pattern 3: Committing node_modules

What it looks like:

• Git repo size is 2GB.

Why it fails:

• Slow clones. Platform specific binaries break.

Correct approach:

• .gitignore must include node_modules/, dist/, .turbo/, .next/.

--- ---

7. Quality Checklist

Performance:

• [ ] Cache: Remote caching enabled and verified (Hit rate > 80%).
• [ ] Parallelism: Tasks run in parallel where possible (Topology aware).
• [ ] Size: Production artifacts minified and tree-shaken.

Reliability:

• [ ] Lockfile: pnpm-lock.yaml / package-lock.json is consistent.
• [ ] CI: Builds pass on clean runner (no cache).
• [ ] Determinism: Same inputs = Same hash.

Maintainability:

• [ ] Scripts: package.json scripts standardized (dev, build, test, lint).
• [ ] Graph: Dependency graph is acyclic (DAG).
• [ ] Scaffolding: Generators set up for new libraries/apps.

Examples

Example 1: Enterprise Monorepo Migration

Scenario: A 500-developer company with 4 React applications and 15 shared libraries wants to migrate from separate repos to a monorepo to improve code sharing and CI efficiency.

Migration Approach: 1. Tool Selection: Chose Nx for enterprise features and graph visualization 2. Dependency Mapping: Used madge to visualize current dependencies between projects 3. Module Boundaries: Defined clear layers (ui, utils, data-access, features) 4. Build Optimization: Configured remote caching with Nx Cloud

Migration Results:

• CI build time reduced from 45 minutes to 8 minutes (82% improvement)
• Code duplication reduced by 60% through shared libraries
• Affected builds only test changed projects (often under 1 minute)
• Clear architectural boundaries enforced by Nx project inference

Example 2: Webpack to Rspack Migration

Scenario: A large e-commerce platform has slow production builds (12 minutes) due to complex Webpack configuration and wants to improve developer experience.

Migration Strategy: 1. Incremental Migration: Started with development builds, kept Webpack for production temporarily 2. Config Translation: Mapped Webpack loaders to Rspack equivalents 3. Plugin Compatibility: Used rspack-plugins for webpack-compatible plugins 4. Verification: Ran parallel builds to verify output equivalence

Performance Comparison:

Example 3: Distributed CI Pipeline with Sharding

Scenario: A gaming company with 5,000 E2E tests needs to reduce CI time from 90 minutes to under 15 minutes for fast feedback.

Pipeline Design: 1. Test Analysis: Categorized tests by duration and parallelism potential 2. Shard Strategy: Split tests into 20 shards, each running ~250 tests 3. Smart Scheduling: Used Nx affected to only run tests for changed features 4. Resource Optimization: Configured auto-scaling runners for parallel execution

CI Pipeline Configuration:

# GitHub Actions with Playwright sharding
- name: Run E2E Tests
  run: |
    npx playwright test --shard=${{ matrix.shard }}/${{ matrix.total }} \
      --config=playwright.config.ts
  strategy:
    matrix:
      shard: [1, 2, ..., 20]
    max-parallel: 10

Results:

• E2E test time: 90m → 12m (87% improvement)
• Developer feedback loop under 15 minutes
• Reduced cloud CI costs by 30% through better parallelism

Best Practices

Monorepo Architecture

• Define Clear Boundaries: Establish and enforce project boundaries from day one
• Use Strict Dependency Rules: Prevent circular dependencies and enforce directionality
• Automate Project Creation: Use generators for consistent new project setup
• Version Packages Together: Use Changesets or Lerna for coordinated releases
• Document Dependencies: Maintain architecture decision records for changes

Build Performance

• Profile Before Optimizing: Use tools like speed-measure-webpack-plugin to identify bottlenecks
• Incremental Builds: Configure build tools to only rebuild what's necessary
• Parallel Execution: Use available CPU cores for parallel task execution
• Caching Strategies: Implement aggressive caching at every layer
• Dependency Optimization: Prune unused dependencies regularly (bundlephobia)

CI/CD Excellence

• Fail Fast: Order tests to run fast tests first, catch failures quickly
• Sharding Strategy: Distribute tests across multiple runners intelligently
• Cache Everything: Dependencies, build outputs, test results
• Conditional Execution: Only run jobs that are affected by the change
• Pipeline as Code: Version control CI configuration alongside code

Tool Selection

• Match Tool to Ecosystem: Don't force tools that don't fit your stack
• Evaluate Migration Cost: Consider total cost, not just performance gains
• Community Health: Choose tools with active maintenance and community support
• Plugin Ecosystem: Ensure required integrations are available
• Team Familiarity: Consider learning curve and team adoption

Security and Compliance

• Secret Scanning: Never commit secrets; use automated scanning
• Dependency Auditing: Regular vulnerability scans with automated fixes
• Access Control: Limit CI credentials to minimum required permissions
• Build Reproducibility: Ensure builds can be reproduced from source
• Audit Logging: Maintain logs of all build and deployment activities

Build Engineer - Best Practices

This guide outlines best practices for build system configuration, optimization, code splitting, and deployment.

Core Principles

Fast Builds

• Enable caching (file system, Babel cache, persistent cache)
• Use parallel processing where possible
• Optimize build configuration for minimal overhead
• Use modern, fast bundlers (Vite, esbuild, Turbopack)
• Monitor build times and optimize bottlenecks

Small Bundles

• Implement code splitting strategies
• Tree shake unused code
• Compress output (minification, gzip, brotli)
• Use dynamic imports for lazy loading
• Analyze bundle sizes regularly
• Remove unused dependencies

Developer Experience

• Fast HMR (Hot Module Replacement)
• Clear error messages with source maps
• Easy local development setup
• Proxy configuration for API calls
• Environment variable management
• Source map generation for debugging

Build Tool Selection

Tool Comparison

When to Use Each

• Webpack: Complex enterprise applications, legacy migrations
• Vite: Modern web apps, Vue/React projects, DX priority
• esbuild: Production builds, performance-critical, simple setups
• Turbopack: New projects, performance experimentation, early adopters
• Rollup: Library/package development, tree shaking focus
• Parcel: Quick prototypes, learning projects, zero-config needs

Webpack Configuration

Optimizations

Performance

module.exports = {
  cache: {
    type: 'filesystem',
    cacheDirectory: '.webpack_cache',
  },
  parallelism: true, // Use all CPU cores
  stats: {
    preset: 'minimal', // Reduce output
  },
}

Code Splitting

module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          priority: 10,
        },
        common: {
          minChunks: 2,
          priority: 5,
          reuseExistingChunk: true,
        },
      },
    },
  },
}

Loaders

module.exports = {
  module: {
    rules: [
      {
        test: /\.(ts|tsx)$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
}

Vite Configuration

Optimizations

Build Options

export default defineConfig({
  build: {
    minify: 'terser',
    sourcemap: false,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        },
      },
    },
  },
})

Performance

export default defineConfig({
  optimizeDeps: {
    include: ['react', 'react-dom'],
  },
  server: {
    hmr: {
      overlay: true,
    },
  },
})

Plugins

import react from '@vitejs/plugin-react';
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    react(),
    visualizer({
      open: false,
      gzipSize: true,
    }),
  ],
})

Code Splitting Strategies

Route-Based Splitting

• Lazy load route components
• Use React.lazy() or similar
• Benefits: Faster initial load, parallel downloads

const Home = lazy(() => import('./pages/Home'));
const Dashboard = lazy(() => import('./pages/Dashboard'));

Component-Based Splitting

• Lazy load heavy components
• Use dynamic imports
• Benefits: Load components on demand

const HeavyChart = lazy(() => import('./components/HeavyChart'));

Vendor Splitting

• Separate third-party libraries
• Cache vendor chunks separately
• Benefits: Better caching, faster rebuilds

// Webpack
splitChunks: {
  cacheGroups: {
    vendor: {
      test: /[\\/]node_modules[\\/]/,
      name: 'vendors',
    },
  },
}

Library Splitting

• Split large libraries (React, Vue, etc.)
• Load from CDN when possible
• Benefits: Smaller bundle, CDN caching

Caching Strategies

Webpack Caching

File System Cache

module.exports = {
  cache: {
    type: 'filesystem',
    cacheDirectory: '.webpack_cache',
    maxAge: 604800000, // 1 week
  },
}

Babel Cache

{
  test: /\.(js|jsx)$/,
  use: {
    loader: 'babel-loader',
    options: {
      cacheDirectory: true,
    },
  },
}

Vite Caching

export default defineConfig({
  cacheDir: './node_modules/.vite',
  optimizeDeps: {
    force: false, // Only re-optimizes on change
  },
})

Persistent Cache

• Use browser caching headers
• Implement service workers
• Use CDN caching for static assets
• Set appropriate cache timeouts
• Cache bust with content hash

Production Optimization

Minification

• Use Terser for JavaScript minification
• Use cssnano for CSS optimization
• Enable dead code elimination
• Remove console.log in production
• Minify HTML with html-minifier

Asset Optimization

• Compress images (ImageMin, imagemin)
• Use modern image formats (WebP, AVIF)
• SVG optimization (svgo)
• Font subsetting
• Inline small assets when beneficial

Bundle Analysis

• Use webpack-bundle-analyzer
• Use rollup-plugin-visualizer for Vite
• Analyze bundle size composition
• Identify large dependencies
• Find optimization opportunities

const BundleAnalyzerPlugin = require('webpack-bundle-analyzer');

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: 'static',
      openAnalyzer: false,
    }),
  ],
}

Development Experience

Hot Module Replacement (HMR)

• Enable HMR for fast feedback
• Preserve state during HMR when possible
• Use overlay for build errors
• Configure HMR timeout appropriately
• Handle HMR errors gracefully

Dev Server Configuration

// Webpack
devServer: {
  port: 3000,
  hot: true,
  open: false,
  proxy: {
    '/api': {
      target: 'http://localhost:4000',
      changeOrigin: true,
    },
  },
}

// Vite
server: {
  port: 3000,
  open: false,
  proxy: {
    '/api': {
      target: 'http://localhost:4000',
      changeOrigin: true,
    },
  },
}

Source Maps

• Use source-map for production
• Use eval-source-map for development
• Exclude source maps from production bundle
• Configure source map hosting
• Consider security implications

Performance Monitoring

Build Time Monitoring

• Track build time in CI/CD
• Alert on build time degradation
• Optimize slow build steps
• Cache dependencies to reduce build time
• Monitor for build time regressions

Bundle Size Monitoring

• Track bundle sizes over time
• Alert on size increases
• Set size budgets in config
• Monitor individual chunk sizes
• Track total bundle size

Runtime Performance

• Monitor Time to Interactive (TTI)
• Track Lighthouse scores
• Monitor Core Web Vitals
• Track JavaScript execution time
• Monitor bundle parse time

Dependency Management

Dependency Auditing

# Check for vulnerabilities
npm audit

# Fix vulnerabilities
npm audit fix

# Check outdated packages
npm outdated

# Update packages
npm update

Dependency Optimization

• Remove unused dependencies
• Use smaller alternatives when possible
• Bundle critical dependencies
• Use tree shaking for conditional imports
• Consider CDN for large libraries

Environment Configuration

Environment Variables

• Use .env files for local development
• Load environment variables in build
• Document required variables
• Validate configuration on startup
• Never commit .env files

Multi-Environment Configs

// webpack.config.js
const isProduction = process.env.NODE_ENV === 'production';

module.exports = {
  mode: isProduction ? 'production' : 'development',
  // Environment-specific config
};

Testing Build Configs

Configuration Validation

• Test config in multiple environments
• Verify all plugins load correctly
• Check loaders resolve files
• Test with sample files
• Validate source map generation

Build Testing

• Test production build locally
• Verify all assets are generated
• Test in staging environment
• Test with real user data
• Verify CDN uploads work

CI/CD Integration

Build Caching

# GitHub Actions example
- name: Cache node modules
  uses: actions/cache@v2
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

Parallel Builds

• Run test and build in parallel
• Use matrix builds for multiple configurations
• Split long builds into stages
• Use build artifacts between stages

Deployment Automation

• Automated deployment on successful build
• Rollback on deployment failure
• Blue-green deployment strategy
• Canary releases for gradual rollout
• Health checks before routing traffic

Security Best Practices

Source Map Security

• Don't expose full source maps in production
• Upload source maps to error tracking services
• Use hidden source maps when needed
• Consider security implications

Dependency Security

• Regularly audit dependencies
• Fix vulnerabilities promptly
• Review licenses of dependencies
• Use Snyk or Dependabot for alerts
• Patch dependencies automatically in CI/CD

Build Environment Security

• Use isolated build environments
• Don't expose secrets in build output
• Sanitize environment variables
• Use secure artifact storage
• Verify no secrets in bundles

Documentation

Build Documentation

• Document build configuration decisions
• Explain complex optimizations
• Document dependency rationale
• Include troubleshooting steps
• Document environment requirements

README for Build

• Quick start guide for building
• Development workflow
• Production build instructions
• Common issues and solutions
• Environment variable documentation
• Deployment instructions

Troubleshooting Build Issues

Common Patterns

• Slow builds: Enable caching, check for unnecessary plugins
• Large bundles: Analyze with bundle analyzer, implement splitting
• HMR not working: Check WebSockets, verify config
• Caching issues: Clear cache, verify permissions
• Source maps: Verify generation, check paths
• Proxy issues: Check backend is running, verify CORS

Debug Tools

• Use --display-modules for Webpack
• Use bundle analyzer for Vite
• Check webpack stats for insights
• Use browser DevTools for runtime debugging
• Monitor network tab for asset loading

Continuous Improvement

Regular Review

• Review bundle sizes weekly
• Analyze build times monthly
• Review dependency updates quarterly
• Update tools and plugins regularly
• Monitor for new optimization techniques

Performance Budgets

// webpack.config.js
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      defaultSizes: 'gzip',
      analyzerMode: 'static',
      generateStatsFile: true,
      statsOptions: { source: false },
    }),
  ],
  performance: {
    hints: false,
    maxEntrypointSize: 512000, // 500 KB
    maxAssetSize: 512000, // 500 KB
  },
}

Learning from Errors

• Document build errors and solutions
• Create internal knowledge base
• Share solutions with team
• Update scripts based on common issues
• Contribute back to tool communities

Bundler Guide

Overview

Modern web applications use bundlers to transform, optimize, and bundle source code for browser consumption. This guide covers major bundlers and their configurations.

Webpack

Basic Configuration

const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  mode: 'production',
};

Loaders

module.exports = {
  module: {
    rules: [
      // JavaScript/TypeScript
      {
        test: /\.(ts|tsx|js|jsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              '@babel/preset-env',
              '@babel/preset-react',
              '@babel/preset-typescript',
            ],
          },
        },
      },
      
      // CSS
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
      
      // Images
      {
        test: /\.(png|jpe?g|gif|svg)$/,
        type: 'asset/resource',
      },
      
      // Fonts
      {
        test: /\.(woff|woff2|eot|ttf|otf)$/,
        type: 'asset/resource',
      },
    ],
  },
};

Plugins

const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const CleanWebpackPlugin = require('clean-webpack-plugin');

module.exports = {
  plugins: [
    new CleanWebpackPlugin(),
    
    new HtmlWebpackPlugin({
      template: './public/index.html',
      filename: 'index.html',
      minify: true,
    }),
    
    new MiniCssExtractPlugin({
      filename: '[name].[contenthash].css',
      chunkFilename: '[name].[contenthash].css',
    }),
  ],
};

Optimization

const TerserPlugin = require('terser-webpack-plugin');
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          compress: {
            drop_console: true,
          },
        },
      }),
      new CssMinimizerPlugin(),
    ],
    
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
        },
      },
    },
    
    runtimeChunk: 'single',
  },
};

Vite

Configuration

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

export default defineConfig({
  plugins: [react()],
  
  resolve: {
    alias: {
      '@': '/src',
    },
  },
  
  build: {
    outDir: 'dist',
    sourcemap: true,
    
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
        },
      },
    },
  },
  
  server: {
    port: 3000,
    open: true,
  },
});

Plugins

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import eslint from 'vite-plugin-eslint';
import svgr from 'vite-plugin-svgr';

export default defineConfig({
  plugins: [
    react(),
    eslint(),
    svgr(),
  ],
});

Environment Variables

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify(process.env.npm_package_version),
    __API_URL__: JSON.stringify(process.env.VITE_API_URL),
  },
});

esbuild

Basic Usage

const esbuild = require('esbuild');

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  minify: true,
  sourcemap: true,
  target: 'es2015',
});

Watch Mode

esbuild.context({
  entryPoints: ['src/index.js'],
  outfile: 'dist/bundle.js',
  bundle: true,
}).then(ctx => {
  ctx.watch();
});

Turbopack

Configuration

module.exports = {
  experimental: {
    turbo: {},
  },
};

Development Server

const { createServer } = require('turbo');

createServer({
  entry: './src/index.js',
  dev: true,
  hmr: true,
});

Comparison

When to Use Which

Webpack

• Maximum configurability needed
• Advanced optimization required
• Legacy browser support
• Large enterprise applications

Vite

• Modern browser support
• Fast development experience
• TypeScript-first
• React/Vue/Svelte projects

esbuild

• Maximum build speed
• Simple projects
• Minimal dependencies
• Build-time transformation only

Turbopack

• Next.js projects
• Maximum performance
• React-based applications
• Want to stay bleeding-edge

Best Practices

Performance

// Enable persistent cache
module.exports = {
  cache: {
    type: 'filesystem',
    cacheDirectory: '.webpack_cache',
  },
};

Bundle Size

// Analyze bundle size
const BundleAnalyzerPlugin = require('webpack-bundle-analyzer');

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: 'static',
      openAnalyzer: false,
    }),
  ],
};

Development

// Fast rebuilds
module.exports = {
  devtool: 'eval-cheap-module-source-map',
  cache: true,
};

Production

// Optimize for production
module.exports = {
  mode: 'production',
  optimization: {
    minimize: true,
    usedExports: true,
    sideEffects: true,
  },
};

Framework Selection Guide

Overview

Choosing the right build tool/framework is crucial for project success. This guide helps you make informed decisions based on project requirements.

Decision Matrix

Project Size

Small Projects (< 10 files, < 5 dependencies)

• Vite - Fastest setup, minimal configuration
• esbuild - Simplest, no build system needed
• Rollup - Great for libraries

Medium Projects (10-100 files, 5-20 dependencies)

• Vite - Excellent DX, fast HMR
• Webpack - More control if needed
• Parcel - Zero config

Large Projects (100+ files, 20+ dependencies)

• Webpack - Maximum control and optimization
• Vite - Still good, may need plugins
• Turbopack - For Next.js projects

Team Size

Solo Developer

• Vite - Simple and fast
• esbuild - Minimal setup
• Parcel - Zero config

Small Team (2-5 developers)

• Vite - Good documentation, easy onboarding
• Webpack - Well-documented, widely used
• Parcel - Easy setup, less maintenance

Large Team (5+ developers)

• Webpack - Standard in industry, lots of resources
• Vite - Growing ecosystem
• Turbopack - Latest tech, may be experimental

Requirements

Fast Development

1. Vite - Instant HMR 2. esbuild - Fastest builds 3. Turbopack - Blazing fast

Maximum Optimization

1. Webpack - Most options 2. Rollup - Great tree shaking 3. Terser - Best minification

Legacy Browser Support

1. Webpack + Babel - Most control 2. Rollup + Babel - Good for libraries 3. Parcel - Handles automatically

TypeScript Support

1. Vite - Native support 2. esbuild - Native support 3. Turbopack - Native support

Tool Comparison

Webpack

Pros:

• Extensive plugin ecosystem
• Maximum configurability
• Industry standard
• Advanced optimization
• Great documentation

Cons:

• Slow builds
• Complex configuration
• Steep learning curve
• Can be overkill for small projects

Best For:

• Large enterprise applications
• Advanced optimization needs
• Legacy browser support
• Custom build pipelines

Vite

Pros:

• Extremely fast HMR
• Simple configuration
• Native TypeScript support
• Excellent DX
• Growing ecosystem

Cons:

• Smaller plugin ecosystem than Webpack
• Less mature than Webpack
• Limited advanced features

Best For:

• Modern web apps
• React/Vue/Svelte projects
• Fast development cycles
• Small to medium teams

esbuild

Pros:

• Extremely fast (10-100x faster)
• Simple API
• Native TypeScript
• No dependencies
• Great for libraries

Cons:

• Limited plugin support
• Less mature
• Minimal configuration
• Not a full bundler for complex apps

Best For:

• Build tools
• CLI tools
• Simple apps
• Performance-critical builds

Turbopack

Pros:

• Extremely fast
• Rust-based
• Next.js integration
• Modern architecture

Cons:

• Very new (beta)
• Limited ecosystem
• Experimental features
• Limited documentation

Best For:

• Next.js projects
• Early adopters
• Performance-critical apps
• React projects

Rollup

Pros:

• Excellent tree shaking
• Great for libraries
• Simple API
• Good plugin support

Cons:

• Not for complex apps
• Limited HMR
• More config than Vite
• Slower than esbuild

Best For:

• Library development
• Component libraries
• npm packages
• Simple bundles

Parcel

Pros:

• Zero config
• Fast builds
• Automatic optimization
• Great for small teams

Cons:

• Less control
• Plugin limitations
• Smaller ecosystem
• Harder to debug

Best For:

• Prototypes
• Small projects
• Less technical teams
• Rapid development

Recommendations by Use Case

Single Page Applications

React: 1. Vite (recommended) 2. Webpack Create React App 3. Next.js (SSR)

Vue: 1. Vite (recommended) 2. Vue CLI (Webpack) 3. Nuxt (SSR)

Svelte: 1. Vite (recommended) 2. SvelteKit (SSR)

Angular: 1. Angular CLI (Webpack) 2. Nx (Webpack/Turbo)

Static Site Generation

Next Best: 1. Next.js (React) 2. Nuxt (Vue) 3. SvelteKit (Svelte) 4. Gatsby (React)

Good Options: 1. Vite + Vitepress 2. Docusaurus 3. Astro

Component Libraries

Recommended: 1. Rollup 2. Vite library mode 3. esbuild

Micro-frontends

Recommended: 1. Webpack Module Federation 2. Single-spa 3. Qiankun

Node.js Applications

Recommended: 1. esbuild 2. ts-node (development) 3. swc (development)

Migration Guides

Webpack to Vite

// Before (webpack.config.js)
module.exports = {
  entry: './src/index.js',
  output: { filename: 'bundle.js' },
};

// After (vite.config.ts)
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    outDir: 'dist',
  },
});

Webpack to esbuild

// Before (webpack.config.js)
module.exports = {
  entry: './src/index.js',
  output: { filename: 'bundle.js' },
};

// After (esbuild.js)
const esbuild = require('esbuild');

esbuild.build({
  entryPoints: ['src/index.js'],
  outfile: 'dist/bundle.js',
  bundle: true,
});

Performance Benchmarks

Build Time (Cold Build)

• esbuild: ~100ms (small project)
• Vite: ~500ms (small project)
• Webpack: ~2s (small project)
• Turbopack: ~50ms (small project)

HMR Time

• Vite: ~50ms
• Webpack: ~500ms
• Turbopack: ~10ms

Bundle Size

All bundlers can produce similar sizes with proper optimization. Differences come from:

• Code splitting strategy
• Tree shaking effectiveness
• Compression settings
• Source map configuration

Checklist for Selection

Requirements Assessment

• [ ] Project size and complexity
• [ ] Team size and expertise
• [ ] Performance requirements
• [ ] Browser support needs
• [ ] TypeScript requirements
• [ ] Build tooling needs
• [ ] Deployment constraints
• [ ] Budget limitations

Technical Considerations

• [ ] Learning curve
• [ ] Ecosystem maturity
• [ ] Documentation quality
• [ ] Community support
• [ ] Plugin availability
• [ ] Integration with other tools
• [ ] Long-term maintenance

Business Considerations

• [ ] Time to market
• [ ] Developer productivity
• [ ] Hiring ease
• [ ] Skill availability
• [ ] Vendor lock-in risk
• [ ] Future-proofing

Final Recommendations

Default Choice: Vite

• Fast development experience
• Simple configuration
• Modern tooling
• Growing ecosystem
• Good documentation

Complex Enterprise: Webpack

• Maximum control
• Extensive plugins
• Industry standard
• Advanced optimization
• Well-documented

Maximum Performance: esbuild

• Blazing fast builds
• Simple API
• Zero dependencies
• Great for libraries

Next.js Projects: Turbopack

• Native integration
• Cutting-edge performance
• Future-proof
• Active development

Conservative Choice: Rollup

• Stable and mature
• Great for libraries
• Excellent tree shaking
• Well-documented

Build Optimization Strategies

Overview

Build optimization is crucial for delivering fast, efficient web applications. This guide covers comprehensive optimization strategies across the build pipeline.

Code Splitting

Route-based Splitting

import { lazy, Suspense } from 'react';

const Home = lazy(() => import('./pages/Home'));
const Dashboard = lazy(() => import('./pages/Dashboard'));

export const App = () => (
  <Suspense fallback={<Loading />}>
    <Routes>
      <Route path="/" element={<Home />} />
      <Route path="/dashboard" element={<Dashboard />} />
    </Routes>
  </Suspense>
);

Component-based Splitting

import { lazy, Suspense } from 'react';

const HeavyChart = lazy(() => import('./HeavyChart'));

export const Dashboard = () => {
  const [showChart, setShowChart] = useState(false);

  return (
    <div>
      <button onClick={() => setShowChart(true)}>
        Show Chart
      </button>
      {showChart && (
        <Suspense fallback={<Loading />}>
          <HeavyChart />
        </Suspense>
      )}
    </div>
  );
};

Vendor Splitting

// webpack.config.js
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          priority: 10,
        },
      },
    },
  },
};

Tree Shaking

ES Modules

//GOOD - ES modules
export { func1, func2 } from './utils';

// BAD - CommonJS
module.exports = { func1, func2 };

Package.json Side Effects

{
  "sideEffects": false,
  "sideEffects": ["*.css", "./src/**/*.scss"]
}

Webpack Configuration

module.exports = {
  optimization: {
    usedExports: true,
    sideEffects: true,
  },
};

Minification

JavaScript

// Terser configuration
const TerserPlugin = require('terser-webpack-plugin');

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          compress: {
            drop_console: true,
            pure_funcs: ['console.log'],
            dead_code: true,
            unused: true,
          },
          mangle: {
            safari10: true,
          },
        },
      }),
    ],
  },
};

CSS

// CSS Nano configuration
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');

module.exports = {
  optimization: {
    minimizer: [
      new CssMinimizerPlugin({
        minimizerOptions: {
          preset: [
            'default',
            {
              discardComments: { removeAll: true },
              normalizeWhitespace: true,
              minifyFontValues: true,
            },
          ],
        },
      }),
    ],
  },
};

HTML

const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  plugins: [
    new HtmlWebpackPlugin({
      minify: {
        removeComments: true,
        collapseWhitespace: true,
        removeAttributeQuotes: true,
        minifyJS: true,
        minifyCSS: true,
      },
    }),
  ],
};

Bundle Analysis

Webpack Bundle Analyzer

const BundleAnalyzerPlugin = require('webpack-bundle-analyzer');

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: 'static',
      openAnalyzer: false,
      generateStatsFile: true,
      statsFilename: 'bundle-stats.json',
    }),
  ],
};

Source Map Explorer

npm run build
npm run build:analyze

Asset Optimization

Images

const ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|gif|svg)$/i,
        type: 'asset',
        parser: {
          dataUrlCondition: {
            maxSize: 8 * 1024,
          },
        },
        generator: {
          filename: 'images/[name].[contenthash][ext]',
        },
        use: [
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              minimizer: {
                implementation: ImageMinimizerPlugin.imageminGenerate,
                options: {
                  plugins: [
                    ['imagemin-mozjpeg', { quality: 75 }],
                    ['imagemin-pngquant', { quality: [0.65, 0.9] }],
                  ],
                },
              },
            },
          },
        ],
      },
    ],
  },
};

Fonts

module.exports = {
  module: {
    rules: [
      {
        test: /\.(woff|woff2|eot|ttf|otf)$/,
        type: 'asset/resource',
        generator: {
          filename: 'fonts/[name][ext]',
        },
      },
    ],
  },
};

SVG Optimization

const SvgrWebpackPlugin = require('svg-sprite-loader');

module.exports = {
  module: {
    rules: [
      {
        test: /\.svg$/,
        use: ['@svgr/webpack'],
      },
    ],
  },
};

Caching

File System Cache

module.exports = {
  cache: {
    type: 'filesystem',
    cacheDirectory: '.webpack_cache',
    maxAge: 1000 * 60 * 60 * 24 * 7, // 1 week
    compression: 'gzip',
  },
};

Babel Cache

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        use: {
          loader: 'babel-loader',
          options: {
            cacheDirectory: true,
            cacheCompression: true,
          },
        },
      },
    ],
  },
};

Persistent Build

module.exports = {
  snapshot: {
    managedPaths: [path.join(process.cwd(), 'node_modules')],
    immutablePaths: [],
    buildDependencies: {
      config: [__filename],
    },
  },
};

Performance Monitoring

Build Metrics

const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      analyzerMode: 'static',
      reportFilename: './bundle-report.html',
      generateStatsFile: true,
      statsOptions: { source: false },
    }),
  ],
};

Lighthouse CI

# .github/workflows/lighthouse.yml
name: Lighthouse CI

on: [push]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run Lighthouse CI
        uses: treosh/lighthouse-ci-action@v3
        with:
          urls: |
            https://example.com
          uploadArtifacts: true
          temporaryPublicStorage: true

Environment-specific Optimization

Development

module.exports = {
  mode: 'development',
  devtool: 'eval-cheap-module-source-map',
  
  optimization: {
    runtimeChunk: true,
    removeAvailableModules: false,
    removeEmptyChunks: false,
    splitChunks: false,
  },
  
  cache: {
    type: 'memory',
  },
};

Production

module.exports = {
  mode: 'production',
  devtool: 'source-map',
  
  optimization: {
    minimize: true,
    nodeEnv: 'production',
    
    splitChunks: {
      chunks: 'all',
      maxInitialRequests: 25,
      minSize: 20000,
    },
    
    runtimeChunk: 'single',
  },
  
  performance: {
    hints: 'warning',
    maxEntrypointSize: 512000,
    maxAssetSize: 512000,
  },
};

Advanced Strategies

DLL Plugin for Dependencies

const webpack = require('webpack');
const path = require('path');

module.exports = {
  entry: {
    vendor: ['react', 'react-dom', 'react-router-dom'],
  },
  output: {
    path: path.join(__dirname, 'dll'),
    filename: '[name].dll.js',
    library: '[name]_library',
  },
  plugins: [
    new webpack.DllPlugin({
      name: '[name]_library',
      path: path.join(__dirname, 'dll', '[name]-manifest.json'),
    }),
  ],
};

Module Federation

const ModuleFederationPlugin = require('webpack').container
  .ModuleFederationPlugin;

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'app1',
      filename: 'remoteEntry.js',
      exposes: {
        './Button': './src/Button',
      },
      shared: {
        react: { singleton: true, eager: true },
        'react-dom': { singleton: true, eager: true },
      },
    }),
  ],
};

Preloading & Prefetching

// Preload critical resources
<link rel="preload" href="/styles/main.css" as="style">
<link rel="preload" href="/fonts/main.woff2" as="font" crossorigin>

// Prefetch likely next navigation
<link rel="prefetch" href="/about.js">
<link rel="prefetch" href="/dashboard.js">

Checklist

Pre-build

• [ ] Analyze bundle size
• [ ] Identify unused code
• [ ] Review dependencies
• [ ] Set up code splitting strategy
• [ ] Configure compression

During Build

• [ ] Enable minification
• [ ] Configure source maps
• [ ] Set up caching
• [ ] Enable tree shaking
• [ ] Optimize assets

Post-build

• [ ] Review bundle reports
• [ ] Test loading performance
• [ ] Verify source maps work
• [ ] Check Lighthouse scores
• [ ] Monitor production metrics

Continuous

• [ ] Track bundle size over time
• [ ] Monitor build times
• [ ] Review Lighthouse CI results
• [ ] Update dependencies regularly
• [ ] Review optimization strategies

Build Engineer - Troubleshooting

This guide helps troubleshoot common issues when using build engineer automation scripts.

Script Execution Issues

Python Scripts Not Found

Problem: python scripts/config_webpack.py returns "No such file or directory"

Solutions:

• Verify you're in the correct directory: cd build-engineer-skill
• Check scripts directory exists: ls scripts/
• Ensure Python 3.7+ is installed: python --version

Missing Dependencies

Problem: ModuleNotFoundError: No module named 'xxx'

Solutions:

• Install required Python dependencies
• Install Node.js packages if needed: npm install
• Check package.json for required dependencies
• Review error messages for missing modules

Permission Denied

Problem: PermissionError: [Errno 13] Permission denied when writing output files

Solutions:

• Check directory permissions: ls -la scripts/
• Make scripts executable: chmod +x scripts/*.py
• Verify write permissions for output directory
• Use sudo if necessary (not recommended)

Webpack Configuration Issues

Webpack Config Not Generated

Problem: Webpack configuration file not created

Solutions:

• Verify output directory exists: mkdir -p dist or use --output .
• Check write permissions for output directory
• Review script error messages for specific failures
• Use absolute path for output if relative fails

Entry Point Not Found

Problem: Entry module not found

Solutions:

• Verify entry file exists: src/index.tsx or similar
• Check entry point is correct for your project
• Use --language flag to match entry file extension
• Verify project structure matches expected layout

Loader/Plugin Errors

Problem: Cannot resolve loader or plugin

Solutions:

• Install missing loader: npm install ts-loader css-loader
• Install missing plugin: npm install html-webpack-plugin
• Verify loader/plugin is compatible with Webpack version
• Check webpack.config.js for correct syntax

Vite Configuration Issues

Vite Config Not Generated

Problem: Vite configuration file not created

Solutions:

• Verify output directory exists
• Check write permissions
• Review script error messages
• Use absolute path for output if needed

Framework Plugin Issues

Problem: Framework plugin not working

Solutions:

• Install framework plugin: npm install @vitejs/plugin-react
• Verify framework in config matches installed: --framework react requires React plugin
• Check plugin configuration in generated vite.config.ts
• Review Vite documentation for framework-specific setup

Alias Resolution Fails

Problem: Imports using aliases not resolving

Solutions:

• Verify alias is configured in vite.config.ts or webpack.config.js
• Check alias target paths exist
• Use absolute paths for alias targets
• Review resolve configuration

Code Splitting Issues

Splitting Not Working

Problem: Code not being split as expected

Solutions:

• Verify splitting type is correct: route, component, webpack, vite, all
• Check for lazy loading in your code
• Verify dynamic imports are used
• Review splitting configuration in generated config

Import Errors After Splitting

Problem: Cannot find module after code splitting

Solutions:

• Check chunk names in config
• Verify publicPath configuration
• Review import statements for dynamic imports
• Check for circular dependencies

Large Chunk Sizes

Problem: Individual chunks still too large

Solutions:

• Review vendor chunk configuration
• Check for common chunks configuration
• Analyze bundle with bundle analyzer
• Implement additional splitting strategies

Caching Issues

Cache Not Working

Problem: Rebuilds are not faster

Solutions:

• Verify cache directory is writable
• Check cache configuration in config
• Use --loader flag for Babel cache
• Verify Webpack file system cache is enabled
• Check for cache conflicts between projects

Cache Corruption

Problem: Builds fail with cache errors

Solutions:

• Clear cache directory: rm -rf node_modules/.cache or rm -rf .webpack_cache
• Clear browser cache for dev server
• Rebuild without cache
• Disable cache temporarily to test

Dev Server Issues

Port Already in Use

Problem: Error: Port 3000 already in use

Solutions:

• Find process using port:
• Mac/Linux: lsof -i :3000
• Windows: netstat -ano | findstr :3000
• Kill process: kill -9 <PID>
• Use different port: --port 3001
• Wait for previous process to finish

HMR Not Working

Problem: Changes not reflecting automatically

Solutions:

• Verify HMR is enabled in config
• Check WebSocket connections are not blocked
• Review firewall settings
• Check for HMR errors in browser console
• Restart dev server if issues persist

Proxy Configuration Fails

Problem: Proxy to backend not working

Solutions:

• Verify proxy target URL is correct
• Check backend is running and accessible
• Review proxy configuration in dev server config
• Check for CORS issues
• Test proxy with curl command

Production Build Issues

Build Fails

Problem: Production build returns errors

Solutions:

• Check for TypeScript/ESLint errors
• Review error messages in build output
• Check for missing dependencies
• Verify all imports resolve correctly
• Test in development environment first

Build Too Slow

Problem: Production builds take very long time

Solutions:

• Enable caching (file system, Babel cache)
• Use thread-loader or parallel-webpack for parallelism
• Check for excessive source map generation
• Reduce number of plugins
• Consider using esbuild or swc for faster builds

Large Bundle Size

Problem: Final bundle is too large

Solutions:

• Analyze bundle with bundle analyzer
• Implement code splitting
• Tree shake unused code
• Compress output (minification, gzip)
• Use dynamic imports for lazy loading
• Review and remove large dependencies

Common Issues Across All Scripts

Node.js Version Issues

Problem: Scripts fail due to Node.js version

Solutions:

• Check Node.js version: node --version
• Use nvm to switch Node versions: nvm use 16
• Install required Node version if needed
• Review package.json for version requirements

TypeScript Compilation Errors

Problem: TypeScript fails to compile

Solutions:

• Check tsconfig.json configuration
• Verify @types packages are installed
• Review type errors in compilation output
• Use any type temporarily (not recommended for production)
• Check for circular type references

CSS Module Issues

Problem: CSS imports failing

Solutions:

• Configure CSS loaders correctly
• Install required CSS loader: npm install css-loader style-loader
• Check for CSS syntax errors
• Verify CSS file paths are correct
• Review webpack.config.js for CSS rules

Framework-Specific Issues

React

• Ensure React is installed: npm install react react-dom
• Check JSX transformation is configured
• Verify @types/react is installed for TypeScript
• Review React-specific loader configuration

Vue

• Install Vue loader: npm install vue-loader
• Configure Vue-specific rules in webpack
• Check .vue file extension is handled
• Verify Vue template compiler is installed

Angular

• Use Angular CLI for new projects
• Check for @angular/compiler-cli
• Review Angular webpack configuration
• Verify RxJS and zone.js are installed

Debug Mode

Verbose Output

# Get detailed build information
npm run build --verbose

Source Maps

# Generate source maps for debugging
# In webpack.config.js
devtool: 'source-map'

# In vite.config.ts
build: {
  sourcemap: true
}

Build Analysis

# Analyze bundle size
npm run build -- --analyze

# Or use webpack-bundle-analyzer
npm install --save-dev webpack-bundle-analyzer

Getting Help

Script Help

# Get help for any script
python scripts/config_webpack.py --help
python scripts/config_vite.py --help

Framework Documentation

• Webpack: https://webpack.js.org/
• Vite: https://vitejs.dev/
• esbuild: https://esbuild.github.io/
• Rollup: https://rollupjs.org/

Community Resources

• Stack Overflow: Search for specific error messages
• GitHub Issues: Check webpack/vite repositories
• Discord/Slack: Framework-specific communities
• Package documentation: Read npm package docs

Prevention

Best Practices

• Always test build in development first
• Use lockfiles (package-lock.json, yarn.lock)
• Pin dependency versions in CI/CD
• Monitor build times
• Keep build tools updated
• Review bundle sizes regularly

Build Performance

• Enable caching for faster rebuilds
• Use thread-loader for parallelism
• Minimize plugins to reduce complexity
• Use file system cache for production builds
• Consider incremental builds if supported

Dependency Management

• Audit dependencies regularly: npm audit
• Update dependencies with caution: npm update
• Remove unused dependencies
• Use peer dependencies correctly
• Document required Node.js versions

Integration Issues

CI/CD Integration

Problem: Build script works locally but fails in CI/CD

Solutions:

• Verify Node.js version in CI/CD matches local
• Check all dependencies are installed in CI/CD
• Review environment variables in CI/CD
• Check for platform-specific issues
• Review CI/CD logs for specific errors

Docker Builds

Problem: Build fails in Docker container

Solutions:

• Verify Dockerfile has all dependencies
• Check for platform-specific issues
• Ensure sufficient memory allocation
• Review multi-stage build setup
• Check for permission issues in container

Asset Optimization

Problem: Images or assets not optimized

Solutions:

• Install image optimization plugins
• Configure optimization settings
• Check file sizes before and after
• Verify optimization plugins are running
• Review optimization configuration

Tool-Specific Troubleshooting

Webpack

• Check webpack.config.js for syntax errors
• Verify loader order is correct
• Review plugins configuration
• Check for circular dependencies
• Use webpack CLI for debugging: webpack --display-modules

Vite

• Check vite.config.ts for errors
• Verify plugins are compatible
• Review resolve configuration
• Check for esbuild errors
• Use Vite debug flag: vite --debug

esbuild

• Check for esbuild version compatibility
• Review esbuild configuration
• Verify plugins are supported
• Check for API limitations
• Review esbuild documentation for specifics