React Best Practices 소개

React 성능 개선 작업은 대개 사후 대응식으로 이루어집니다. 릴리스를 배포하고 나서 앱이 느려진 게 느껴지면 그제야 팀이 증상을 쫓기 시작하는 방식이죠. 비용이 많이 들 뿐 아니라, 정작 중요하지 않은 부분을 최적화하는 실수도 흔합니다.

10년 넘게 수많은 프로덕션 코드베이스를 살펴보면서 동일한 근본 원인들을 반복해서 발견했습니다:

• 의도치 않게 순차적으로 실행되는 비동기 작업

• 시간이 지날수록 점점 커지는 클라이언트 번들

• 불필요하게 반복되는 컴포넌트 리렌더링

이유는 간단합니다. 이것들은 미세 최적화 문제가 아닙니다. 매 사용자 세션마다 체감되는 대기 시간, 화면 끊김, 반복 비용으로 직결되는 문제들입니다.

이러한 문제들을 더 쉽게 파악하고 빠르게 해결할 수 있도록 React 모범 사례(best practices) 프레임워크를 정리했습니다.

핵심 개념: 우선순위

대부분의 성능 개선 작업이 실패하는 이유는 스택의 너무 낮은 단계에서 시작하기 때문입니다.

요청 워터폴(waterfall)로 600ms의 대기 시간이 발생한다면, useMemo 호출을 아무리 최적화해도 소용없습니다. 매 페이지마다 300KB의 자바스크립트를 추가로 전송하고 있다면, 루프에서 마이크로초 몇 개를 줄인다고 달라지는 건 없습니다.

성능 문제는 복리처럼 쌓입니다. 오늘 배포한 작은 성능 저하는 누군가 해결하기 전까지 모든 세션에 누적되는 장기적인 비용이 됩니다.

이 프레임워크가 실제 지표를 가장 크게 개선하는 두 가지 수정 사항부터 시작하는 이유가 여기 있습니다:

1. 워터폴 제거

2. 번들 크기 축소

이후에는 서버 사이드 성능, 클라이언트 사이드 데이터 패칭(fetching), 리렌더링 최적화로 이어집니다.

8개 카테고리에 걸쳐 40개 이상의 규칙을 수록했으며, 영향도 순으로 정렬되어 있습니다. CRITICAL(워터폴 제거, 번들 크기 축소)부터 점진적 개선(고급 패턴)까지 단계적으로 구성했습니다. ‍​‌ ‌ ‌

그 밖에 무엇이 있나요?

리포지터리는 여덟 가지 성능 카테고리를 다룹니다:

• 비동기 워터폴 제거

• 번들 크기 최적화

• 서버 사이드 성능

• 클라이언트 사이드 데이터 패칭

• 리렌더링 최적화

• 렌더링 성능

• 고급 패턴

• 자바스크립트 성능

각 규칙에는 수정 우선순위 결정에 도움이 되는 영향도 등급(CRITICAL~LOW)과 함께, 어떤 코드가 문제를 일으키는지와 해결 방법을 보여주는 코드 예시가 포함되어 있습니다.

예를 들어, 미사용 코드를 블로킹하는 흔한 패턴을 살펴보겠습니다:

잘못된 예시 (두 분기 모두 블로킹):

1
async function handleRequest(userId: string, skipProcessing: boolean) {
2
  const userData = await fetchUserData(userId)
3
  
4
  if (skipProcessing) {
5
    // Returns immediately but still waited for userData
6
    return { skipped: true }
7
  }
8
  
9
  // Only this branch uses userData
10
  return processUserData(userData)
11
}

올바른 예시 (필요할 때만 블로킹):

1
async function handleRequest(
2
  userId: string,
3
  skipProcessing: boolean
4
) {
5
  if (skipProcessing) {
6
    return { skipped: true }
7
  }
8

9
  const userData = await fetchUserData(userId)
10
  return processUserData(userData)
11
}
12

개별 규칙 파일들은 AGENTS.md라는 단일 문서로 컴파일됩니다. 에이전트가 코드 리뷰나 최적화 제안 시 참조할 수 있도록 설계되었으며, 리팩터링을 수행하는 AI 에이전트를 포함해 일관되게 따를 수 있기 때문에 팀 전체가 대규모 코드베이스에서도 동일한 기준을 적용할 수 있습니다.

이 모범 사례는 어떻게 수집되었나요?

이론이 아닙니다. 실제 프로덕션 코드베이스에서 직접 수행한 성능 개선 작업에서 나온 것들입니다.

몇 가지 예시를 소개합니다:

루프 순회 합치기

채팅 페이지에서 동일한 메시지 목록을 여덟 번씩 별도로 순회하고 있었습니다. 이를 단일 패스(pass)로 통합했고, 수천 개의 메시지가 쌓일수록 그 효과가 극대화되었습니다.

비동기 병렬 처리

서로 의존 관계가 없는데도 한 데이터베이스 호출이 끝나야 다음 호출을 시작하는 API가 있었습니다. 이를 동시에 실행하도록 바꾸자 전체 대기 시간이 절반으로 줄었습니다.

지연 상태 초기화(Lazy State Initialization)

한 컴포넌트가 상태 초기화 시 한 번만 필요한 JSON 설정을 매 렌더링마다 localStorage에서 파싱하고 있었습니다. 이를 콜백(useState(() => JSON.parse(...)))으로 감싸는 것만으로 불필요한 연산을 제거할 수 있었습니다.

코딩 에이전트에서 react-best-practices 활용하기

이 모범 사례들은 Agent Skills 형태로 패키징되어 Opencode, Codex, Claude Code, Cursor를 비롯한 다양한 코딩 에이전트에 설치할 수 있습니다. 에이전트가 연쇄적인 useEffect 호출이나 무거운 클라이언트 사이드 임포트를 감지하면, 이 패턴들을 참조해 수정 방안을 제안합니다.

1
npx skills add vercel-labs/agent-skills

react-best-practices 리포지터리를 확인해 보세요.