vercel-react-best-practices

name	vercel-react-best-practices
description	Workflow for building production-quality React applications using Vercel-style best practices focused on readability, performance, maintainability, and stable UI behavior.

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