vercel-react-best-practices

# Vercel React Best Practices ## Overview This skill enables Claude to build and review React applications using modern frontend engineering standards inspired by high-quality production workflows. The workflow focuses on: - readable React architecture - maintainable component systems - performance optimization - stable rendering behavior - edge-case handling - scalable frontend structure - production-ready UI patterns The goal is to ensure React projects remain: - clean - predictable - scalable - performant - easy to review and maintain This workflow emphasizes long-term maintainability over short-term hacks or overly clever abstractions. --- # Setup Before starting: 1. Install Node.js: https://nodejs.org 2. Create a React or Next.js project: ```bash npx create-next-app@latest ``` or: ```bash npm create vite@latest ``` 3. Install dependencies: ```bash npm install ``` 4. Start development server: ```bash npm run dev ``` Recommended tools: - VS Code - TypeScript - ESLint - Prettier - React DevTools Recommended extensions: - ES7 React snippets - Prettier - Tailwind CSS IntelliSense - Error Lens --- # Inputs Required - React project or component system - UI requirements - Application structure - State management requirements Optional: - Design system - Existing component library - API contracts - Performance requirements --- # When to Use This Skill Use this skill when: - building React applications - reviewing frontend code - designing scalable component systems - optimizing frontend performance - improving maintainability - handling complex UI states - creating production-ready frontend architecture --- # When NOT to Use Do NOT use this skill for: - quick throwaway prototypes - non-React projects - static HTML-only workflows - highly experimental one-off demos --- # Example Use Case > Build a scalable dashboard interface for a SaaS product. Claude should: 1. Create reusable component architecture 2. Keep component logic readable 3. Prevent unnecessary re-renders 4. Handle loading and error states correctly 5. Optimize rendering performance 6. Ensure accessibility and maintainability 7. Validate edge-case behavior Final result should: - remain easy to scale - feel performant - avoid unstable UI behavior - maintain clean architecture - support long-term development --- # Core React Principles ## 1. Prioritize Readability Readable code is more valuable than overly clever abstractions. Components should: - remain understandable - have clear responsibilities - avoid excessive nesting - use predictable naming Good readability improves: - onboarding - debugging - reviews - long-term maintenance Avoid: - deeply nested logic - overly abstract hooks - unnecessary complexity - confusing state flow --- ## 2. Keep Components Focused Each component should have a single clear responsibility. Good component design: - isolates concerns - improves reusability - simplifies testing - reduces side effects Preferred structure: - UI components - logic hooks - utility functions - shared primitives Avoid: - massive monolithic components - mixed responsibilities - tightly coupled logic --- ## 3. Optimize Rendering Performance React applications should minimize unnecessary rendering work. Common optimization strategies: - memoization - component splitting - stable props - efficient state updates - lazy loading Claude should proactively prevent: - excessive re-renders - unstable object creation - unnecessary derived state - large render trees Performance improves: - responsiveness - scalability - perceived quality --- ## 4. Handle Edge Cases Explicitly Production applications require robust state handling. Always account for: - loading states - empty states - failed requests - invalid inputs - partial data - asynchronous race conditions Stable UI systems should fail gracefully. Avoid: - undefined rendering assumptions - unhandled async behavior - fragile conditional rendering --- ## 5. Maintain Predictable State Flow State management should remain: - centralized when necessary - localized when possible - easy to trace - easy to debug Preferred approaches: - colocated state - predictable hooks - derived values - controlled updates Avoid: - duplicated state - deeply chained prop drilling - unpredictable side effects --- ## 6. Build Reusable UI Systems Reusable systems improve scalability significantly. Preferred patterns: - shared UI primitives - consistent spacing systems - reusable layouts - centralized design tokens Good systems improve: - development speed - consistency - maintainability --- # Workflow ## 1. Define Application Structure Start by identifying: - pages - layouts - reusable components - shared logic - API boundaries Recommended structure: ```plaintext components/ hooks/ lib/ pages/ styles/ ``` Keep the architecture: - predictable - modular - scalable --- ## 2. Build Reusable Components Create: - buttons - cards - inputs - modals - layout primitives Each component should: - remain isolated - support reuse - expose clean props - avoid tightly coupled logic --- ## 3. Handle State Carefully Separate: - server state - local UI state - derived values - async operations Validate: - loading behavior - error handling - optimistic updates - race conditions Keep state transitions predictable. --- ## 4. Optimize Performance Check for: - unnecessary re-renders - unstable props - large component trees - blocking operations Use: - `React.memo` - lazy loading - dynamic imports - memoized calculations Optimize only where necessary. Avoid premature optimization. --- ## 5. Improve Accessibility Ensure: - keyboard navigation - semantic HTML - proper labels - focus management - screen-reader compatibility Accessibility improves: - usability - maintainability - production quality --- ## 6. Validate Edge Cases Before shipping validate: - empty states - slow network behavior - failed API responses - invalid user inputs - mobile responsiveness Production-quality applications should remain stable under imperfect conditions. --- ## 7. Review & Refine Review: - readability - component complexity - rendering behavior - maintainability - architectural consistency Refactor: - duplicated logic - overly complex components - unstable abstractions --- # Output Expectations The final output should include: - clean React architecture - reusable component systems - stable rendering behavior - optimized performance - robust edge-case handling - production-ready frontend quality The workflow itself should remain: - scalable - maintainable - readable - team-friendly - easy to review --- # Execution Strategy (for AI agents) The agent should: 1. Prioritize readability over unnecessary abstraction 2. Keep components focused and modular 3. Detect performance issues proactively 4. Handle edge cases explicitly 5. Maintain predictable state flow 6. Optimize for long-term maintainability The workflow should optimize for: - frontend stability - rendering performance - maintainability - developer experience - scalability --- # Best Practices - Keep components small and focused - Avoid unnecessary abstraction layers - Handle loading and error states explicitly - Prevent unnecessary re-renders - Use semantic HTML - Prefer composition over complexity - Validate edge cases before shipping --- # Notes - Readability compounds over long projects - Stable React architecture improves team velocity - Most frontend instability comes from poor state management - Explicit edge-case handling dramatically improves reliability - Good component systems scale better than ad-hoc implementations