Introducing: React Best Practices - Vercel
핵심 포인트
- 1이 문서는 React 및 Next.js 애플리케이션의 고질적인 성능 문제를 해결하기 위해 10년 이상의 최적화 지식을 집대성한 `react-best-practices` 저장소를 소개합니다.
- 2이 프레임워크는 async waterfalls 제거 및 bundle size 최적화를 포함한 8가지 카테고리의 40개 이상 규칙을 영향도(CRITICAL-LOW)에 따라 정리하고 코드 예시를 제공합니다.
- 3`react-best-practices`는 `AGENTS.md` 파일로 컴파일되어 AI agents가 코드 검토 및 최적화 제안에 활용될 수 있도록 설계되었으며, `Opencode`, `Codex` 등 다양한 코딩 에이전트에서 Agent Skills로도 사용 가능합니다.
react-best-practices는 10년 이상의 React 및 Next.js 최적화 노하우를 집약하여 AI 에이전트 및 LLM에 최적화된 형태로 제공하는 구조화된 저장소입니다. 기존의 React 성능 작업이 대개 "반응적(reactive)"으로 이루어져 앱 릴리스 후 성능 저하가 발생하면 증상을 추적하고 비용이 많이 드는 잘못된 최적화를 시도하는 경향이 있었습니다. 이 문서에 따르면 지난 10년간 프로덕션 코드베이스에서 반복적으로 발견된 주요 성능 저하 원인은 다음과 같습니다:
- 의도치 않게 순차적으로 실행되는 비동기(Async) 작업
- 시간이 지남에 따라 커지는 클라이언트 번들(Bundle) 크기
- 불필요하게 과도하게 리렌더링(re-render)되는 컴포넌트
이러한 문제들은 단순한 미세 최적화(micro-optimizations)가 아니라 사용자 세션마다 대기 시간(waiting time), 버벅임(jank), 반복적인 비용을 발생시키는 근본적인 원인으로 작용합니다.
핵심 방법론 (Core Methodology): 최적화 순서 (Ordering)
이 프레임워크의 핵심 아이디어는 성능 최적화 작업을 수행하는 "순서"에 있습니다. 대부분의 성능 작업이 실패하는 이유는 너무 낮은 스택(low in the stack)에서 시작하기 때문입니다. 예를 들어, 요청 워터폴(request waterfall)이 600ms의 대기 시간을 추가한다면 useMemo 호출을 아무리 최적화하더라도 큰 의미가 없으며, 매 페이지마다 300KB의 JavaScript가 추가로 로드된다면 루프(loop)의 몇 마이크로초를 줄이는 것은 중요하지 않습니다. 성능 작업은 또한 누적(compounding)됩니다. 오늘 발생한 작은 성능 저하(regression)는 누군가가 해당 "기술 부채(technical debt)"를 해결하기 전까지 모든 사용자 세션에 장기적인 부담을 줍니다.
따라서 이 프레임워크는 실제 사용자 지표(real-world metrics)에 가장 먼저 영향을 미치는 두 가지 CRITICAL(치명적) 중요도의 최적화부터 시작합니다. 이 두 가지는 종종 request waterfall과 bundle size와 같은 네트워크 및 로딩 단계의 최적화를 의미합니다.
- 워터폴 제거 (Eliminate Waterfalls): 네트워크 요청이 불필요하게 순차적으로 발생하는 패턴을 병렬화하여 총 대기 시간을 줄이는 것을 목표로 합니다. 예를 들어, 서로 의존성이 없는 비동기 작업들을
Promise.all과 같이 병렬로 실행하여await체인으로 인한 지연을 방지합니다. 문서에 제시된 잘못된 코드 예시(Incorrect)는 비록skipProcessing이true일지라도fetchUserData를 항상await하여 불필요한 네트워크 지연을 발생시킵니다. 올바른 코드(Correct)는skipProcessing조건이 참일 경우fetchUserData호출을 완전히 생략하여async waterfall을 제거합니다. 이는Critical등급의 최적화입니다.- Incorrect (blocks both branches):
async function handleRequest(userId: string, skipProcessing: boolean) {
const userData = await fetchUserData(userId); // Always waits
if (skipProcessing) {
return { skipped: true };
}
return processUserData(userData);
}- Correct (only blocks when needed):
async function handleRequest(userId: string, skipProcessing: boolean) {
if (skipProcessing) {
return { skipped: true };
}
const userData = await fetchUserData(userId); // Waits only if needed
return processUserData(userData);
}- 번들 크기 축소 (Reduce Bundle Size): 웹 애플리케이션의 초기 로드 시간을 결정하는 핵심 요소입니다. 불필요한 코드, 중복된 라이브러리, 거대한 의존성을 제거하거나 코드 스플리팅(code splitting), 트리 쉐이킹(tree-shaking) 등을 통해 클라이언트에 전송되는 JavaScript, CSS, 기타 자원의 양을 줄입니다. 이는
Critical등급의 최적화입니다.
이후 프레임워크는 서버 측 성능(Server-side performance), 클라이언트 측 데이터 패칭(Client-side data fetching), 그리고 리렌더링 최적화(Re-render optimization) 순으로 진행됩니다.
저장소 구성 및 내용
react-best-practices 저장소는 8가지 성능 카테고리(Categories)에 걸쳐 40개 이상의 규칙(Rules)을 포함하며, 각 규칙은 CRITICAL부터 LOW까지의 impact rating을 가집니다.
- Eliminating async waterfalls (비동기 워터폴 제거)
- Bundle size optimization (번들 크기 최적화)
- Server-side performance (서버 측 성능)
- Client-side data fetching (클라이언트 측 데이터 패칭)
- Re-render optimization (리렌더링 최적화)
- Rendering performance (렌더링 성능)
- Advanced patterns (고급 패턴)
- JavaScript performance (JavaScript 성능)
각 규칙은 impact rating 외에도 "무엇이 잘못되었는지(what breaks)"와 "어떻게 고치는지(how to fix it)"를 보여주는 코드 예시(code examples)를 포함합니다. 개별 규칙 파일들은 AGENTS.md라는 단일 문서로 컴파일되어 AI 에이전트가 코드 리뷰나 최적화 제안 시 활용할 수 있도록 설계되었습니다. 이는 AI 에이전트를 포함하여 팀 전체가 일관된 의사 결정을 대규모 코드베이스에 적용할 수 있도록 돕습니다.
지식 수집 방법론
이러한 모범 사례들은 이론적인 것이 아니라 실제 프로덕션 코드베이스에서의 성능 작업 경험에서 수집되었습니다. 구체적인 사례로는:
- 루프 반복 결합 (Combining loop iterations): 채팅 페이지에서 메시지 목록을 8번 개별적으로 스캔하던 것을 단일 패스(single pass)로 결합하여 수천 개의 메시지가 있을 때 발생하는 성능 오버헤드를 줄였습니다.
- await 병렬화 (Parallelizing awaits): API가 독립적인 여러 데이터베이스 호출을 순차적으로 기다리던 것을 동시에 실행하여 총 대기 시간을 절반으로 단축했습니다.
- 폰트 폴백 튜닝 (Tuning font fallbacks): 커스텀 폰트 로드 전 시스템 폰트 사용 시 헤드라인이 답답해 보이던 것을
letter-spacing조정을 통해 의도적인 디자인처럼 보이도록 개선했습니다.
코딩 에이전트 활용
이러한 베스트 프랙티스는 Opencode, Codex, Claude Code, Cursor 등 다양한 코딩 에이전트에 설치할 수 있는 "Agent Skills"로 패키징되어 제공됩니다. 에이전트가 연쇄적인 useEffect 호출이나 무거운 클라이언트 측 임포트(imports)를 감지하면, 이 패턴들을 참조하여 해결책을 제안할 수 있습니다. npx add-skill vercel-labs/agent-skills 명령어를 통해 쉽게 통합할 수 있습니다.