Vercel React 모범 사례
Vercel이 유지 관리하는 React 및 Next.js 애플리케이션을 위한 종합적인 성능 최적화 가이드입니다. 8개 카테고리, 70개의 규칙을 포함하며 영향도에 따라 우선순위가 지정되어 자동 리팩토링 및 코드 생성을 안내합니다.
적용 시점
다음 상황에서 이 가이드라인을 참고하세요:
- 새 React 컴포넌트나 Next.js 페이지를 작성할 때
- 데이터 페칭(클라이언트 또는 서버 측)을 구현할 때
- 성능 문제로 코드를 리뷰할 때
- 기존 React/Next.js 코드를 리팩토링할 때
- 번들 크기나 로드 시간을 최적화할 때
우선순위별 규칙 카테고리
| 우선순위 | 카테고리 | 영향도 | 접두사 |
|---|---|---|---|
| 1 | 워터폴 제거 | 치명적 | async- |
| 2 | 번들 크기 최적화 | 치명적 | bundle- |
| 3 | 서버 측 성능 | 높음 | server- |
| 4 | 클라이언트 측 데이터 페칭 | 중간-높음 | client- |
| 5 | 리렌더링 최적화 | 중간 | rerender- |
| 6 | 렌더링 성능 | 중간 | rendering- |
| 7 | JavaScript 성능 | 낮음-중간 | js- |
| 8 | 고급 패턴 | 낮음 | advanced- |
빠른 참조
1. 워터폴 제거 (치명적)
async-cheap-condition-before-await- 플래그나 원격 값을 기다리기 전에 저렴한 동기 조건을 먼저 확인async-defer-await- await을 실제로 사용되는 분기 안으로 이동async-parallel- 독립적인 작업에는 Promise.all() 사용async-dependencies- 부분 의존성에는 better-all 사용async-api-routes- API 라우트에서 Promise를 일찍 시작하고 늦게 awaitasync-suspense-boundaries- Suspense를 사용해 콘텐츠 스트리밍
2. 번들 크기 최적화 (치명적)
bundle-barrel-imports- 배럴 파일 대신 직접 가져오기bundle-analyzable-paths- 정적으로 분석 가능한 가져오기 및 파일 시스템 경로 사용으로 넓은 번들 및 트레이스 방지bundle-dynamic-imports- 무거운 컴포넌트에는 next/dynamic 사용bundle-defer-third-party- 분석/로깅은 하이드레이션 이후에 로드bundle-conditional- 기능이 활성화될 때만 모듈 로드bundle-preload- 인지된 속도 향상을 위해 호버/포커스 시 사전 로드
3. 서버 측 성능 (높음)
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. 클라이언트 측 데이터 페칭 (중간-높음)
client-swr-dedup- 자동 요청 중복 제거에 SWR 사용client-event-listeners- 전역 이벤트 리스너 중복 제거client-passive-event-listeners- 스크롤에는 수동 리스너 사용client-localstorage-schema- localStorage 데이터 버전 관리 및 최소화
5. 리렌더링 최적화 (중간)
rerender-defer-reads- 콜백에서만 사용되는 상태를 구독하지 않기rerender-memo- 비용이 큰 작업을 메모이제이션된 컴포넌트로 추출rerender-memo-with-default-value- 기본 비원시 타입 props 호이스팅rerender-dependencies- 이펙트에서 원시 타입 의존성 사용rerender-derived-state- 가공된 불리언 값 구독, 원시 값 구독 피하기rerender-derived-state-no-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. 렌더링 성능 (중간)
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 성능 (낮음-중간)
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- 정렬 대신 루프로 최소/최대값 찾기js-set-map-lookups- O(1) 조회를 위해 Set/Map 사용js-tosorted-immutable- 불변성을 위해 toSorted() 사용js-flatmap-filter- flatMap으로 매핑과 필터링을 한 번에 처리js-request-idle-callback- 중요하지 않은 작업을 브라우저 유휴 시간으로 지연
8. 고급 패턴 (낮음)
advanced-effect-event-deps-useEffectEvent결과를 이펙트 의존성에 넣지 않기advanced-event-handler-refs- 이벤트 핸들러를 ref에 저장advanced-init-once- 앱 로드당 한 번 초기화advanced-use-latest- 안정적인 콜백 ref를 위해 useLatest 사용
사용 방법
자세한 설명과 코드 예제는 각 규칙 파일을 읽어보세요:
rules/async-parallel.md
rules/bundle-barrel-imports.md
각 규칙 파일에는 다음이 포함됩니다:
- 규칙이 중요한 이유에 대한 간략한 설명
- 잘못된 코드 예제와 설명
- 올바른 코드 예제와 설명
- 추가 컨텍스트 및 참고 자료
전체 문서
모든 규칙이 확장된 전체 가이드는 AGENTS.md를 참조하세요.