@codihaus/claude-skills 1.6.19 → 1.6.20

package/knowledge/stacks/nextjs/_index.md

@@ -637,6 +637,31 @@ if (process.env.NODE_ENV !== 'production') {
 }
 ```
 
+## Advanced RSC & Performance Patterns
+
+**See `references/rsc-patterns.md` for comprehensive Next.js optimization guide covering**:
+- Eliminating waterfalls (defer await, dependency parallelization, Promise.all)
+- Server-side performance (LRU caching, serialization, React.cache, after())
+- Bundle optimization (avoid barrel imports, dynamic imports, preloading)
+- Data fetching strategies (auto-deduplication, SWR, caching)
+- Server Actions best practices
+
+**Critical patterns**:
+- **Defer await until needed** - Don't block unused code paths
+- **Start promises early** - Enable parallelization in API routes
+- **Component composition** - Move async calls to components for parallel execution
+- **Minimize serialization** - Only pass needed fields across RSC boundary
+- **React.cache()** - Deduplicate DB queries, auth checks, heavy computations
+- **after()** - Schedule non-blocking work (analytics, logging)
+- **Avoid barrel imports** - Use optimizePackageImports or direct imports
+- **LRU caching** - Share data across requests (especially with Fluid Compute)
+
+**Impact metrics**:
+- Eliminating waterfalls: 2-10× faster
+- Avoiding barrel imports: 15-70% faster builds
+- LRU caching: Eliminates redundant queries
+- after() for non-blocking: 50-200ms faster responses
+
 ## Resources
 
 ### Official Docs
@@ -644,6 +669,11 @@ if (process.env.NODE_ENV !== 'production') {
 - App Router: https://nextjs.org/docs/app
 - Learn: https://nextjs.org/learn
 
+### Performance & Patterns
+- Vercel Best Practices: https://github.com/vercel/react-best-practices
+- See `references/rsc-patterns.md` - Detailed RSC & optimization guide
+- See `references/performance.md` - Next.js performance optimizations
+
 ### Context7 Queries
 
 ```
@@ -651,4 +681,6 @@ Query: "Next.js 15 App Router data fetching"
 Query: "Next.js Server Actions best practices"
 Query: "Next.js middleware authentication"
 Query: "Next.js Server Components patterns"
