vercel-react-best-practices

Vercel React 모범 사례

React 및 Next.js 애플리케이션을 위한 종합적인 성능 최적화 가이드로, Vercel에서 유지 관리합니다. 영향도별로 우선순위가 지정된 8개 카테고리, 70개의 규칙을 포함하며, 자동 리팩토링 및 코드 생성을 안내합니다.

적용 시기

다음과 같은 경우 이 가이드라인을 참조하세요:

• 새 React 컴포넌트 또는 Next.js 페이지를 작성할 때
• 데이터 페칭(클라이언트 또는 서버 측)을 구현할 때
• 성능 문제를 위해 코드를 검토할 때
• 기존 React/Next.js 코드를 리팩토링할 때
• 번들 크기 또는 로드 시간을 최적화할 때

규칙 카테고리 (우선순위별)

우선순위	카테고리	영향도	접두사
1	워터폴 제거	CRITICAL	async-
2	번들 크기 최적화	CRITICAL	bundle-
3	서버 측 성능	HIGH	server-
4	클라이언트 측 데이터 페칭	MEDIUM-HIGH	client-
5	리렌더링 최적화	MEDIUM	rerender-
6	렌더링 성능	MEDIUM	rendering-
7	JavaScript 성능	LOW-MEDIUM	js-
8	고급 패턴	LOW	advanced-

빠른 참조

1. 워터폴 제거 (CRITICAL)

• async-cheap-condition-before-await - 플래그나 원격 값을 기다리기 전에 저렴한 동기 조건 확인
• async-defer-await - 실제로 사용되는 분기로 await 이동
• async-parallel - 독립적인 작업에 Promise.all() 사용
• async-dependencies - 부분 종속성에 better-all 사용
• async-api-routes - API 라우트에서 프라미스를 일찍 시작하고 늦게 await
• async-suspense-boundaries - Suspense를 사용하여 콘텐츠 스트리밍

2. 번들 크기 최적화 (CRITICAL)

• bundle-barrel-imports - 직접 가져오기, 배럴 파일 피하기
• bundle-analyzable-paths - 정적으로 분석 가능한 import 및 파일 시스템 경로를 선호하여 광범위한 번들과 트레이스 방지
• bundle-dynamic-imports - 무거운 컴포넌트에 next/dynamic 사용
• bundle-defer-third-party - 하이드레이션 후 분석/로깅 로드
• bundle-conditional - 기능이 활성화된 경우에만 모듈 로드
• bundle-preload - 인지된 속도 향상을 위해 호버/포커스 시 사전 로드

3. 서버 측 성능 (HIGH)

• server-auth-actions - API 라우트처럼 서버 액션 인증
• server-cache-react - 요청별 중복 제거를 위해 React.cache() 사용
• server-cache-lru - 요청 간 캐싱을 위해 LRU 캐시 사용
• server-dedup-props - RSC props의 중복 직렬화 방지
• server-hoist-static-io - 정적 I/O(글꼴, 로고)를 모듈 레벨로 호이스팅
• server-no-shared-module-state - RSC/SSR에서 모듈 레벨의 변경 가능한 요청 상태 방지
• server-serialization - 클라이언트 컴포넌트에 전달되는 데이터 최소화
• server-parallel-fetching - 페치를 병렬화하도록 컴포넌트 재구성
• server-parallel-nested-fetching - Promise.all에서 항목별로 중첩 페치 체인 만들기
• server-after-nonblocking - 비차단 작업에 after() 사용

4. 클라이언트 측 데이터 페칭 (MEDIUM-HIGH)

• client-swr-dedup - 자동 요청 중복 제거를 위해 SWR 사용
• client-event-listeners - 전역 이벤트 리스너 중복 제거
• client-passive-event-listeners - 스크롤에 수동 리스너 사용
• client-localstorage-schema - localStorage 데이터 버전 관리 및 최소화

5. 리렌더링 최적화 (MEDIUM)

