antigravity-claudekit/skills/ck-react-best-practices/SKILL.md

name, description

name	description
ck-react-best-practices	React and Next.js performance optimization from Vercel Engineering. Use when writing, reviewing, or refactoring React components, data fetching, bundle optimization, or fixing performance issues.

React Best Practices (Vercel)

45 prioritized rules across 8 categories for React and Next.js performance.

When to Use

• Writing new React components or Next.js pages
• Implementing data fetching (client or server-side)
• Reviewing code for performance issues
• Optimizing bundle size or load times
• Refactoring existing React/Next.js code

Don't Use When

• Working with non-React frameworks (Vue, Svelte, Angular)
• Pure Node.js backend code without React

Rules by Priority

1. Eliminating Waterfalls (CRITICAL)

• 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
• async-suspense-boundaries — use Suspense to stream content

2. Bundle Size (CRITICAL)

• bundle-barrel-imports — import directly, avoid barrel files
• bundle-dynamic-imports — use next/dynamic for heavy components
• bundle-defer-third-party — load analytics after hydration
• bundle-conditional — load modules only when feature activated
• bundle-preload — preload on hover/focus for perceived speed

3. Server-Side Performance (HIGH)

• server-cache-react — use React.cache() for per-request dedup
• 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
• server-after-nonblocking — use after() for non-blocking ops

4. Client-Side Data Fetching (MEDIUM-HIGH)

• client-swr-dedup — use SWR for automatic request deduplication
• client-event-listeners — deduplicate global event listeners

5. Re-render Optimization (MEDIUM)

• 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)

• 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-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)

• 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-set-map-lookups — use Set/Map for O(1) lookups
• js-early-exit — return early from functions
• js-hoist-regexp — hoist RegExp creation outside loops

8. Advanced Patterns (LOW)

• advanced-event-handler-refs — store event handlers in refs
• advanced-use-latest — useLatest for stable callback refs

Full Reference

Complete guide with code examples: AGENTS.md

Individual rule files: rules/<rule-name>.md