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:

npx create-next-app@latest

or:

npm create vite@latest

3. Install dependencies:

npm install

4. Start development server:

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:

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