claude-autopm 2.8.2 → 2.8.3

package/packages/plugin-languages/commands/javascript-optimize.md

@@ -0,0 +1,636 @@
+# javascript:optimize
+
+Optimize JavaScript/TypeScript frontend performance with Context7-verified bundling, tree-shaking, and runtime optimization.
+
+## Description
+
+Comprehensive JavaScript performance optimization following web.dev best practices:
+- Bundle optimization (code splitting, tree-shaking)
+- Runtime performance (event loop, debouncing)
+- Resource loading (lazy loading, preloading)
+- Critical rendering path optimization
+- Web Workers for background processing
+
+## Required Documentation Access
+
+**MANDATORY:** Before optimization, query Context7 for JavaScript best practices:
+
+**Documentation Queries:**
+- `mcp://context7/web-dev/performance` - Web performance optimization
+- `mcp://context7/javascript/bundling` - Bundle optimization techniques
+- `mcp://context7/web-dev/critical-rendering-path` - Rendering optimization
+- `mcp://context7/javascript/web-workers` - Background processing
+- `mcp://context7/web-dev/resource-hints` - Resource loading optimization
+
+**Why This is Required:**
+- Ensures optimization follows web.dev best practices
+- Applies proven bundling and minification techniques
+- Validates resource loading strategies
+- Prevents common JavaScript performance pitfalls
+
+## Usage
+
+```bash
+/javascript:optimize [options]
+```
+
+## Options
+
+- `--scope <bundle|runtime|resources|all>` - Optimization scope (default: all)
+- `--analyze-only` - Analyze without applying changes
+- `--output <file>` - Write optimization report
+- `--bundler <webpack|vite|rollup>` - Bundler-specific optimization
+- `--target <modern|legacy>` - Browser target (default: modern)
+
+## Examples
+
+### Full Application Optimization
+```bash
+/javascript:optimize
+```
+
+### Bundle Optimization Only
+```bash
+/javascript:optimize --scope bundle --bundler vite
+```
+
+### Analyze Performance
+```bash
+/javascript:optimize --analyze-only --output performance-report.md
+```
+
+### Modern Browsers Only
+```bash
+/javascript:optimize --target modern
+```
+
+## Optimization Categories
+
+### 1. Bundle Optimization (Context7-Verified)
+
+**Patterns from Context7 (/websites/web_dev_learn):**
+
+#### Code Splitting
+```javascript
+// BEFORE: Single large bundle
+import { heavyLibrary } from 'heavy-lib';
+import { rareFeature } from './rare-feature';
+
+function init() {
+  heavyLibrary.setup();
+  if (needsRareFeature) {
+    rareFeature.run();
+  }
+}
+// Bundle size: 850 KB
+
+// AFTER: Dynamic imports (code splitting)
+function init() {
+  import('heavy-lib').then(({ heavyLibrary }) => {
+    heavyLibrary.setup();
+  });
+
+  if (needsRareFeature) {
+    import('./rare-feature').then(({ rareFeature }) => {
+      rareFeature.run();
+    });
+  }
+}
+// Initial bundle: 150 KB (82% reduction)
+// Lazy chunks: Loaded on demand
+```
+
+**Performance Impact:**
+- Initial load: 850 KB → 150 KB (82% reduction)
+- Time to Interactive: 3.2s → 0.9s (72% faster)
+- First Contentful Paint: 1.8s → 0.5s (72% faster)
+
+#### Tree Shaking (Webpack/Rollup)
+```javascript
+// library.js - Export multiple functions
+export function usedFunction() {
+  return 'used';
+}
+
+export function unusedFunction() {
+  return 'never imported';
+}
+
+// app.js - Import only what you need
+import { usedFunction } from './library';
+
+console.log(usedFunction());
+
+// Result: unusedFunction() is removed from bundle (dead code elimination)
+```
+
+**Configuration (package.json):**
+```json
+{
+  "sideEffects": false
+}
+```
+
+**Benefits:**
+- Removes unused exports (20-40% smaller bundles)
+- Works with ES6 modules
+- Automatic dead code elimination
+
+#### Minification and Uglification
+```javascript
+// BEFORE: Unminified JavaScript
+export function injectScript() {
+  const scriptElement = document.createElement('script');
+  scriptElement.src = '/js/scripts.js';
+  scriptElement.type = 'module';
+  document.body.appendChild(scriptElement);
+}
+// Size: 180 bytes
+
+// AFTER: Minified (Terser/UglifyJS)
+export function injectScript(){const t=document.createElement("script");t.src="/js/scripts.js",t.type="module",document.body.appendChild(t)}
+// Size: 126 bytes (30% reduction)
+```
+
+**Benefits:**
+- 20-40% size reduction
+- Faster parsing
+- Automatic in production builds
+
+### 2. Critical Rendering Path Optimization (Context7-Verified)
+
+**Patterns from Context7 (/websites/web_dev_learn):**
+
+#### Inline Critical CSS
+```html
+<head>
+  <title>Page Title</title>
+  <!-- Inline critical CSS (above-the-fold styles) -->
+  <style>
+    h1,h2{color:#000}h1{font-size:2em}h2{font-size:1.5em}
+  </style>
+</head>
+<body>
+  <!-- Page content -->
+
+  <!-- Load non-critical CSS asynchronously -->
+  <link rel="stylesheet" href="non-critical.css">
+</body>
+```
+
+**Benefits:**
+- Eliminates render-blocking CSS request
+- Faster First Contentful Paint (FCP)
+- Improved Largest Contentful Paint (LCP)
+
+**Performance Impact:**
+- FCP: 1.8s → 0.6s (67% faster)
+- LCP: 2.4s → 1.1s (54% faster)
+
+#### Defer Non-Critical JavaScript
+```html
+<!-- BEFORE: Render-blocking script -->
+<script src="/script.js"></script>
+
+<!-- AFTER: Deferred script -->
+<script defer src="/script.js"></script>
+```
+
+**Benefits:**
+- HTML parsing continues while script downloads
+- Script executes after DOM is parsed
+- Maintains execution order
+
+**Script Loading Strategies:**
+```html
+<!-- Critical: Block parsing (use sparingly) -->
+<script src="/critical.js"></script>
+
+<!-- Non-critical: Defer execution -->
+<script src="/non-critical.js" defer></script>
+
+<!-- Analytics: Async (order doesn't matter) -->
+<script src="/analytics.js" async></script>
+```
+
+#### Resource Hints
+```html
+<!-- Preconnect: Establish early connection -->
+<link rel="preconnect" href="https://api.example.com">
+
+<!-- DNS Prefetch: Resolve DNS early -->
+<link rel="dns-prefetch" href="https://fonts.googleapis.com">
+
+<!-- Preload: High-priority resource -->
+<link rel="preload" href="/styles/critical.css" as="style">
+
+<!-- Prefetch: Low-priority future navigation -->
+<link rel="prefetch" href="/page2.html" as="document">
+```
+
+**Benefits:**
+- Faster resource loading (100-500ms savings)
+- Reduced latency for API calls
+- Improved navigation performance
+
+### 3. Runtime Performance Optimization (Context7-Verified)
+
+**Patterns from Context7:**
+
+#### Debouncing Expensive Operations
+```javascript
+// Context7 Pattern: Debounce scroll/resize handlers
+function debounce(func, wait) {
+  let timeout;
+  return function executedFunction(...args) {
+    const later = () => {
+      clearTimeout(timeout);
+      func(...args);
+    };
+    clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+  };
+}
+
+// Usage: Debounce scroll handler
+const handleScroll = debounce(() => {
+  console.log('Scroll handled');
+  updateScrollPosition();
+}, 200);
+
+window.addEventListener('scroll', handleScroll);
+```
+
+**Benefits:**
+- Reduces function calls by 90-95%
+- Prevents event loop congestion
+- Smoother scrolling/resizing
+
+**Performance Impact:**
+- Without debounce: 500 calls/second (event loop blocked)
+- With debounce (200ms): 5 calls/second (smooth performance)
+
+#### Lazy Loading with Intersection Observer
+```javascript
+// Context7 Pattern: Lazy load images
+const imageObserver = new IntersectionObserver((entries, observer) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      const img = entry.target;
+      img.src = img.dataset.src;
+      img.classList.add('loaded');
+      observer.unobserve(img);
+    }
+  });
+});
+
+// Apply to all images with data-src
+document.querySelectorAll('img[data-src]').forEach(img => {
+  imageObserver.observe(img);
+});
+```
+
+**HTML:**
+```html
+<img
+  src="/images/placeholder.jpg"
+  data-src="/images/actual-image.jpg"
+  loading="lazy"
+  alt="Description"
+/>
+```
+
+**Benefits:**
+- Images load only when visible
+- Faster initial page load
+- Reduced bandwidth usage
+
+**Performance Impact:**
+- Initial load: 2.5 MB → 0.3 MB (88% reduction)
+- Page load time: 4.2s → 1.1s (74% faster)
+
+#### Web Workers for Background Processing
+```javascript
+// Context7 Pattern: Offload heavy computation
+// main.js
+const worker = new Worker('/worker.js');
+
+worker.postMessage({ data: largeDataset });
+
+worker.onmessage = (event) => {
+  console.log('Result:', event.data);
+  updateUI(event.data);
+};
+
+// worker.js
+self.onmessage = (event) => {
+  const result = processData(event.data);
+  self.postMessage(result);
+};
+
+function processData(data) {
+  // Heavy computation (doesn't block main thread)
+  return data.map(item => expensiveOperation(item));
+}
+```
+
+**Benefits:**
+- Main thread remains responsive
+- Parallel processing
+- No UI freezing during computation
+
+**Performance Impact:**
+- Without worker: UI frozen for 3 seconds
+- With worker: UI responsive (computation in background)
+
+#### Performance API for Measurement
+```javascript
+// Context7 Pattern: Measure custom timing
+performance.mark('process-start');
+
+// ... expensive operation
+await processLargeDataset();
+
+performance.mark('process-end');
+performance.measure('process', 'process-start', 'process-end');
+
+const measure = performance.getEntriesByName('process')[0];
+console.log('Process took:', measure.duration, 'ms');
+```
+
+**Navigation Timing:**
+```javascript
+// Measure page load performance
+const perfData = performance.getEntriesByType('navigation')[0];
+console.log('DOM Load:', perfData.domContentLoadedEventEnd);
+console.log('Full Load:', perfData.loadEventEnd);
+```
+
+### 4. Responsive Images Optimization
+
+**Pattern from Context7:**
+
+```html
+<!-- Picture element with WebP -->
+<picture>
+  <source
+    media="(min-width: 1200px)"
+    srcset="/images/hero-large.webp"
+    type="image/webp"
+  />
+  <source
+    media="(min-width: 768px)"
+    srcset="/images/hero-medium.webp"
+    type="image/webp"
+  />
+  <img
+    src="/images/hero-small.jpg"
+    alt="Hero image"
+    loading="lazy"
+    width="800"
+    height="600"
+  />
+</picture>
+```
+
+**Benefits:**
+- Modern format (WebP): 30-50% smaller than JPEG
+- Responsive sizing: Correct image for device
+- Lazy loading: Deferred loading for below-fold images
+
+**Performance Impact:**
+- Image size: 1.2 MB → 0.4 MB (67% reduction)
+- Mobile bandwidth savings: 80%
+
+#### Prioritize LCP Image
+```html
+<!-- LCP image should NOT be lazy loaded -->
+<img
+  src="hero.jpg"
+  alt="Main promotional image"
+  fetchpriority="high"
+>
+```
+
+**Benefits:**
+- Prioritizes critical image loading
+- Improves Largest Contentful Paint (LCP)
+- Better Core Web Vitals score
+
+### 5. Render-Blocking Resource Management
+
+**Pattern from Context7:**
+
+#### Mark Render-Blocking Resources
+```html
+<!-- Explicitly mark render-blocking (Chrome 105+) -->
+<link rel="stylesheet" href="critical.css" blocking="render">
+<script src="important.js" blocking="render"></script>
+<style blocking="render">
+  body { background-color: lightblue; }
+</style>
+```
+
+#### Mark Non-Render-Blocking
+```html
+<!-- Make CSS non-render-blocking with media query -->
+<link rel="stylesheet" href="print.css" media="print">
+<link rel="stylesheet" href="large-screens.css" media="(min-width: 1200px)">
+```
+
+**Benefits:**
+- Explicit control over rendering
+- Parser continues processing
+- Faster initial rendering
+
+## Optimization Output
+
+```
+🎨 JavaScript/Frontend Performance Optimization Analysis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Project: React SPA
+Bundler: Webpack 5.89.0
+Target: Modern Browsers (ES2020)
+
+📦 Bundle Analysis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Current Bundle Size: 850 KB (uncompressed)
+  Gzipped: 280 KB
+  Target: < 200 KB (gzipped)
+
+  ⚠️  Large bundle detected
+
+  Top Contributors:
+  1. moment.js - 72 KB (use date-fns: 92% smaller)
+  2. lodash - 68 KB (use lodash-es: tree-shakeable)
+  3. unused exports - 54 KB (enable tree-shaking)
+  4. duplicate code - 38 KB (deduplicate dependencies)
+
+  💡 Recommendations:
+  1. Replace moment with date-fns → Save 66 KB
+  2. Replace lodash with lodash-es → Save 50 KB
+  3. Enable tree-shaking (sideEffects: false) → Save 54 KB
+  4. Code splitting for routes → Initial: 150 KB (82% reduction)
+
+  Expected Impact: 850 KB → 150 KB initial (82% reduction)
+
+🚀 Critical Rendering Path
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ❌ Render-blocking resources detected
+
+  CSS:
+  - /styles/main.css (42 KB, 320ms)
+  - /styles/fonts.css (18 KB, 180ms)
+
+  JavaScript:
+  - /js/vendor.js (180 KB, 890ms)
+  - /js/app.js (120 KB, 640ms)
+
+  💡 Recommendations:
+  1. Inline critical CSS → Save 500ms (FCP improvement)
+  2. Defer non-critical JS → Save 1,530ms
+  3. Preload critical resources → Save 200ms
+
+  Expected Impact:
+  - FCP: 1.8s → 0.6s (67% faster)
+  - LCP: 2.4s → 1.1s (54% faster)
+
+⚡ Runtime Performance
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ⚠️  Performance issues detected
+
+  1. Scroll handler without debounce
+     File: components/Navbar.js:42
+     Impact: 500 calls/second (blocks event loop)
+     💡 Add debouncing (200ms)
+
+  2. Heavy computation in main thread
+     File: utils/dataProcessor.js:156
+     Time: 2.3 seconds (UI frozen)
+     💡 Move to Web Worker
+
+  3. Large images not lazy loaded
+     Count: 15 images (8 MB total)
+     💡 Add lazy loading attribute
+
+  Expected Impact:
+  - Smooth scrolling (95% fewer calls)
+  - Responsive UI (no freezing)
+  - 88% faster initial load (lazy loading)
+
+📊 Resource Loading
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ⚠️  Suboptimal resource loading
+
+  Issues:
+  1. Missing preconnect for API (api.example.com)
+  2. Missing preload for LCP image
+  3. No resource hints for external fonts
+
+  💡 Recommendations:
+  1. Add preconnect for API → Save 300ms
+  2. Add preload for hero image → Save 200ms (LCP)
+  3. Add dns-prefetch for fonts → Save 100ms
+
+  Expected Impact: 600ms faster resource loading
+
+Summary
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Total Optimizations: 14
+
+  🔴 Critical: 2 (bundle size, render-blocking)
+  🟡 High Impact: 6 (lazy loading, debouncing, workers)
+  🟢 Medium Impact: 6 (resource hints, code splitting)
+
+  Estimated Performance Improvement:
+  - Bundle size: -82% (850 KB → 150 KB initial)
+  - FCP: -67% (1.8s → 0.6s)
+  - LCP: -54% (2.4s → 1.1s)
+  - TTI: -72% (3.2s → 0.9s)
+
+  Core Web Vitals:
+  - LCP: 2.4s → 1.1s (✅ Good: < 2.5s)
+  - FID: 80ms → 20ms (✅ Good: < 100ms)
+  - CLS: 0.15 → 0.05 (✅ Good: < 0.1)
+
+  Run with --apply to implement optimizations
+```
+
+## Implementation
+
+This command uses the **@javascript-frontend-engineer** agent:
+
+1. Query Context7 for JavaScript optimization patterns
+2. Analyze bundle composition (Webpack Bundle Analyzer)
+3. Check critical rendering path (render-blocking resources)
+4. Detect performance anti-patterns (missing debouncing, lazy loading)
+5. Validate resource loading (preload, preconnect, prefetch)
+6. Generate optimization recommendations
+7. Optionally apply automated fixes
+
+## Best Practices Applied
+
+Based on Context7 documentation from `/websites/web_dev_learn`:
+
+1. **Code Splitting** - Reduce initial bundle size (82%)
+2. **Tree Shaking** - Remove unused exports (20-40%)
+3. **Debouncing** - Optimize event handlers (95% fewer calls)
+4. **Lazy Loading** - Load resources on demand (88% savings)
+5. **Web Workers** - Background processing (non-blocking)
+6. **Resource Hints** - Faster resource loading (600ms savings)
+7. **Critical CSS** - Eliminate render-blocking (67% faster FCP)
+
+## Related Commands
+
+- `/react:optimize` - React-specific optimization
+- `/nextjs:optimize` - Next.js optimization
+- `/bundle:analyze` - Bundle analysis
+
+## Troubleshooting
+
+### Large Bundle Size
+- Enable tree-shaking (package.json: sideEffects: false)
+- Use dynamic imports for code splitting
+- Replace heavy libraries with lighter alternatives
+
+### Slow First Paint
+- Inline critical CSS
+- Defer non-critical JavaScript
+- Preload critical resources
+
+### Blocked Event Loop
+- Add debouncing to scroll/resize handlers
+- Move heavy computation to Web Workers
+- Use requestAnimationFrame for animations
+
+## Installation
+
+```bash
+# Bundle analyzers
+npm install --save-dev webpack-bundle-analyzer
+npm install --save-dev rollup-plugin-visualizer
+
+# Performance utilities
+npm install --save-dev lighthouse
+npm install --save-dev @bundle/cli
+
+# Modern date library (replace moment)
+npm install date-fns
+
+# Tree-shakeable utilities (replace lodash)
+npm install lodash-es
+```
+
+## Version History
+
+- v2.0.0 - Initial Schema v2.0 release with Context7 integration
+- Bundle optimization patterns
+- Critical rendering path optimization
+- Runtime performance best practices
+