Vercel의 React Best Practices와 Claude Code 활용하기

들어가며

Note:

This document is mainly for agents and LLMs to follow when maintaining, generating, or refactoring React and Next.js codebases at Vercel.

8개 카테고리 한눈에 보기

주요 규칙 살펴보기

1. Eliminating Waterfalls (CRITICAL)

// ❌ 순차 실행: 3번의 왕복
const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

// ✅ 병렬 실행: 1번의 왕복
const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

2. Bundle Size Optimization (CRITICAL)

// ❌ 전체 라이브러리 로드 (1,583 모듈)
import { Check, X, Menu } from 'lucide-react'

// ✅ 필요한 것만 로드 (3 모듈)
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.config.js
module.exports = {
  experimental: {
    optimizePackageImports: ['lucide-react', '@mui/material']
  }
}

3. Server-Side Performance (HIGH)

// ❌ Sidebar가 Header 페칭을 기다림
export default async function Page() {
  const header = await fetchHeader()
  return (
    <div>
      <div>{header}</div>
      <Sidebar />
    </div>
  )
}

// ✅ 둘 다 동시에 페칭
export default function Page() {
  return (
    <div>
      <Header />
      <Sidebar />
    </div>
  )
}

4. Re-render Optimization (MEDIUM)

// ❌ items 의존성 필요, 매번 재생성
const addItem = useCallback((newItem) => {
  setItems([...items, newItem])
}, [items])

// ✅ 의존성 없음, 안정적인 참조
const addItem = useCallback((newItem) => {
  setItems(curr => [...curr, newItem])
}, [])

• 안정적인 콜백 참조 - 상태 변경 시 재생성 불필요

• stale closure 방지 - 항상 최신 상태 값 사용

• 의존성 감소 - 메모리 누수 위험 감소

5. JavaScript Performance (LOW-MEDIUM)

// ❌ O(n) per check
const allowedIds = ['a', 'b', 'c']
items.filter(item => allowedIds.includes(item.id))

// ✅ O(1) per check
const allowedIds = new Set(['a', 'b', 'c'])
items.filter(item => allowedIds.has(item.id))

Claude Code와 함께 사용하기

설치 방법

npm install -g @anthropic-ai/claude-code

your-project/
├── .claude/
│   └── skills/
│       └── vercel-react-best-practices/
│           ├── SKILL.md          # 스킬 정의
│           ├── AGENTS.md         # 전체 가이드 (2,250줄)
│           └── rules/            # 45개 개별 규칙
│               ├── async-parallel.md
│               ├── bundle-barrel-imports.md
│               └── ...
├── src/
└── package.json

---
name: vercel-react-best-practices
description: React and Next.js performance optimization guidelines from Vercel Engineering.
---

AI 시대의 개발 가이드

각 규칙의 구조

### 규칙명
**Impact: CRITICAL/HIGH/MEDIUM/LOW**

간단한 설명

**Incorrect: 문제점 설명**
코드 예시

**Correct: 해결책**
코드 예시

• 명확한 Before/After 비교 - AI가 패턴을 학습하기 쉬움

• 영향도 표시 - 우선순위 판단 가능

• 구체적인 코드 예시 - 즉시 적용 가능

실제 활용 사례

"이 컴포넌트의 성능을 최적화해줘"

1. 폭포수 패턴 감지 → Promise.all() 적용

2. barrel import 발견 → 직접 import로 변경

3. 불필요한 리렌더 감지 → 함수형 setState 적용

4. O(n) 조회 발견 → Set/Map으로 변경

마치며

참고 자료

• React 공식 문서

• Next.js 공식 문서

• Vercel Blog - Package Import 최적화

• Vercel Blog - 대시보드 2배 빠르게 만들기