• rerender-defer-reads - 콜백에서만 사용되는 상태를 구독하지 않음
• rerender-memo - 비용이 많이 드는 작업을 메모이제이션된 컴포넌트로 추출
• rerender-memo-with-default-value - 기본 비원시 props 호이스팅
• rerender-dependencies - effect에 원시 종속성 사용
• rerender-derived-state - 원시 값이 아닌 파생된 불리언 구독
• rerender-derived-state-no-effect - effect가 아닌 렌더링 중에 상태 파생
• rerender-functional-setstate - 안정적인 콜백을 위해 함수형 setState 사용
• rerender-lazy-state-init - 비용이 많이 드는 값에 useState에 함수 전달
• rerender-simple-expression-in-memo - 단순 원시값에 memo 사용 방지
• rerender-split-combined-hooks - 독립적인 종속성을 가진 훅 분리
• rerender-move-effect-to-event - 상호작용 로직을 이벤트 핸들러에 배치
• rerender-transitions - 긴급하지 않은 업데이트에 startTransition 사용
• rerender-use-deferred-value - 값비싼 렌더링을 연기하여 입력 응답성 유지
• rerender-use-ref-transient-values - 일시적인 빈번한 값에 ref 사용
• rerender-no-inline-components - 컴포넌트 내부에 컴포넌트 정의 금지

6. 렌더링 성능 (MEDIUM)

• rendering-animate-svg-wrapper - SVG 요소가 아닌 div 래퍼 애니메이션
• rendering-content-visibility - 긴 목록에 content-visibility 사용
• rendering-hoist-jsx - 정적 JSX를 컴포넌트 외부로 추출
• rendering-svg-precision - SVG 좌표 정밀도 감소
• rendering-hydration-no-flicker - 클라이언트 전용 데이터에 인라인 스크립트 사용
• rendering-hydration-suppress-warning - 예상되는 불일치 억제
• rendering-activity - 표시/숨김에 Activity 컴포넌트 사용
• rendering-conditional-render - 조건부 렌더링에 && 대신 삼항 연산자 사용
• rendering-usetransition-loading - 로딩 상태에 useTransition 선호
• rendering-resource-hints - 사전 로드를 위해 React DOM 리소스 힌트 사용
• rendering-script-defer-async - script 태그에 defer 또는 async 사용

7. JavaScript 성능 (LOW-MEDIUM)

• js-batch-dom-css - 클래스 또는 cssText를 통해 CSS 변경 그룹화
• js-index-maps - 반복 조회를 위해 Map 구축
• js-cache-property-access - 루프에서 객체 속성 캐싱
• js-cache-function-results - 모듈 레벨 Map에 함수 결과 캐싱
• js-cache-storage - localStorage/sessionStorage 읽기 캐싱
• js-combine-iterations - 여러 filter/map을 하나의 루프로 결합
• js-length-check-first - 비용이 많이 드는 비교 전에 배열 길이 확인
• js-early-exit - 함수에서 조기 반환
• js-hoist-regexp - 루프 외부로 RegExp 생성 호이스팅
• js-min-max-loop - sort 대신 루프를 사용하여 최소/최대값 찾기
• js-set-map-lookups - O(1) 조회를 위해 Set/Map 사용
• js-tosorted-immutable - 불변성을 위해 toSorted() 사용
• js-flatmap-filter - flatMap을 사용하여 매핑과 필터링을 한 번에 수행
• js-request-idle-callback - 중요하지 않은 작업을 브라우저 유휴 시간으로 연기

8. 고급 패턴 (LOW)

• advanced-effect-event-deps - useEffectEvent 결과를 effect 종속성에 넣지 않음
• advanced-event-handler-refs - 이벤트 핸들러를 ref에 저장
• advanced-init-once - 앱 로드당 한 번만 앱 초기화
• advanced-use-latest - 안정적인 콜백 ref를 위해 useLatest

사용 방법

자세한 설명과 코드 예시는 개별 규칙 파일을 참조하세요:

rules/async-parallel.md
rules/bundle-barrel-imports.md

각 규칙 파일에는 다음이 포함됩니다:

• 중요한 이유에 대한 간략한 설명
• 설명이 포함된 잘못된 코드 예시
• 설명이 포함된 올바른 코드 예시
• 추가 컨텍스트 및 참조

전체 컴파일 문서

모든 규칙이 확장된 전체 가이드는 다음을 참조하세요: AGENTS.md