Agent Skills: ln-832-bundle-optimizer

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

ln-832-bundle-optimizer

Type: L3 Worker Category: 8XX Optimization

Reduces JavaScript/TypeScript bundle size. Metric: bundle size in bytes. Each optimization verified via build with keep/discard pattern. JS/TS projects only.

Overview

| Aspect | Details | |--------|---------| | Input | JS/TS project (auto-detect from package.json) | | Output | Smaller bundle, optimization report | | Scope | JS/TS only (skip for other stacks) |

Workflow

Phases: Pre-flight → Baseline → Analyze → Optimize Loop → Report

Phase 0: Pre-flight Checks

| Check | Required | Action if Missing | |-------|----------|-------------------| | package.json exists | Yes | Block (not a JS/TS project) | | Build command available | Yes | Block (need build for size measurement) | | dist/ or build/ output | Yes | Run build first to establish baseline | | Git clean state | Yes | Block (need clean baseline for revert) |

MANDATORY READ: Load shared/references/ci_tool_detection.md — use Build section for build command detection.

Worktree & Branch Isolation

MANDATORY READ: Load shared/references/git_worktree_fallback.md — use ln-832 row.

Phase 1: Establish Baseline

Measure Current Bundle Size

1. Run build: npm run build (or detected build command)
2. Measure: total size of dist/ or build/ directory
3. Record: baseline_bytes, baseline_files

| Metric | How | |--------|-----| | Total size | Sum of all files in output directory | | Per-chunk sizes | Individual JS/CSS file sizes | | Source map excluded | Do not count .map files |

Phase 2: Analyze Opportunities

Analysis Tools

| Check | Tool | What It Finds | |-------|------|--------------| | Unused dependencies | npx depcheck | Packages in package.json not imported anywhere | | Bundle composition | npx vite-bundle-visualizer or webpack-bundle-analyzer | Large dependencies, duplicates | | Tree-shaking gaps | Manual scan | import * as instead of named imports | | Code splitting | Route analysis | Large initial bundle, lazy-loadable routes |

Optimization Categories

| Category | Example | Typical Savings | |----------|---------|----------------| | Remove unused deps | lodash installed but not imported | 10-50KB per dep | | Named imports | import { debounce } from 'lodash-es' vs import _ from 'lodash' | 50-200KB | | Lighter alternatives | date-fns instead of moment | 50-300KB | | Dynamic imports | React.lazy(() => import('./HeavyComponent')) | Reduce initial load | | CSS optimization | Purge unused CSS, minify | 10-100KB |

Phase 3: Optimize Loop (Keep/Discard)

Per-Optimization Cycle

FOR each optimization (O1..ON):
  1. APPLY: Make change (remove dep, rewrite import, add lazy load)
  2. BUILD: Run build command
     IF build FAILS → DISCARD (revert) → next optimization
  3. MEASURE: New bundle size
  4. COMPARE:
     IF new_bytes < baseline_bytes → KEEP (new baseline = new_bytes)
     IF new_bytes >= baseline_bytes → DISCARD (revert, no improvement)
  5. LOG: Record result

Stop Conditions (Optimize Loop)

| Condition | Action | |-----------|--------| | All optimizations processed | STOP — proceed to Report | | 3 consecutive DISCARDs (no size reduction) | STOP — plateau: "No further reductions found" | | Build infrastructure breaks | STOP — revert to last KEEP, report partial results | | Bundle already below target size | STOP — "Bundle already optimized" |

Keep/Discard Decision

| Condition | Decision | |-----------|----------| | Build fails | DISCARD | | Bundle smaller | KEEP (update baseline) | | Bundle same or larger | DISCARD |

Optimization Order

| Order | Category | Reason | |-------|----------|--------| | 1 | Remove unused deps | Safest, immediate savings | | 2 | Named imports / tree-shaking | Medium risk, good savings | | 3 | Lighter alternatives | Higher risk (API changes) | | 4 | Dynamic imports / code splitting | Structural change, test carefully | | 5 | CSS optimization | Lowest priority |

Phase 4: Report Results

Report Schema

| Field | Description | |-------|-------------| | project | Project path | | baseline_bytes | Original bundle size | | final_bytes | Final bundle size | | reduction_bytes | Bytes saved | | reduction_percent | Percentage reduction | | optimizations_applied | Count of kept optimizations | | optimizations_discarded | Count + reasons | | details[] | Per-optimization: category, description, bytes saved | | deps_removed[] | Unused dependencies removed |

Configuration

Options:
  # Build
  build_command: ""             # Auto-detect from ci_tool_detection.md
  output_dir: ""                # Auto-detect: dist/ or build/

  # Analysis
  run_depcheck: true
  run_bundle_analyzer: false    # Opens browser, skip in CI

  # Optimization scope
  remove_unused_deps: true
  fix_tree_shaking: true
  suggest_alternatives: true
  add_code_splitting: false     # Structural change, opt-in

  # Verification
  run_build: true

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | depcheck not available | Not installed | npx depcheck (runs without install) | | Build fails after removal | Dep used in dynamic import / config | Revert, mark as false positive | | No output directory | Non-standard build setup | Check package.json for output config | | Not a JS/TS project | No package.json | Skip entirely with info message |

References

• shared/references/ci_tool_detection.md (build detection)

Definition of Done

• [ ] JS/TS project confirmed (package.json present)
• [ ] Baseline bundle size measured (build + measure dist/)
• [ ] Unused deps identified via depcheck
• [ ] Each optimization applied with keep/discard: build passes + smaller → keep
• [ ] Compound: each kept optimization updates baseline for next
• [ ] Report returned with baseline, final, reduction%, per-optimization details

Version: 1.0.0 Last Updated: 2026-03-08