+Query: "Next.js RSC waterfall elimination"
+Query: "Next.js bundle optimization barrel imports"
 ```

package/knowledge/stacks/nextjs/references/rsc-patterns.md

@@ -0,0 +1,705 @@
+# Next.js RSC & Server Actions Patterns
+
+> Critical patterns for React Server Components and Server Actions from Vercel Engineering
+
+## Eliminating Waterfalls
+
+### Defer Await Until Needed
+
+**Impact**: HIGH - Avoids blocking unused code paths
+
+Move `await` operations into branches where they're actually used:
+
+```typescript
+// ❌ Incorrect: blocks both branches
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+
+  if (skipProcessing) {
+    return { skipped: true }  // Still waited!
+  }
+
+  return processUserData(userData)
+}
+
+// ✅ Correct: only blocks when needed
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    return { skipped: true }  // No wait
+  }
+
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Early return optimization**:
+
+```typescript
+// ❌ Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+
+  if (!resource) return { error: 'Not found' }
+  if (!permissions.canEdit) return { error: 'Forbidden' }
+
+  return await updateResourceData(resource, permissions)
+}
+
+// ✅ Correct: check resource first (cheaper)
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  if (!resource) return { error: 'Not found' }
+
+  const permissions = await fetchPermissions(userId)
+  if (!permissions.canEdit) return { error: 'Forbidden' }
+
+  return await updateResourceData(resource, permissions)
+}
+```
+
+### Dependency-Based Parallelization
+
+**Impact**: CRITICAL - 2-10× improvement
+
+Use `better-all` for partial dependencies:
+
+```typescript
+// ❌ Incorrect: profile waits for config unnecessarily
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+
+// ✅ Correct: config and profile run in parallel
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+### Prevent Waterfall Chains in API Routes
+
+**Impact**: CRITICAL - 2-10× improvement
+
+Start independent operations immediately:
+
+```typescript
+// ❌ Incorrect: sequential
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+
+// ✅ Correct: parallel where possible
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+
+  return Response.json({ data, config })
+}
+```
+
+### Promise.all() for Independent Operations
+
+**Impact**: CRITICAL - Reduces N round trips to 1
+
+```typescript
+// ❌ Incorrect: sequential (3 round trips)
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+
+// ✅ Correct: parallel (1 round trip)
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### Strategic Suspense Boundaries
+
+**Impact**: Faster initial paint
+
+Show wrapper UI immediately while data streams in:
+
+```tsx
+// ❌ Incorrect: all or nothing
+export default async function Page() {
+  const [header, content, sidebar] = await Promise.all([
+    fetchHeader(),
+    fetchContent(),
+    fetchSidebar()
+  ])
+  return <Layout header={header} content={content} sidebar={sidebar} />
+}
+
+// ✅ Correct: streams in progressively
+async function Header() {
+  const data = await fetchHeader()
+  return <header>{data}</header>
+}
+
+async function Content() {
+  const data = await fetchContent()
+  return <main>{data}</main>
+}
+
+async function Sidebar() {
+  const data = await fetchSidebar()
+  return <aside>{data}</aside>
+}
+
+export default function Page() {
+  return (
+    <>
+      <Suspense fallback={<HeaderSkeleton />}>
+        <Header />
+      </Suspense>
+      <Suspense fallback={<ContentSkeleton />}>
+        <Content />
+      </Suspense>
+      <Suspense fallback={<SidebarSkeleton />}>
+        <Sidebar />
+      </Suspense>
+    </>
+  )
+}
+```
+
+**Share promises with `use()` hook**:
+
+```tsx
+const dataPromise = fetchData()
+
+function ParentComponent() {
+  return (
+    <>
+      <ChildA dataPromise={dataPromise} />
+      <ChildB dataPromise={dataPromise} />
+    </>
+  )
+}
+
+function ChildA({ dataPromise }) {
+  const data = use(dataPromise)  // Shares same promise
+  return <div>{data.title}</div>
+}
+
+function ChildB({ dataPromise }) {
+  const data = use(dataPromise)  // Same promise, no duplicate fetch
+  return <div>{data.count}</div>
+}
+```
+
+## Server-Side Performance
+
+### Cross-Request LRU Caching
+
+**Impact**: HIGH - Especially with Vercel Fluid Compute
+
+`React.cache()` only works within one request. Use LRU cache for sequential user actions:
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const userCache = new LRUCache<string, User>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = userCache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  userCache.set(id, user)
+  return user
+}
+```
+
+**Why this matters**: With Vercel Fluid Compute, the same instance handles multiple requests from the same user. LRU cache survives across requests.
+
+### Minimize Serialization at RSC Boundaries
+
+**Impact**: HIGH - Reduces data transfer size
+
+Only pass fields the client actually uses:
+
+```typescript
+// ❌ Incorrect: serializes all 50 fields
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />  // Client uses 1 field
+}
+
+// ✅ Correct: serializes only 1 field
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+// ✅ Alternative: transform before passing
+async function Page() {
+  const user = await fetchUser()
+  const clientData = {
+    name: user.name,
+    avatar: user.avatar
+  }
+  return <Profile user={clientData} />
+}
+```
+
+**Why this matters**: Data is embedded in HTML response AND RSC requests. Large objects increase payload size and parsing time.
+
+### Parallel Data Fetching with Component Composition
+
+**Impact**: CRITICAL - Eliminates server-side waterfalls
+
+RSCs execute sequentially within a tree. Restructure to parallelize:
+
+```tsx
+// ❌ Incorrect: Sidebar waits for Page's fetch
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />  {/* Waits for header */}
+    </div>
+  )
+}
+
+// ✅ Correct: both fetch simultaneously
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />  {/* Parallel! */}
+    </div>
+  )
+}
+```
+
+**Pro tip**: Move async calls into separate components at the same level to maximize parallelism.
+
+### Per-Request Deduplication with React.cache()
+
+**Impact**: HIGH - Prevents duplicate queries in one render
+
+**Important**: In Next.js, `fetch` is auto-deduplicated. Use `React.cache()` for:
+- Database queries
+- Heavy computations
+- Auth checks
+- File system operations
+
+```typescript
+import { cache } from 'react'
+
+// ✅ Correct: multiple calls = one execution
+export const getUser = cache(async (id: string) => {
+  return await db.user.findUnique({ where: { id } })
+})
+
+// Usage in multiple components
+async function Profile() {
+  const user = await getUser('123')  // Executes
+  return <div>{user.name}</div>
+}
+
+async function Avatar() {
+  const user = await getUser('123')  // Cached!
+  return <img src={user.avatar} />
+}
+```
+
+**Warning**: Avoid inline objects as arguments (always cache miss):
+
+```typescript
+// ❌ Incorrect: cache miss every time (different object reference)
+const getData = cache(async (options: { id: string }) => {
+  return await db.query(options.id)
+})
+getData({ id: '123' })  // Miss
+getData({ id: '123' })  // Miss (different object!)
+
+// ✅ Correct: use primitives or stable references
+const getData = cache(async (id: string) => {
+  return await db.query(id)
+})
+getData('123')  // Hit
+getData('123')  // Hit
+```
+
+### Use after() for Non-Blocking Operations
+
+**Impact**: HIGH - Faster response times
+
+Schedule work after response is sent:
+
+```typescript
+import { after } from 'next/server'
+
+export async function POST(request: Request) {
+  const data = await request.json()
+  await updateDatabase(data)
+
+  after(async () => {
+    // These don't block the response
+    await logUserAction(data)
+    await sendAnalytics(data)
+    await invalidateCache(data.id)
+    await sendNotification(data.userId)
+  })
+
+  return new Response(JSON.stringify({ status: 'success' }))
+}
+```
+
+**Perfect for**:
+- Analytics
+- Audit logging
+- Notifications
+- Cache invalidation
+- External webhooks
+
+## Bundle Size Optimization
+
+### Avoid Barrel File Imports
+
+**Impact**: CRITICAL - 200-800ms import cost, 15-70% faster builds
+
+Popular libraries have 1000s of re-exports. Tree-shaking doesn't help:
+
+```typescript
+// ❌ Incorrect: loads 1,583 modules, ~2.8s in dev
+import { Check, X, Menu } from 'lucide-react'
+
+// ✅ Correct: loads only 3 modules
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+
+// ✅ Best: Next.js 13.5+ (auto-optimized)
+// next.config.js
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material', '@mui/icons-material']
+  }
+}
+// Then use barrel imports normally
+import { Check, X, Menu } from 'lucide-react'  // Optimized!
+```
+
+**Affected libraries**: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`
+
+### Conditional Module Loading
+
+**Impact**: HIGH - Reduces initial bundle
+
+Load large modules only when feature is activated:
+
+```typescript
+// ❌ Incorrect: always bundled
+import { processData } from './heavy-library'
+
+export default function Component() {
+  const [advanced, setAdvanced] = useState(false)
+
+  if (!advanced) return <SimpleView />
+
+  return <AdvancedView data={processData(input)} />
+}
+
+// ✅ Correct: loaded only when needed
+export default function Component() {
+  const [advanced, setAdvanced] = useState(false)
+
+  if (!advanced) return <SimpleView />
+
+  const { processData } = await import('./heavy-library')
+  return <AdvancedView data={processData(input)} />
+}
+```
+
+**Client-side SSR prevention**:
+
+```typescript
+// Prevents bundling in server bundle
+if (typeof window !== 'undefined') {
+  const { heavyClientLib } = await import('./client-only')
+}
+```
+
+### Defer Non-Critical Third-Party Libraries
+
+**Impact**: HIGH - Analytics/monitoring don't block interaction
+
+Load after hydration:
+
+```tsx
+// ❌ Incorrect: blocks hydration
+import Analytics from 'analytics-lib'
+
+export default function Layout({ children }) {
+  return (
+    <>
+      <Analytics />
+      {children}
+    </>
+  )
+}
+
+// ✅ Correct: loads after hydration
+const Analytics = dynamic(() => import('./Analytics'), {
+  ssr: false  // Client-only
+})
+
+export default function Layout({ children }) {
+  return (
+    <>
+      {children}
+      <Analytics />
+    </>
+  )
+}
+```
+
+### Dynamic Imports for Heavy Components
+
+**Impact**: CRITICAL - Directly affects TTI and LCP
+
+Example: Monaco Editor (~300KB) should always be dynamic:
+
+```tsx
+// ❌ Incorrect: adds 300KB to initial bundle
+import Editor from '@monaco-editor/react'
+
+export default function Page() {
+  return <Editor />
+}
+
+// ✅ Correct: loaded on demand
+const Editor = dynamic(() => import('@monaco-editor/react'), {
+  loading: () => <div>Loading editor...</div>,
+  ssr: false
+})
+
+export default function Page() {
+  return <Editor />
+}
+```
+
+### Preload Based on User Intent
+
+**Impact**: MEDIUM-HIGH - Feels instant
+
+Preload before click using hover/focus:
+
+```tsx
+import { useState } from 'react'
+
+function NavigationLink({ href, children }) {
+  const [isPreloading, setIsPreloading] = useState(false)
+
+  return (
+    <Link
+      href={href}
+      onMouseEnter={() => {
+        if (!isPreloading) {
+          setIsPreloading(true)
+          // Preload route
+          router.prefetch(href)
+        }
+      }}
+      onFocus={() => {
+        if (!isPreloading) {
+          setIsPreloading(true)
+          router.prefetch(href)
+        }
+      }}
+    >
+      {children}
+    </Link>
+  )
+}
+```
+
+## Data Fetching Strategies
+
+### fetch is Auto-Deduplicated
+
+**Built-in**: Same URL + options = one request per render
+
+```tsx
+// ✅ Automatic deduplication
+async function Header() {
+  const data = await fetch('/api/data')  // Request 1
+  return <div>{data.title}</div>
+}
+
+async function Content() {
+  const data = await fetch('/api/data')  // Deduplicated!
+  return <div>{data.body}</div>
+}
+```
+
+### React.cache() for Non-Fetch
+
+Use for DB queries, file ops, computations:
+
+```typescript
+import { cache } from 'react'
+
+export const getSettings = cache(async () => {
+  // Heavy computation or DB query
+  return await db.settings.findFirst()
+})
+```
+
+### Client-Side: Use SWR for Deduplication
+
+```typescript
+import useSWR from 'swr'
+
+// Multiple instances share one request
+function Component() {
+  const { data } = useSWR('/api/user', fetcher)
+  return <div>{data?.name}</div>
+}
+
+// Use useImmutableSWR for static data
+import { useImmutableSWR } from 'swr/immutable'
+
+function StaticComponent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+  return <div>{data?.appName}</div>
+}
+```
+
+## Server Actions Best Practices
+
+### Prevent Waterfalls
+
+```typescript
+'use server'
+
+// ❌ Incorrect: sequential
+export async function updateProfile(data: FormData) {
+  const user = await getUser()
+  const validated = await validateData(data)
+  const result = await saveToDb(validated)
+  return result
+}
+
+// ✅ Correct: parallel where possible
+export async function updateProfile(data: FormData) {
+  const userPromise = getUser()
+  const validatedPromise = validateData(data)
+
+  const [user, validated] = await Promise.all([
+    userPromise,
+    validatedPromise
+  ])
+
+  const result = await saveToDb(validated)
+  return result
+}
+```
+
+### Use after() for Non-Blocking Work
+
+```typescript
+'use server'
+
+import { after } from 'next/server'
+
+export async function createPost(data: FormData) {
+  const post = await db.post.create({ data })
+
+  after(async () => {
+    await revalidatePath('/blog')
+    await sendNotification(post.authorId)
+    await trackEvent('post_created', { postId: post.id })
+  })
+
+  return { success: true, postId: post.id }
+}
+```
+
+### React.cache() for Shared Logic
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session) return null
+  return await db.user.findUnique({ where: { id: session.userId } })
+})
+
+// Multiple server actions can call this
+export async function updateProfile(data: FormData) {
+  const user = await getCurrentUser()  // Cached
+  // ...
+}
+
+export async function deleteAccount() {
+  const user = await getCurrentUser()  // Same cache
+  // ...
+}
+```
+
+## Anti-Patterns to Avoid
+
+### Critical Anti-Patterns
+1. ❌ Sequential awaits for independent operations
+2. ❌ Barrel file imports (200-800ms overhead)
+3. ❌ Awaiting in parent RSC before rendering children
+4. ❌ Passing entire objects across RSC boundary
+
+### High-Impact Anti-Patterns
+5. ❌ No deduplication for repeated calls (use React.cache/SWR)
+6. ❌ Blocking responses with logging/analytics (use after())
+7. ❌ Inline objects as React.cache() arguments
+8. ❌ Not using optimizePackageImports for icon libraries
+
+### Subtle Bugs
+9. ❌ Forgetting `ssr: false` for client-only libraries
+10. ❌ Not hoisting async calls to enable parallelization
+11. ❌ Using barrel imports in dev (slow HMR)
+12. ❌ LRU cache without TTL (memory leak)
+
+## Key Metrics
+
+| Optimization | Improvement |
+|---|---|
+| Eliminate waterfalls | 2-10× faster |
+| Avoid barrel imports | 15-70% faster builds, 28% faster HMR |
+| Bundle size reduction | Direct TTI/LCP impact |
+| LRU caching | Eliminates redundant DB queries |
+| Parallel RSC composition | Eliminates server waterfalls |
+| after() for non-blocking | 50-200ms faster responses |
+
+**Reference**: [Vercel React Best Practices](https://github.com/vercel/react-best-practices)

package/knowledge/stacks/react/_index.md

@@ -571,9 +571,30 @@ When reviewing React code:
 - useDeferredValue (defer updates for performance)
 - useSyncExternalStore (external store integration)
 
+## Advanced Performance Patterns
+
+**See `references/performance.md` for comprehensive optimization guide covering**:
+- Re-render optimization (functional setState, lazy initialization, transitions)
+- Rendering performance (hoisting, content-visibility, hydration)
+- Client-side optimization (passive listeners, storage caching)
+- JavaScript performance (index maps, Set/Map, toSorted)
+- Advanced patterns (useLatest, event handler refs)
+
+**Key takeaways**:
+- Use functional setState to prevent stale closures
+- Lazy initialize expensive state with function
+- Mark non-urgent updates with startTransition
+- Hoist static JSX outside render
+- Use content-visibility for long lists
+- Cache storage API calls in memory
+- Build index Maps for repeated lookups
+- Use toSorted() instead of sort() for immutability
+
 ## Resources
 
 - [React Docs](https://react.dev) - Official documentation
 - [React DevTools](https://react.dev/learn/react-developer-tools) - Browser extension
 - [Rules of Hooks](https://react.dev/reference/rules/rules-of-hooks) - Hook constraints
 - [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app) - TS patterns
+- [Vercel React Best Practices](https://github.com/vercel/react-best-practices) - Performance patterns
+- `references/performance.md` - Detailed optimization guide

package/knowledge/stacks/react/references/performance.md

@@ -0,0 +1,573 @@
+# React Performance Optimization
+
+> Critical performance patterns from Vercel Engineering
+
+## Re-render Optimization
+
+### Functional setState Updates
+
+**Impact**: Prevents stale closures, enables stable callbacks
+
+Always use functional updates when state depends on current state:
+
+```typescript
+// ❌ Incorrect: stale closure risk
+const removeItem = useCallback((id: string) => {
+  setItems(items.filter(item => item.id !== id))
+}, [])  // Missing items dependency - STALE
+
+// ✅ Correct: always uses latest state
+const removeItem = useCallback((id: string) => {
+  setItems(curr => curr.filter(item => item.id !== id))
+}, [])  // Safe and stable
+```
+
+### Lazy State Initialization
+
+**Impact**: Expensive initial computation runs only once
+
+Pass function to `useState` for expensive initial values:
+
+```typescript
+// ❌ Incorrect: runs on every render
+const [settings, setSettings] = useState(
+  JSON.parse(localStorage.getItem('settings') || '{}')
+)
+
+// ✅ Correct: runs only once
+const [settings, setSettings] = useState(() => {
+  const stored = localStorage.getItem('settings')
+  return stored ? JSON.parse(stored) : {}
+})
+```
+
+### Use Transitions for Non-Urgent Updates
+
+**Impact**: Maintains UI responsiveness
+
+Mark frequent, non-urgent updates as transitions:
+
+```typescript
+import { useTransition } from 'react'
+
+function SearchResults() {
+  const [isPending, startTransition] = useTransition()
+  const [results, setResults] = useState([])
+
+  function handleSearch(query: string) {
+    startTransition(() => {
+      // Non-urgent: heavy filtering/search
+      setResults(expensiveSearch(query))
+    })
+  }
+
+  return (
+    <>
+      <input onChange={e => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <Results data={results} />
+    </>
+  )
+}
+```
+
+### Defer State Reads to Usage Point
+
+**Impact**: Avoids unnecessary re-renders
+
+Don't subscribe to state if only read in callbacks:
+
+```typescript
+// ❌ Incorrect: component re-renders on every URL change
+function Component() {
+  const searchParams = useSearchParams()  // Re-renders on change
+
+  const handleSubmit = () => {
+    const query = searchParams.get('q')  // Used only here
+    submitForm(query)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+
+// ✅ Correct: no re-renders, read directly in callback
+function Component() {
+  const handleSubmit = () => {
+    const query = new URLSearchParams(window.location.search).get('q')
+    submitForm(query)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+### Extract to Memoized Components
+
+**Impact**: Prevents unnecessary re-renders of expensive subtrees
+
+```typescript
+// ❌ Incorrect: entire list re-renders on count change
+function Page() {
+  const [count, setCount] = useState(0)
+  return (
+    <div>
+      <button onClick={() => setCount(c => c + 1)}>{count}</button>
+      <ExpensiveList items={items} /> {/* Re-renders unnecessarily */}
+    </div>
+  )
+}
+
+// ✅ Correct: list doesn't re-render
+const MemoizedList = memo(ExpensiveList)
+
+function Page() {
+  const [count, setCount] = useState(0)
+  return (
+    <div>
+      <button onClick={() => setCount(c => c + 1)}>{count}</button>
+      <MemoizedList items={items} />
+    </div>
+  )
+}
+```
+
+### Narrow Effect Dependencies
+
+**Impact**: Reduces effect re-runs
+
+Extract only needed properties instead of whole objects:
+
+```typescript
+// ❌ Incorrect: effect runs on any user change
+useEffect(() => {
+  logUserActivity(user.id)
+}, [user])  // user object changes often
+
+// ✅ Correct: effect only runs when ID changes
+useEffect(() => {
+  logUserActivity(user.id)
+}, [user.id])  // Stable value
+```
+
+### Subscribe to Derived State
+
+**Impact**: Avoids storing and synchronizing computed values
+
+```typescript
+// ❌ Incorrect: derived state in useState (sync issue)
+const [items, setItems] = useState([])
+const [count, setCount] = useState(0)
+
+useEffect(() => {
+  setCount(items.length)  // Sync issue!
+}, [items])
+
+// ✅ Correct: compute during render
+const [items, setItems] = useState([])
+const count = items.length  // Always in sync
+```
+
+## Rendering Performance
+
+### Hoist Static JSX Elements
+
+**Impact**: Prevents recreation on every render
+
+```typescript
+// ❌ Incorrect: creates new object on every render
+function Component({ title }) {
+  return (
+    <div>
+      <Icon name="check" color="green" />  {/* New object every render */}
+      {title}
+    </div>
+  )
+}
+
+// ✅ Correct: created once
+const CheckIcon = <Icon name="check" color="green" />
+
+function Component({ title }) {
+  return (
+    <div>
+      {CheckIcon}
+      {title}
+    </div>
+  )
+}
+```
+
+### CSS content-visibility for Long Lists
+
+**Impact**: 10× faster initial render
+
+Browser skips layout/paint for off-screen items:
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;  /* Estimated height */
+}
+```
+
+### Use Explicit Conditional Rendering
+
+**Impact**: Prevents rendering unwanted values
+
+Use ternary when condition can be `0` or `NaN`:
+
+```typescript
+// ❌ Incorrect: renders "0" when count is 0
+{count && <div>{count} items</div>}
+
+// ✅ Correct: renders nothing when 0
+{count > 0 && <div>{count} items</div>}
+// or
+{count ? <div>{count} items</div> : null}
+```
+
+### Prevent Hydration Mismatch Without Flickering
+
+**Impact**: No FOUC (Flash of Unstyled Content)
+
+Use synchronous inline script:
+
+```tsx
+function ThemeWrapper({ children }) {
+  return (
+    <>
+      <div id="theme-wrapper">{children}</div>
+      <script dangerouslySetInnerHTML={{__html: `
+        (function() {
+          try {
+            var theme = localStorage.getItem('theme') || 'light';
+            var el = document.getElementById('theme-wrapper');
+            if (el) el.className = theme;
+          } catch (e) {}
+        })();
+      `}} />
+    </>
+  )
+}
+```
+
+### Animate SVG Wrapper Instead of Element
+
+**Impact**: Reduces paint complexity
+
+```typescript
+// ❌ Incorrect: animates SVG element directly
+<svg style={{ transform: `translateX(${x}px)` }}>
+  <path d="..." />
+</svg>
+
+// ✅ Correct: animate wrapper div
+<div style={{ transform: `translateX(${x}px)` }}>
+  <svg><path d="..." /></svg>
+</div>
+```
+
+### Activity Component for Show/Hide
+
+**Impact**: Prevents layout thrashing
+
+```typescript
+// ❌ Incorrect: removes from DOM (layout thrash)
+{isVisible && <ExpensiveComponent />}
+
+// ✅ Correct: uses visibility (keeps layout)
+<div style={{ visibility: isVisible ? 'visible' : 'hidden' }}>
+  <ExpensiveComponent />
+</div>
+```
+
+## Client-Side Optimization
+
+### Use Passive Event Listeners
+
+**Impact**: Eliminates scroll delay
+
+Add `{ passive: true }` to touch/wheel events:
+
+```typescript
+useEffect(() => {
+  const handleScroll = (e: Event) => {
+    // No preventDefault() call
+    updateScrollPosition()
+  }
+
+  // ✅ Passive listener - doesn't block scrolling
+  window.addEventListener('scroll', handleScroll, { passive: true })
+
+  return () => {
+    window.removeEventListener('scroll', handleScroll, { passive: true } as any)
+  }
+}, [])
+```
+
+### Deduplicate Global Event Listeners
+
+**Impact**: N instances = 1 listener instead of N
+
+Use shared hook for global events:
+
+```typescript
+// ❌ Incorrect: N listeners for N components
+function Component() {
+  useEffect(() => {
+    const handler = () => console.log('resize')
+    window.addEventListener('resize', handler)
+    return () => window.removeEventListener('resize', handler)
+  }, [])
+}
+
+// ✅ Correct: 1 listener shared across all instances
+import { useSWRSubscription } from 'swr/subscription'
+
+function useWindowSize() {
+  return useSWRSubscription('window-size', (key, { next }) => {
+    const handler = () => next(null, {
+      width: window.innerWidth,
+      height: window.innerHeight
+    })
+
+    window.addEventListener('resize', handler)
+    handler() // Initial value
+
+    return () => window.removeEventListener('resize', handler)
+  })
+}
+```
+
+### Cache Storage API Calls
+
+**Impact**: Avoids synchronous I/O on every access
+
+```typescript
+// ❌ Incorrect: reads from localStorage on every access
+function useSettings() {
+  const [settings, setSettings] = useState(() => {
+    return JSON.parse(localStorage.getItem('settings') || '{}')
+  })
+
+  // Every time this runs, reads from localStorage
+  const value = localStorage.getItem('key')
+}
+
+// ✅ Correct: cache in memory
+const settingsCache = new Map<string, any>()
+
+function getCachedSetting(key: string) {
+  if (settingsCache.has(key)) {
+    return settingsCache.get(key)
+  }
+
+  const value = localStorage.getItem(key)
+  const parsed = value ? JSON.parse(value) : null
+  settingsCache.set(key, parsed)
+  return parsed
+}
+
+// Invalidate on storage events
+window.addEventListener('storage', (e) => {
+  if (e.key) settingsCache.delete(e.key)
+})
+```
+
+## JavaScript Performance
+
+### Build Index Maps for Repeated Lookups
+
+**Impact**: O(n×m) → O(n+m), 1M ops → 2K ops
+
+```typescript
+// ❌ Incorrect: O(n) per lookup
+return orders.map(order => ({
+  ...order,
+  user: users.find(u => u.id === order.userId)  // O(n) each time
+}))
+
+// ✅ Correct: O(1) per lookup
+const userById = new Map(users.map(u => [u.id, u]))
+return orders.map(order => ({
+  ...order,
+  user: userById.get(order.userId)  // O(1)
+}))
+```
+
+### Cache Property Access in Loops
+
+**Impact**: Avoids repeated property lookups
+
+```typescript
+// ❌ Incorrect: repeated access
+for (let i = 0; i < items.length; i++) {
+  // items.length evaluated each iteration
+}
+
+// ✅ Correct: cached
+const len = items.length
+for (let i = 0; i < len; i++) {
+  // Faster
+}
+```
+
+### Hoist RegExp Creation
+
+**Impact**: Avoids creating regex on every call
+
+```typescript
+// ❌ Incorrect: creates new RegExp every call
+function validate(email: string) {
+  return /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/.test(email)
+}
+
+// ✅ Correct: created once
+const EMAIL_REGEX = /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/
+
+function validate(email: string) {
+  return EMAIL_REGEX.test(email)
+}
+```
+
+### Use toSorted() Instead of sort()
+
+**Impact**: Prevents mutation bugs in React state
+
+```typescript
+// ❌ Incorrect: mutates array
+setItems(items.sort((a, b) => a - b))  // MUTATION BUG
+
+// ✅ Correct: creates new array (Chrome 110+)
+setItems(items.toSorted((a, b) => a - b))
+
+// ✅ Alternative: spread + sort
+setItems([...items].sort((a, b) => a - b))
+```
+
+### Combine Multiple Array Iterations
+
+**Impact**: O(3n) → O(n)
+
+```typescript
+// ❌ Incorrect: 3 passes
+const filtered = items.filter(x => x.active)
+const mapped = filtered.map(x => x.value)
+const result = mapped.slice(0, 10)
+
+// ✅ Correct: 1 pass
+const result = items
+  .filter(x => x.active)
+  .map(x => x.value)
+  .slice(0, 10)
+
+// ✅ Even better: reduce for complex transforms
+const result = items.reduce((acc, item) => {
+  if (item.active && acc.length < 10) {
+    acc.push(item.value)
+  }
+  return acc
+}, [] as number[])
+```
+
+### Use Set/Map for O(1) Lookups
+
+**Impact**: O(n) → O(1)
+
+```typescript
+// ❌ Incorrect: O(n) lookup
+const isAllowed = (id: string) => allowedIds.includes(id)
+
+// ✅ Correct: O(1) lookup
+const allowedSet = new Set(allowedIds)
+const isAllowed = (id: string) => allowedSet.has(id)
+```
+
+### Early Length Check for Array Comparisons
+
+**Impact**: Avoids unnecessary iteration
+
+```typescript
+// ❌ Incorrect: iterates even when lengths differ
+function arraysEqual(a: any[], b: any[]) {
+  return a.every((item, i) => item === b[i])
+}
+
+// ✅ Correct: check length first
+function arraysEqual(a: any[], b: any[]) {
+  if (a.length !== b.length) return false
+  return a.every((item, i) => item === b[i])
+}
+```
+
+## Advanced Patterns
+
+### Store Event Handlers in Refs
+
+**Impact**: Stable references without useCallback
+
+```typescript
+// ❌ Incorrect: needs dependencies
+const handleClick = useCallback(() => {
+  doSomething(prop1, prop2)
+}, [prop1, prop2])  // Changes often
+
+// ✅ Correct: always stable
+const handleClickRef = useRef<() => void>()
+handleClickRef.current = () => {
+  doSomething(prop1, prop2)
+}
+
+const handleClick = useCallback(() => {
+  handleClickRef.current?.()
+}, [])  // Never changes
+```
+
+### useLatest for Stable Callback Refs
+
+**Impact**: Avoids stale closures with stable identity
+
+```typescript
+function useLatest<T>(value: T) {
+  const ref = useRef(value)
+  useEffect(() => {
+    ref.current = value
+  })
+  return ref
+}
+
+// Usage
+function Component({ onEvent }) {
+  const onEventRef = useLatest(onEvent)
+
+  useEffect(() => {
+    const handler = () => onEventRef.current()
+    window.addEventListener('resize', handler)
+    return () => window.removeEventListener('resize', handler)
+  }, [])  // Empty deps, always uses latest
+}
+```
+
+## Anti-Patterns to Avoid
+
+1. ❌ Non-functional setState (stale closures)
+2. ❌ Missing lazy initialization for expensive initial state
+3. ❌ State reads in render when only used in callbacks
+4. ❌ Creating RegExp/objects in render
+5. ❌ Non-passive scroll/touch event listeners
+6. ❌ Multiple array iterations when one would suffice
+7. ❌ Using `&&` for conditional rendering with numbers
+8. ❌ Direct `.sort()` mutation in React state
+9. ❌ Storing derived values in state
+10. ❌ Not extracting expensive components to memo
+
+## React Compiler Note
+
+Many of these optimizations become automatic with React Compiler:
+- Auto-memoization of expensive computations
+- Automatic extraction of stable dependencies
+- Smart re-render optimization
+
+However, architectural patterns (lazy state init, transitions, content-visibility) still require manual implementation.
+
+**Reference**: [Vercel React Best Practices](https://github.com/vercel/react-best-practices)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codihaus/claude-skills",
-  "version": "1.6.19",
+  "version": "1.6.20",
   "description": "Claude Code skills for software development workflow",
   "main": "src/index.js",
   "bin": {