cp-toolkit 2.0.0

package/templates/skills/optional/nextjs-react-expert/8-advanced-advanced-patterns.md

@@ -0,0 +1,150 @@
+# 8. Advanced Patterns
+
+> **Impact:** VARIABLE
+> **Focus:** Advanced patterns for specific cases that require careful implementation.
+
+---
+
+## Overview
+
+This section contains **3 rules** focused on advanced patterns.
+
+---
+
+## Rule 8.1: Initialize App Once, Not Per Mount
+
+**Impact:** LOW-MEDIUM  
+**Tags:** initialization, useEffect, app-startup, side-effects  
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+---
+
+## Rule 8.2: Store Event Handlers in Refs
+
+**Impact:** LOW  
+**Tags:** advanced, hooks, refs, event-handlers, optimization  
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+---
+
+## Rule 8.3: useEffectEvent for Stable Callback Refs
+
+**Impact:** LOW  
+**Tags:** advanced, hooks, useEffectEvent, refs, optimization  
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+

package/templates/skills/optional/nextjs-react-expert/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: nextjs-react-expert
+description: React and Next.js performance optimization from Vercel Engineering. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, reviewing code for performance issues, or implementing server/client-side optimizations.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Next.js & React Performance Expert
+
+> **From Vercel Engineering** - 57 optimization rules prioritized by impact
+> **Philosophy:** Eliminate waterfalls first, optimize bundles second, then micro-optimize.
+
+---
+
+## 🎯 Selective Reading Rule (MANDATORY)
+
+**Read ONLY sections relevant to your task!** Check the content map below and load what you need.
+
+> 🔴 **For performance reviews: Start with CRITICAL sections (1-2), then move to HIGH/MEDIUM.**
+
+---
+
+## 📑 Content Map
+
+| File | Impact | Rules | When to Read |
+|------|--------|-------|--------------|
+| `1-async-eliminating-waterfalls.md` | 🔴 **CRITICAL** | 5 rules | Slow page loads, sequential API calls, data fetching waterfalls |
+| `2-bundle-bundle-size-optimization.md` | 🔴 **CRITICAL** | 5 rules | Large bundle size, slow Time to Interactive, First Load issues |
+| `3-server-server-side-performance.md` | 🟠 **HIGH** | 7 rules | Slow SSR, API route optimization, server-side waterfalls |
+| `4-client-client-side-data-fetching.md` | 🟡 **MEDIUM-HIGH** | 4 rules | Client data management, SWR patterns, deduplication |
+| `5-rerender-re-render-optimization.md` | 🟡 **MEDIUM** | 12 rules | Excessive re-renders, React performance, memoization |
+| `6-rendering-rendering-performance.md` | 🟡 **MEDIUM** | 9 rules | Rendering bottlenecks, virtualization, image optimization |
+| `7-js-javascript-performance.md` | ⚪ **LOW-MEDIUM** | 12 rules | Micro-optimizations, caching, loop performance |
+| `8-advanced-advanced-patterns.md` | 🔵 **VARIABLE** | 3 rules | Advanced React patterns, useLatest, init-once |
+
+**Total: 57 rules across 8 categories**
+
+---
+
+## 🚀 Quick Decision Tree
+
+**What's your performance issue?**
+
+```
+🐌 Slow page loads / Long Time to Interactive
+  → Read Section 1: Eliminating Waterfalls
+  → Read Section 2: Bundle Size Optimization
+
+📦 Large bundle size (> 200KB)
+  → Read Section 2: Bundle Size Optimization
+  → Check: Dynamic imports, barrel imports, tree-shaking
+
+🖥️ Slow Server-Side Rendering
+  → Read Section 3: Server-Side Performance
+  → Check: Parallel data fetching, streaming
+
+🔄 Too many re-renders / UI lag
+  → Read Section 5: Re-render Optimization
+  → Check: React.memo, useMemo, useCallback
+
+🎨 Rendering performance issues
+  → Read Section 6: Rendering Performance
+  → Check: Virtualization, layout thrashing
+
+🌐 Client-side data fetching problems
+  → Read Section 4: Client-Side Data Fetching
+  → Check: SWR deduplication, localStorage
+
+✨ Need advanced patterns
+  → Read Section 8: Advanced Patterns
+```
+
+---
+
+## 📊 Impact Priority Guide
+
+**Use this order when doing comprehensive optimization:**
+
+```
+1️⃣ CRITICAL (Biggest Gains - Do First):
+   ├─ Section 1: Eliminating Waterfalls
+   │  └─ Each waterfall adds full network latency (100-500ms+)
+   └─ Section 2: Bundle Size Optimization
+      └─ Affects Time to Interactive and Largest Contentful Paint
+
+2️⃣ HIGH (Significant Impact - Do Second):
+   └─ Section 3: Server-Side Performance
+      └─ Eliminates server-side waterfalls, faster response times
+
+3️⃣ MEDIUM (Moderate Gains - Do Third):
+   ├─ Section 4: Client-Side Data Fetching
+   ├─ Section 5: Re-render Optimization
+   └─ Section 6: Rendering Performance
+
+4️⃣ LOW (Polish - Do Last):
+   ├─ Section 7: JavaScript Performance
+   └─ Section 8: Advanced Patterns
+```
+
+---
+
+## 🔗 Related Skills
+
+| Need | Skill |
+|------|-------|
+| API design patterns | `@[skills/api-patterns]` |
+| Database optimization | `@[skills/database-design]` |
+| Testing strategies | `@[skills/testing-patterns]` |
+| UI/UX design principles | `@[skills/frontend-design]` |
+| TypeScript patterns | `@[skills/typescript-expert]` |
+| Deployment & DevOps | `@[skills/deployment-procedures]` |
+
+---
+
+## ✅ Performance Review Checklist
+
+Before shipping to production:
+
+**Critical (Must Fix):**
+- [ ] No sequential data fetching (waterfalls eliminated)
+- [ ] Bundle size < 200KB for main bundle
+- [ ] No barrel imports in app code
+- [ ] Dynamic imports used for large components
+- [ ] Parallel data fetching where possible
+
+**High Priority:**
+- [ ] Server components used where appropriate
+- [ ] API routes optimized (no N+1 queries)
+- [ ] Suspense boundaries for data fetching
+- [ ] Static generation used where possible
+
+**Medium Priority:**
+- [ ] Expensive computations memoized
+- [ ] List rendering virtualized (if > 100 items)
+- [ ] Images optimized with next/image
+- [ ] No unnecessary re-renders
+
+**Low Priority (Polish):**
+- [ ] Hot path loops optimized
+- [ ] RegExp patterns hoisted
+- [ ] Property access cached in loops
+
+---
+
+## ❌ Anti-Patterns (Common Mistakes)
+
+**DON'T:**
+- ❌ Use sequential `await` for independent operations
+- ❌ Import entire libraries when you need one function
+- ❌ Use barrel exports (`index.ts` re-exports) in app code
+- ❌ Skip dynamic imports for large components/libraries
+- ❌ Fetch data in useEffect without deduplication
+- ❌ Forget to memoize expensive computations
+- ❌ Use client components when server components work
+
+**DO:**
+- ✅ Fetch data in parallel with `Promise.all()`
+- ✅ Use dynamic imports: `const Comp = dynamic(() => import('./Heavy'))`
+- ✅ Import directly: `import { specific } from 'library/specific'`
+- ✅ Use Suspense boundaries for better UX
+- ✅ Leverage React Server Components
+- ✅ Measure performance before optimizing
+- ✅ Use Next.js built-in optimizations (next/image, next/font)
+
+---
+
+## 🎯 How to Use This Skill
+
+### For New Features:
+1. Check **Section 1 & 2** while building (prevent waterfalls, keep bundle small)
+2. Use server components by default (Section 3)
+3. Apply memoization for expensive operations (Section 5)
+
+### For Performance Reviews:
+1. Start with **Section 1** (waterfalls = biggest impact)
+2. Then **Section 2** (bundle size)
+3. Then **Section 3** (server-side)
+4. Finally other sections as needed
+
+### For Debugging Slow Performance:
+1. Identify the symptom (slow load, lag, etc.)
+2. Use Quick Decision Tree above
+3. Read relevant section
+4. Apply fixes in priority order
+
+---
+
+## 📚 Learning Path
+
+**Beginner (Focus on Critical):**
+→ Section 1: Eliminating Waterfalls
+→ Section 2: Bundle Size Optimization
+
+**Intermediate (Add High Priority):**
+→ Section 3: Server-Side Performance
+→ Section 5: Re-render Optimization
+
+**Advanced (Full Optimization):**
+→ All sections + Section 8: Advanced Patterns
+
+---
+
+## 🔍 Validation Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/react_performance_checker.py` | Automated performance audit | `python scripts/react_performance_checker.py <project_path>` |
+
+---
+
+## 📖 Section Details
+
+### Section 1: Eliminating Waterfalls (CRITICAL)
+**Impact:** Each waterfall adds 100-500ms+ latency
+**Key Concepts:** Parallel fetching, Promise.all(), Suspense boundaries, preloading
+
+### Section 2: Bundle Size Optimization (CRITICAL)
+**Impact:** Directly affects Time to Interactive, Largest Contentful Paint
+**Key Concepts:** Dynamic imports, tree-shaking, barrel import avoidance
+
+### Section 3: Server-Side Performance (HIGH)
+**Impact:** Faster server responses, better SEO
+**Key Concepts:** Parallel server fetching, streaming, API route optimization
+
+### Section 4: Client-Side Data Fetching (MEDIUM-HIGH)
+**Impact:** Reduces redundant requests, better UX
+**Key Concepts:** SWR deduplication, localStorage caching, event listeners
+
+### Section 5: Re-render Optimization (MEDIUM)
+**Impact:** Smoother UI, less wasted computation
+**Key Concepts:** React.memo, useMemo, useCallback, component structure
+
+### Section 6: Rendering Performance (MEDIUM)
+**Impact:** Better rendering efficiency
+**Key Concepts:** Virtualization, image optimization, layout thrashing
+
+### Section 7: JavaScript Performance (LOW-MEDIUM)
+**Impact:** Incremental improvements in hot paths
+**Key Concepts:** Loop optimization, caching, RegExp hoisting
+
+### Section 8: Advanced Patterns (VARIABLE)
+**Impact:** Specific use cases
+**Key Concepts:** useLatest hook, init-once patterns, event handler refs
+
+---
+
+## 🎓 Best Practices Summary
+
+**Golden Rules:**
+1. **Measure first** - Use React DevTools Profiler, Chrome DevTools
+2. **Biggest impact first** - Waterfalls → Bundle → Server → Micro
+3. **Don't over-optimize** - Focus on real bottlenecks
+4. **Use platform features** - Next.js has optimizations built-in
+5. **Think about users** - Real-world conditions matter
+
+**Performance Mindset:**
+- Every `await` in sequence = potential waterfall
+- Every `import` = potential bundle bloat
+- Every re-render = wasted computation (if unnecessary)
+- Server components = less JavaScript to ship
+- Measure, don't guess
+
+---
+
+**Source:** Vercel Engineering
+**Date:** January 2026
+**Version:** 1.0.0
+**Total Rules:** 57 across 8 categories

