# 🔧 Build Optimization Tutorial

> **Master Bun's build system** - Learn to create optimized production builds, configure advanced bundling options, and analyze bundle performance with Arsenal Lab's interactive playground.

[![Advanced](https://img.shields.io/badge/📈_Level-Advanced-red?style=flat)]()
[![Time](https://img.shields.io/badge/⏱️_Duration-25_min-blue?style=flat)]()
[![Build Focus](https://img.shields.io/badge/🎯_Focus-Bundling-FF9F43?style=flat)]()

## 🎯 Tutorial Overview

This comprehensive tutorial covers:
- Interactive Bun.build() API exploration
- Production-ready build configuration
- Bundle size optimization techniques
- Code splitting and lazy loading
- Source maps and debugging
- Performance analysis and monitoring
- CLI integration and automation

## 📋 Prerequisites

- Arsenal Lab running ([Getting Started](../Getting-Started.md))
- Basic understanding of bundlers
- Node.js/npm experience
- 20-25 minutes available

## 🚀 Step 1: Launch Build Configuration Arsenal

```bash
cd Arsenal-Lab
bun run dev
```

Navigate to **http://localhost:3655** and select **"Build Configuration Arsenal"**.

### Interface Overview

- **Configuration Tabs**: Core, Environment, JSX, Optimization, Output, Advanced, CLI
- **Live Code Generation**: Real-time config updates
- **CLI Command Preview**: Copy-paste ready commands
- **Build Execution**: Test configurations instantly

## ⚙️ Step 2: Core Build Configuration

### Entry Points & Targets

1. Click **"Core Options"** tab
2. Set **Entry points**: `["./src/index.ts", "./src/worker.ts"]`
3. Choose **Target**: `browser` (try different targets)
4. Select **Format**: `esm`

**What you'll see:**
```javascript
// Generated configuration
{
  "entrypoints": ["./src/index.ts", "./src/worker.ts"],
  "target": "browser",
  "format": "esm"
}
```

### Understanding Targets

- **browser**: Web applications, uses DOM APIs
- **bun**: Bun runtime, access to Bun APIs
- **node**: Node.js applications, uses Node APIs

### Format Options

- **esm**: ES modules (recommended)
- **cjs**: CommonJS modules
- **iife**: Immediately Invoked Function Expression

## 🎨 Step 3: Environment Configuration

### Define Variables

1. Switch to **"Environment Options"**
2. Add **Define**: `{"__DEV__": "true", "API_URL": "https://api.example.com"}`
3. Set **Env mode**: `inline`

**Generated code:**
```javascript
{
  "define": {
    "__DEV__": "true",
    "API_URL": "https://api.example.com"
  },
  "env": "inline"
}
```

### Environment Handling

```javascript
// In your code
if (__DEV__) {
  console.log('Development mode');
}

const apiUrl = API_URL; // Replaced at build time
```

### Conditions Configuration

```javascript
// Advanced environment setup
{
  "conditions": ["browser", "development"],
  "env": {
    "inline": ["NODE_ENV", "API_URL"],
    "external": ["SECRET_KEY"] // Not inlined
  }
}
```

## ⚛️ Step 4: JSX Configuration

### JSX Setup

1. Click **"JSX Options"**
2. Set **Runtime**: `automatic`
3. Configure **Factory**: `React.createElement`
4. Set **Fragment**: `React.Fragment`

**JSX configuration:**
```javascript
{
  "jsx": {
    "runtime": "automatic",
    "factory": "React.createElement",
    "fragment": "React.Fragment",
    "importSource": "@emotion/react" // For CSS-in-JS
  }
}
```

### JSX Runtime Options

- **automatic**: Modern JSX transform (recommended)
- **classic**: Legacy JSX transform

### Advanced JSX Features

```javascript
// With CSS-in-JS libraries
{
  "jsx": {
    "runtime": "automatic",
    "importSource": "@emotion/react"
  }
}

// Custom JSX pragma
{
  "jsx": {
    "factory": "h",
    "fragment": "Fragment"
  }
}
```

## 🚀 Step 5: Optimization Techniques

### Minification

1. Go to **"Optimization"** tab
2. Enable **Minify**: `true`
3. Configure detailed options:
   - **Whitespace**: `true`
   - **Syntax**: `true`
   - **Identifiers**: `true`

**Optimization config:**
```javascript
{
  "minify": {
    "whitespace": true,
    "syntax": true,
    "identifiers": true
  }
}
```

### Code Splitting

```javascript
// Enable code splitting
{
  "splitting": true,
  "format": "esm" // Required for splitting
}

// Lazy loading example
import { lazy } from 'react';

const LazyComponent = lazy(() =>
  import('./components/HeavyComponent')
);
```

### External Dependencies

```javascript
// Externalize large libraries
{
  "external": ["react", "react-dom", "lodash"],
  "packages": "external" // Externalize all node_modules
}
```

## 📦 Step 6: Output Configuration

### Naming Patterns

1. Click **"Output"** tab
2. Configure **Naming**:
   - **Entry**: `"[name]-[hash].js"`
   - **Chunk**: `"chunk-[hash].js"`
   - **Asset**: `"asset-[name]-[hash].[ext]"`

**Output configuration:**
```javascript
{
  "outdir": "./dist",
  "naming": {
    "entry": "[name]-[hash].js",
    "chunk": "chunk-[hash].js",
    "asset": "asset-[name]-[hash].[ext]"
  },
  "publicPath": "/assets/",
  "sourcemap": "linked"
}
```

### Source Maps

- **none**: No source maps (production)
- **linked**: Separate .map files
- **inline**: Embedded in bundle
- **external**: External source maps

## 🔧 Step 7: Advanced Build Features

### Bytecode Compilation

1. Go to **"Advanced"** tab
2. Enable **Bytecode**: `true` (Bun feature)

**Advanced options:**
```javascript
{
  "bytecode": true,
  "throw": false,
  "banner": "// Built with Arsenal Lab",
  "footer": "// End of bundle",
  "drop": ["console", "debugger"],
  "ignoreDCEAnnotations": false,
  "emitDCEAnnotations": true
}
```

### Dead Code Elimination

```javascript
// Mark code for elimination
/* @__PURE__ */ function unusedFunction() {
  return 'This will be removed';
}

// Conditional dead code
if (__DEV__) {
  console.log('Development only');
}
```

## 💻 Step 8: CLI Integration

### Command Generation

1. Switch to **"CLI Options"** tab
2. Enable **Watch mode**: `true`
3. Set **Production**: `true`

**Generated CLI command:**
```bash
bun build ./src/index.ts \
  --target=browser \
  --format=esm \
  --minify \
  --outdir=./dist \
  --sourcemap=linked \
  --watch \
  --production
```

### CLI Options Explained

- **--watch**: Rebuild on file changes
- **--production**: Enable production optimizations
- **--compile**: Create standalone executable
- **--no-clear-screen**: Keep terminal output

## 📊 Step 9: Build Analysis & Optimization

### Bundle Size Analysis

```javascript
// Analyze bundle composition
const { build } = await import('bun');

const result = await build({
  entrypoints: ['./src/index.ts'],
  target: 'browser',
  minify: true,
  // ... other options
});

console.log('Build completed:');
console.log(`- Output files: ${result.outputs.length}`);
console.log(`- Total size: ${result.outputs.reduce((sum, out) => sum + out.size, 0)} bytes`);
```

### Performance Monitoring

```javascript
// Track build performance
class BuildMonitor {
  constructor() {
    this.builds = [];
  }

  async timeBuild(config) {
    const start = performance.now();

    const result = await Bun.build(config);

    const duration = performance.now() - start;

    this.builds.push({
      timestamp: new Date(),
      duration,
      config,
      outputSize: result.outputs.reduce((sum, out) => sum + out.size, 0),
      success: !result.logs.some(log => log.level === 'error')
    });

    return result;
  }

  getBuildStats() {
    const successful = this.builds.filter(b => b.success);

    return {
      totalBuilds: this.builds.length,
      successfulBuilds: successful.length,
      avgDuration: successful.reduce((sum, b) => sum + b.duration, 0) / successful.length,
      fastestBuild: Math.min(...successful.map(b => b.duration)),
      slowestBuild: Math.max(...successful.map(b => b.duration))
    };
  }
}
```

## 🧪 Step 10: Testing Build Configurations

### Development vs Production

```javascript
// Development configuration
const devConfig = {
  entrypoints: ['./src/index.ts'],
  target: 'browser',
  minify: false,
  sourcemap: 'linked',
  define: { __DEV__: 'true' }
};

// Production configuration
const prodConfig = {
  ...devConfig,
  minify: { whitespace: true, syntax: true, identifiers: true },
  sourcemap: 'external',
  define: { __DEV__: 'false' },
  drop: ['console']
};
```

### Cross-Platform Testing

```javascript
// Test different targets
const targets = ['browser', 'bun', 'node'];
const formats = ['esm', 'cjs', 'iife'];

for (const target of targets) {
  for (const format of formats) {
    try {
      const result = await Bun.build({
        entrypoints: ['./src/index.ts'],
        target,
        format,
        outdir: `./dist/${target}-${format}`
      });

      console.log(`✅ ${target}-${format}: ${result.outputs.length} files`);
    } catch (error) {
      console.log(`❌ ${target}-${format}: ${error.message}`);
    }
  }
}
```

## 🚀 Step 11: Deployment Optimization

### CDN Optimization

```javascript
// Optimize for CDN deployment
const cdnConfig = {
  entrypoints: ['./src/index.ts'],
  target: 'browser',
  format: 'esm',
  minify: true,
  splitting: true,
  publicPath: 'https://cdn.example.com/assets/',
  naming: {
    entry: '[name]-[hash].js',
    chunk: 'chunk-[hash].js'
  }
};
```

### Service Worker Integration

```javascript
// Generate service worker-friendly build
const swConfig = {
  ...cdnConfig,
  banner: `
    // Service Worker Cache Version: ${Date.now()}
    const CACHE_NAME = 'app-v${Date.now()}';
  `,
  footer: `
    // Register service worker
    if ('serviceWorker' in navigator) {
      navigator.serviceWorker.register('/sw.js');
    }
  `
};
```

## 📈 Step 12: Performance Budgets

### Size Limits

```javascript
// Define performance budgets
const budgets = {
  bundleSize: 500 * 1024,      // 500KB
  vendorSize: 200 * 1024,      // 200KB
  initialChunk: 100 * 1024,    // 100KB
  buildTime: 30 * 1000         // 30 seconds
};

function checkBudgets(result, buildTime) {
  const violations = [];

  const totalSize = result.outputs.reduce((sum, out) => sum + out.size, 0);
  if (totalSize > budgets.bundleSize) {
    violations.push(`Bundle too large: ${totalSize} > ${budgets.bundleSize}`);
  }

  if (buildTime > budgets.buildTime) {
    violations.push(`Build too slow: ${buildTime}ms > ${budgets.buildTime}ms`);
  }

  return violations;
}
```

### Continuous Integration

```bash
# CI build script
#!/bin/bash

echo "🏗️ Building application..."

start_time=$(date +%s%3N)
bun build ./src/index.ts --target=browser --minify --outdir=./dist
build_time=$(( $(date +%s%3N) - start_time ))

echo "✅ Build completed in ${build_time}ms"

# Check bundle size
bundle_size=$(du -bc dist/* | tail -1 | awk '{print $1}')
echo "📦 Bundle size: ${bundle_size} bytes"

# Performance assertions
if [ "$bundle_size" -gt 524288 ]; then
  echo "❌ Bundle size exceeds 512KB limit"
  exit 1
fi

if [ "$build_time" -gt 30000 ]; then
  echo "❌ Build time exceeds 30s limit"
  exit 1
fi

echo "🎉 All performance budgets passed!"
```

## 🎯 Tutorial Summary

### Build Optimization Mastery

✅ **Core build configuration** with Bun.build() API
✅ **Environment and JSX setup** for different targets
✅ **Optimization techniques** for production builds
✅ **Output configuration** and source map management
✅ **Advanced features** like bytecode and DCE
✅ **CLI integration** and automation
✅ **Performance monitoring** and budget enforcement

### Key Takeaways

1. **Configuration matters** - Fine-tune settings for your use case
2. **Target selection** impacts available APIs and optimizations
3. **Code splitting** reduces initial bundle size
4. **Source maps** enable debugging in production
5. **Performance budgets** prevent regressions
6. **Automation** ensures consistent builds

### Production-Ready Patterns

- **Development**: Fast rebuilds, source maps, no minification
- **Staging**: Production config, debugging enabled
- **Production**: Full optimization, error tracking, CDN deployment

## 🏆 Achievement Unlocked!

**Build Optimization Expert** 🏆
You've mastered Bun's build system and learned to:
- Configure advanced build options
- Optimize bundle size and performance
- Implement code splitting and lazy loading
- Set up CI/CD pipelines
- Monitor build performance
- Create deployment-ready configurations

## 📚 Continue Your Journey

### Advanced Topics
- **[Performance Testing Tutorial](Performance-Testing.md)** - Benchmark your builds
- **[Integration Guides](../Integration-Guides.md)** - Framework-specific builds
- **[Deployment Guide](../Deployment.md)** - Production deployment

### Reference Materials
- **[Build API Reference](../API-Documentation.md#buildconfigurationarsenal)**
- **[CLI Documentation](https://bun.com/docs/cli/build)**
- **[Bundler Comparison](https://bundlers.tooling.report/)**

### Community Resources
- **[Bun Discord](https://bun.com/docs/discord)** - Real-time help
- **[GitHub Issues](https://github.com/oven-sh/bun/issues)** - Bug reports
- **[Awesome Bun](https://github.com/oven-sh/awesome-bun)** - Tools and libraries

---

**Questions?** Join our [GitHub Discussions](https://github.com/brendadeeznuts1111/Arsenal-Lab/discussions) or check the [Troubleshooting Guide](../Troubleshooting.md).

**Built with ❤️ for the Bun ecosystem** • **Last updated:** October 21, 2025