ln-832-bundle-optimizer

name	ln-832-bundle-optimizer
description	Reduces JS/TS bundle size via tree-shaking, code splitting, and unused dependency removal. Use when optimizing frontend bundle size.
allowed-tools	Read, Grep, Glob, Bash, mcp__hex-graph__audit_workspace, mcp__hex-line__read_file, mcp__hex-line__grep_search, mcp__hex-line__outline
license	MIT

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

ln-832-bundle-optimizer

Type: L3 Worker Category: 8XX Optimization

Reduces JavaScript or TypeScript bundle size using keep/discard verification. JS/TS projects only.

---

Overview

Aspect	Details
Input	JS/TS project path plus optional optimization scope
Output	Smaller bundle plus a machine-readable modernization summary
Scope	JS/TS only

---

Workflow

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

---

Phase 0: Pre-flight Checks

Check	Required	Action if Missing
package.json exists	Yes	Block optimization
Build command available	Yes	Block optimization
Output directory (dist/ or build/) detectable	Yes	Build once to establish baseline
Workspace baseline safe	Yes	In managed runs coordinator already prepared it; in standalone runs protect rollback locally

MANDATORY READ: Load references/ci_tool_detection.md for build detection. Tool policy: follow host AGENTS.md MCP preferences; load references/mcp_tool_preferences.md and references/mcp_integration_patterns.md only when host policy is absent or MCP behavior is unclear.

Use hex-graph first when hotspots or clone groups materially improve optimization targeting. Use hex-line first for local code and config reads when available. If MCP is unavailable, unsupported, or not indexed, continue with built-in Read/Grep/Glob/Bash and state the fallback in the summary.

Runtime Coordination

Managed runs receive deterministic runId and exact summaryArtifactPath from ln-830. Standalone runs remain supported; if runtime arguments are omitted, generate a standalone run-scoped artifact before returning.

---

Phase 1: Establish Baseline

1. Run the detected build command.
2. Measure total size of the output directory.
3. Record baseline bytes and per-chunk sizes.

Metric	How
Total size	Sum all bundle output files except source maps
Per-chunk sizes	Measure individual JS and CSS files
Source map handling	Exclude .map files

---

Phase 2: Analyze Opportunities

Check	Tool	What It Finds
Unused dependencies	depcheck or equivalent	Packages not imported anywhere
Bundle composition	Bundle analyzer	Large dependencies or duplicates
Tree-shaking gaps	Manual scan	Namespace imports or heavy entrypoints
Code splitting gaps	Route analysis	Lazy-load candidates

Optimization categories:

Category	Example	Typical Savings
Remove unused deps	dead dependencies	10-50KB per package
Named imports	lodash-es named imports	50-200KB
Lighter alternatives	replace heavy date or utility libs	50-300KB
Dynamic imports	lazy-load heavy components	lower initial bundle
CSS optimization	remove unused CSS, minify	10-100KB

---

Phase 3: Optimize Loop (Keep/Discard)

Per-optimization cycle:

FOR each optimization:
  1. APPLY the change
  2. BUILD
     IF build fails -> DISCARD and revert
  3. MEASURE new bundle size
  4. KEEP only if the bundle is smaller than the current baseline
  5. LOG the result

Stop conditions:

Condition	Action
All optimizations processed	Stop and report
3 consecutive discards	Stop for plateau
Build infrastructure breaks	Revert to last keep and stop
Bundle already below target	Stop and report

Optimization order:

1. remove unused dependencies
2. improve tree-shaking and imports
3. replace heavy libraries
4. introduce code splitting
5. optimize CSS

---

Phase 4: Report Results

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 plus reasons
deps_removed[]	Dependencies removed
details[]	Per-optimization savings
artifact_path	Durable worker report path, if written

---

Configuration

Options:
  build_command: ""             # Auto-detect
  output_dir: ""                # Auto-detect
  run_depcheck: true
  run_bundle_analyzer: false
  remove_unused_deps: true
  fix_tree_shaking: true
  replace_heavy_libraries: true
  enable_code_splitting: true

---

Error Handling

Error	Cause	Solution
Build fails after optimization	Invalid code or config change	Revert that optimization
No size reduction	Optimization ineffective	Discard it
Analyzer unavailable	Tooling missing	Continue with manual inspection

---

References

• optimization_categories.md
• references/ci_tool_detection.md

---

Runtime Summary Artifact

MANDATORY READ: Load references/coordinator_summary_contract.md

Emit a modernization-worker summary envelope.

Managed mode:

• ln-830 passes deterministic runId and exact summaryArtifactPath
• write the summary to the provided summaryArtifactPath

Standalone mode:

• omit runId and summaryArtifactPath
• write .hex-skills/runtime-artifacts/runs/{run_id}/modernization-worker/ln-832--{identifier}.json

Monitor (2.1.98+): For build commands in keep/discard loop expected >30s, use Monitor. Fallback: Bash(run_in_background=true).

Definition of Done

• Baseline bundle size established from real build output
• Optimization opportunities analyzed from bundle composition and project usage
• Each optimization evaluated with keep/discard verification
• Only size-reducing optimizations kept
• Final report captures bundle delta, discarded attempts, and removed dependencies
• modernization-worker summary artifact written to the managed or standalone path

---

Version: 1.0.0 Last Updated: 2026-03-08