Build System

aegir build [options]

Options:
  --bundle         Build the JS standalone bundle (default: true)
  --bundlesize     Analyze bundle size (default: false)
  --bundlesizeMax  Max threshold for bundle size (string or object)
  --types          Build TypeScript declarations (default: true)

interface BuildOptions {
  /** Build the JS standalone bundle */
  bundle: boolean;
  /** Analyze bundle size with threshold checking */
  bundlesize: boolean;
  /** Max bundle size thresholds */
  bundlesizeMax: string | Record<string, string>;
  /** Build TypeScript type declarations */
  types: boolean;
  /** esbuild configuration options */
  config: esbuild.BuildOptions;
}

// .aegir.js configuration
module.exports = {
  build: {
    bundle: true,
    bundlesize: true,
    bundlesizeMax: "100KB", // Single threshold
    // Or multiple thresholds:
    bundlesizeMax: {
      "dist/index.min.js": "50KB",
      "dist/worker.min.js": "80KB"
    },
    types: true,
    config: {
      // Custom esbuild options
      minify: true,
      sourcemap: true,
      target: 'es2020'
    }
  }
};

# TypeScript compilation is automatically triggered when:
# 1. tsconfig.json exists in project root
# 2. --types option is true (default)
# 3. TypeScript files are detected in src/

// Default bundle configuration:
// - Input: src/index.js or dist/src/index.js (for TS)
// - Output: dist/index.min.js
// - Format: IIFE with UMD wrapper
// - Minification: enabled
// - Source maps: enabled
// - Global variable: PascalCase version of package name

// Bundle size analysis features:
// - Gzip size calculation
// - Threshold validation
// - Size comparison reporting
// - Generates dist/stats.json for esbuild analyzer
// - Fails build if size exceeds thresholds

# Build with bundle size analysis
aegir build --bundlesize

# Build with custom size threshold
aegir build --bundlesize --bundlesizeMax "50KB"

# Build types only (no bundle)
aegir build --no-bundle --types

// Configure multiple entry points in .aegir.js:
module.exports = {
  build: {
    config: {
      entryPoints: {
        'index': 'src/index.js',
        'worker': 'src/worker.js'
      },
      outdir: 'dist'
    }
  }
};

// Results in:
// - dist/index.js
// - dist/worker.js

dist/
├── index.min.js      # Main browser bundle
├── index.min.js.map  # Source map
├── stats.json        # Bundle analysis (if --bundlesize)
└── src/              # TypeScript declarations (if --types)
    ├── index.d.ts
    └── types.d.ts

// JavaScript projects:
// - Entry point: src/index.js
// - Output: dist/index.min.js

// TypeScript projects (with tsconfig.json):
// - Compile TS to dist/src/ first
// - Entry point: dist/src/index.js
// - Output: dist/index.min.js + dist/src/*.d.ts

# Example error output:
# dist/index.min.js 150KB (▲50KB / 100KB)
# Error: Bundle size exceeds maximum threshold