package/templates/skills/optional/nextjs-react-expert/scripts/convert_rules.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Conversion Script: React Best Practices → .agent Format
+Merges 59 individual rules into 8 grouped section files
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+# Section metadata from _sections.md
+SECTIONS = {
+    'async': {
+        'number': 1,
+        'title': 'Eliminating Waterfalls',
+        'impact': 'CRITICAL',
+        'description': 'Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.'
+    },
+    'bundle': {
+        'number': 2,
+        'title': 'Bundle Size Optimization',
+        'impact': 'CRITICAL',
+        'description': 'Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.'
+    },
+    'server': {
+        'number': 3,
+        'title': 'Server-Side Performance',
+        'impact': 'HIGH',
+        'description': 'Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.'
+    },
+    'client': {
+        'number': 4,
+        'title': 'Client-Side Data Fetching',
+        'impact': 'MEDIUM-HIGH',
+        'description': 'Automatic deduplication and efficient data fetching patterns reduce redundant network requests.'
+    },
+    'rerender': {
+        'number': 5,
+        'title': 'Re-render Optimization',
+        'impact': 'MEDIUM',
+        'description': 'Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.'
+    },
+    'rendering': {
+        'number': 6,
+        'title': 'Rendering Performance',
+        'impact': 'MEDIUM',
+        'description': 'Optimizing the rendering process reduces the work the browser needs to do.'
+    },
+    'js': {
+        'number': 7,
+        'title': 'JavaScript Performance',
+        'impact': 'LOW-MEDIUM',
+        'description': 'Micro-optimizations for hot paths can add up to meaningful improvements.'
+    },
+    'advanced': {
+        'number': 8,
+        'title': 'Advanced Patterns',
+        'impact': 'VARIABLE',
+        'description': 'Advanced patterns for specific cases that require careful implementation.'
+    }
+}
+
+
+def parse_frontmatter(content: str) -> Tuple[Dict, str]:
+    """Parse markdown frontmatter and body"""
+    if not content.startswith('---'):
+        return {}, content
+
+    parts = content.split('---', 2)
+    if len(parts) < 3:
+        return {}, content
+
+    # Parse YAML frontmatter manually (simple key: value)
+    frontmatter = {}
+    for line in parts[1].strip().split('\n'):
+        if ':' in line:
+            key, value = line.split(':', 1)
+            frontmatter[key.strip()] = value.strip()
+
+    body = parts[2].strip()
+    return frontmatter, body
+
+
+def parse_rule_file(filepath: Path) -> Dict:
+    """Parse a single rule file"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    frontmatter, body = parse_frontmatter(content)
+
+    # Extract prefix from filename
+    filename = filepath.stem
+    prefix = filename.split('-')[0]
+
+    return {
+        'filename': filepath.name,
+        'prefix': prefix,
+        'title': frontmatter.get('title', filename),
+        'impact': frontmatter.get('impact', ''),
+        'impactDescription': frontmatter.get('impactDescription', ''),
+        'tags': frontmatter.get('tags', ''),
+        'body': body,
+        'frontmatter': frontmatter
+    }
+
+
+def group_rules_by_section(rules_dir: Path) -> Dict[str, List[Dict]]:
+    """Group all rules by their section prefix"""
+    grouped = {prefix: [] for prefix in SECTIONS.keys()}
+
+    for rule_file in sorted(rules_dir.glob('*.md')):
+        # Skip special files
+        if rule_file.name.startswith('_'):
+            continue
+
+        rule = parse_rule_file(rule_file)
+        prefix = rule['prefix']
+
+        if prefix in grouped:
+            grouped[prefix].append(rule)
+        else:
+            print(f"[WARNING] Unknown prefix '{prefix}' in file: {rule_file.name}")
+
+    return grouped
+
+
+def generate_section_file(section_prefix: str, rules: List[Dict], output_dir: Path):
+    """Generate a merged section file"""
+    if not rules:
+        print(f"[WARNING] No rules found for section: {section_prefix}")
+        return
+
+    section_meta = SECTIONS[section_prefix]
+    section_num = section_meta['number']
+    section_title = section_meta['title']
+    impact = section_meta['impact']
+    description = section_meta['description']
+
+    # Sort rules by title
+    rules.sort(key=lambda r: r['title'])
+
+    # Build content
+    content = f"""# {section_num}. {section_title}
+
+> **Impact:** {impact}
+> **Focus:** {description}
+
+---
+
+## Overview
+
+This section contains **{len(rules)} rules** focused on {section_title.lower()}.
+
+"""
+
+    # Add each rule
+    for i, rule in enumerate(rules, 1):
+        rule_id = f"{section_num}.{i}"
+        title = rule['title']
+        rule_impact = rule['impact']
+        tags = rule['tags']
+        body = rule['body']
+
+        content += f"""---
+
+## Rule {rule_id}: {title}
+
+"""
+
+        if rule_impact:
+            content += f"**Impact:** {rule_impact}  \n"
+
+        if tags:
+            content += f"**Tags:** {tags}  \n"
+
+        content += f"\n{body}\n\n"
+
+    # Write file
+    output_file = output_dir / f"{section_num}-{section_prefix}-{section_title.lower().replace(' ', '-')}.md"
+    output_file.write_text(content, encoding='utf-8')
+    print(f"[OK] Generated: {output_file.name} ({len(rules)} rules)")
+
+
+def main():
+    """Main conversion function"""
+    # Paths
+    base_dir = Path(__file__).parent.parent.parent.parent.parent
+    rules_dir = base_dir / "others/agent-skills/skills/react-best-practices/rules"
+    output_dir = base_dir / ".agent/skills/nextjs-react-expert"
+
+    print(f"[*] Reading rules from: {rules_dir}")
+    print(f"[*] Output to: {output_dir}")
+    print()
+
+    # Check if rules directory exists
+    if not rules_dir.exists():
+        print(f"[ERROR] Rules directory not found: {rules_dir}")
+        return
+
+    # Group rules
+    print("[*] Grouping rules by section...")
+    grouped_rules = group_rules_by_section(rules_dir)
+
+    # Stats
+    total_rules = sum(len(rules) for rules in grouped_rules.values())
+    print(f"[*] Found {total_rules} total rules")
+    print()
+
+    # Generate section files
+    print("[*] Generating section files...")
+    for section_prefix in SECTIONS.keys():
+        rules = grouped_rules[section_prefix]
+        generate_section_file(section_prefix, rules, output_dir)
+
+    print()
+    print("[SUCCESS] Conversion complete!")
+    print(f"[*] Generated 8 section files from {total_rules} rules")
+
+
+if __name__ == '__main__':
+    main()