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.
ln-832-bundle-optimizer
Type: L3 Worker
Category: 8XX Optimization
Parent: ln-830-code-modernization-coordinator
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
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
levalencia