@kood/claude-code 0.3.11 → 0.3.14

package/templates/.claude/skills/nextjs-react-best-practices/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: nextjs-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Next.js React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+---
+
+<communication>
+
+## User Communication
+
+**IMPORTANT: Always communicate with the user in Korean (한국어), even though this document is in English.**
+
+When:
+- Asking questions
+- Providing summaries
+- Explaining decisions
+- Reporting progress
+
+Use Korean for all user-facing communication while applying these English guidelines internally.
+
+</communication>
+
+---
+
+<when_to_use>
+
+## When to Apply
+
+| Situation | Description |
+|-----------|-------------|
+| **Writing Components** | Creating new React components or Next.js pages |
+| **Data Fetching** | Implementing client-side or server-side data fetching |
+| **Code Review** | Reviewing code for performance issues |
+| **Refactoring** | Improving existing React/Next.js code |
+| **Optimization** | Optimizing bundle size or load times |
+
+</when_to_use>
+
+---
+
+<categories>
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | **CRITICAL** | `async-` |
+| 2 | Bundle Size Optimization | **CRITICAL** | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+</categories>
+
+---
+
+<rules>
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+| Rule | Description |
+|------|-------------|
+| `async-defer-await` | Move await into branches where actually used |
+| `async-parallel` | Use Promise.all() for independent operations |
+| `async-dependencies` | Use better-all for partial dependencies |
+| `async-api-routes` | Start promises early, await late in API routes |
+| `async-suspense-boundaries` | Use Suspense to stream content |
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+| Rule | Description |
+|------|-------------|
+| `bundle-barrel-imports` | Import directly, avoid barrel files |
+| `bundle-dynamic-imports` | Use next/dynamic for heavy components |
+| `bundle-defer-third-party` | Load analytics/logging after hydration |
+| `bundle-conditional` | Load modules only when feature is activated |
+| `bundle-preload` | Preload on hover/focus for perceived speed |
+
+### 3. Server-Side Performance (HIGH)
+
+| Rule | Description |
+|------|-------------|
+| `server-cache-react` | Use React.cache() for per-request deduplication |
+| `server-cache-lru` | Use LRU cache for cross-request caching |
+| `server-serialization` | Minimize data passed to client components |
+| `server-parallel-fetching` | Restructure components to parallelize fetches |
+| `server-after-nonblocking` | Use after() for non-blocking operations |
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+| Rule | Description |
+|------|-------------|
+| `client-swr-dedup` | Use SWR for automatic request deduplication |
+| `client-event-listeners` | Deduplicate global event listeners |
+
+### 5. Re-render Optimization (MEDIUM)
+
+| Rule | Description |
+|------|-------------|
+| `rerender-defer-reads` | Don't subscribe to state only used in callbacks |
+| `rerender-memo` | Extract expensive work into memoized components |
+| `rerender-dependencies` | Use primitive dependencies in effects |
+| `rerender-derived-state` | Subscribe to derived booleans, not raw values |
+| `rerender-functional-setstate` | Use functional setState for stable callbacks |
+| `rerender-lazy-state-init` | Pass function to useState for expensive values |
+| `rerender-transitions` | Use startTransition for non-urgent updates |
+
+### 6. Rendering Performance (MEDIUM)
+
+| Rule | Description |
+|------|-------------|
+| `rendering-animate-svg-wrapper` | Animate div wrapper, not SVG element |
+| `rendering-content-visibility` | Use content-visibility for long lists |
+| `rendering-hoist-jsx` | Extract static JSX outside components |
+| `rendering-svg-precision` | Reduce SVG coordinate precision |
+| `rendering-hydration-no-flicker` | Use inline script for client-only data |
+| `rendering-activity` | Use Activity component for show/hide |
+| `rendering-conditional-render` | Use ternary, not && for conditionals |
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+| Rule | Description |
+|------|-------------|
+| `js-batch-dom-css` | Group CSS changes via classes or cssText |
+| `js-index-maps` | Build Map for repeated lookups |
+| `js-cache-property-access` | Cache object properties in loops |
+| `js-cache-function-results` | Cache function results in module-level Map |
+| `js-cache-storage` | Cache localStorage/sessionStorage reads |
+| `js-combine-iterations` | Combine multiple filter/map into one loop |
+| `js-length-check-first` | Check array length before expensive comparison |
+| `js-early-exit` | Return early from functions |
+| `js-hoist-regexp` | Hoist RegExp creation outside loops |
+| `js-min-max-loop` | Use loop for min/max instead of sort |
+| `js-set-map-lookups` | Use Set/Map for O(1) lookups |
+| `js-tosorted-immutable` | Use toSorted() for immutability |
+
+### 8. Advanced Patterns (LOW)
+
+| Rule | Description |
+|------|-------------|
+| `advanced-event-handler-refs` | Store event handlers in refs |
+| `advanced-use-latest` | useLatest for stable callback refs |
+
+</rules>
+
+---
+
+<patterns>
+
+## Core Patterns
+
+### ✅ Eliminate Waterfalls
+
+```typescript
+// ❌ Sequential execution, 3 round trips
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+
+// ✅ Parallel execution, 1 round trip
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### ✅ Bundle Optimization
+
+```tsx
+// ❌ Import entire library (1583 modules, ~2.8s)
+import { Check, X, Menu } from 'lucide-react'
+
+// ✅ Direct imports (3 modules only)
+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'
+
+// ✅ Next.js 13.5+ auto-optimization
+// next.config.js
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react']
+  }
+}
+```
+
+### ✅ Server Caching
+
+```typescript
+import { cache } from 'react'
+
+// Per-request deduplication
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({ where: { id: session.user.id } })
+})
+```
+
+### ✅ Re-render Optimization
+
+```tsx
+// ❌ items as dependency, recreated every time
+const addItems = useCallback((newItems: Item[]) => {
+  setItems([...items, ...newItems])
+}, [items])
+
+// ✅ Stable callback, never recreated
+const addItems = useCallback((newItems: Item[]) => {
+  setItems(curr => [...curr, ...newItems])
+}, [])
+```
+
+</patterns>
+
+---
+
+<usage>
+
+## Usage
+
+**Detailed rules and examples:**
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+rules/_sections.md
+```
+
+Each rule file contains:
+- ❌ Incorrect code example with explanation
+- ✅ Correct code example with explanation
+- Additional context and references
+- Why it matters
+
+**Full compiled document:** `AGENTS.md`
+
+</usage>
+
+---
+
+<references>
+
+## References
+
+1. [React](https://react.dev)
+2. [Next.js](https://nextjs.org)
+3. [SWR](https://swr.vercel.app)
+4. [better-all](https://github.com/shuding/better-all)
+5. [node-lru-cache](https://github.com/isaacs/node-lru-cache)
+6. [Next.js Package Import Optimization](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [How We Made the Vercel Dashboard Twice as Fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+
+</references>

package/templates/.claude/skills/nextjs-react-best-practices/rules/advanced-event-handler-refs.md

@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+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: () => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: () => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = () => handlerRef.current()
+    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: () => 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.

package/templates/.claude/skills/nextjs-react-best-practices/rules/advanced-use-latest.md

@@ -0,0 +1,49 @@
+---
+title: useLatest for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useLatest, refs, optimization
+---
+
+## useLatest for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Implementation:**
+
+```typescript
+function useLatest<T>(value: T) {
+  const ref = useRef(value)
+  useEffect(() => {
+    ref.current = value
+  }, [value])
+  return ref
+}
+```
+
+**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 (stable effect, fresh callback):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchRef = useLatest(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchRef.current(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```

package/templates/.claude/skills/nextjs-react-best-practices/rules/async-api-routes.md

@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+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 (auth and config start immediately):**
+
+```typescript
+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 })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).

package/templates/.claude/skills/nextjs-react-best-practices/rules/async-defer-await.md

@@ -0,0 +1,80 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (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: fetches only when needed
+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)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.

package/templates/.claude/skills/nextjs-react-best-practices/rules/async-dependencies.md

@@ -0,0 +1,36 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+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)
+  }
+})
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)

package/templates/.claude/skills/nextjs-react-best-practices/rules/async-parallel.md

@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```

package/templates/.claude/skills/nextjs-react-best-practices/rules/async-suspense-boundaries.md

@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.