React Compiler 설정

01무엇

컴파일러의 동작은 옵션 객체로 바꾼다. Babel 플러그인의 두 번째 인자로 넘긴다.

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      // 여기에 옵션
    }],
  ],
}

기본값으로도 대부분 동작한다. 옵션은 도입 범위를 좁히거나, 낮은 React 버전을 노리거나, 빌드 실패 정책을 정할 때 손댄다.

02무슨 일이 일어나나

각 옵션은 컴파일 파이프라인의 다른 단계를 건드린다. compilationMode는 어떤 함수를 컴파일할지 고르는 규칙이고, target은 어느 React 버전에 맞춰 코드를 낼지 정한다. panicThreshold는 규칙 위반을 만났을 때 어떻게 할지(빌드를 멈출지, 그 컴포넌트만 건너뛸지)를 결정한다.

03사용법

주요 옵션은 다음과 같다.

• compilationMode — 컴파일 대상 선정 방식. 'annotation'은 "use memo"가 붙은 함수만, 'infer'는 컴파일러가 스스로 판단(지시어가 우선), 'all'은 전부 컴파일한다.
• target — 노리는 React 버전. '17'·'18'·'19' 중 하나. 17·18을 노리면 react-compiler-runtime 패키지가 필요하다.
• panicThreshold — 규칙을 어긴 컴포넌트 처리. 'none'이면 빌드를 멈추지 않고 그 컴포넌트만 최적화에서 뺀다. 프로덕션에 권장된다.
• logger — 컴파일 이벤트를 받아 커스텀 로깅. logEvent(filename, event) 형태.
• gating — 런타임 피처 플래그로 점진 출시나 A/B 테스트를 붙일 때. source와 importSpecifierName을 준다.

04실무 예시

기존 코드베이스에 처음 들일 때 흔한 설정이다. 표시한 함수만 컴파일하고(annotation), 문제가 있어도 빌드는 멈추지 않게(panicThreshold: 'none') 둔다.

module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      compilationMode: 'annotation', // "use memo" 붙인 함수만
      panicThreshold: 'none',        // 문제 컴포넌트는 건너뛰고 빌드 유지
    }],
  ],
}

React 18을 아직 쓰는 프로젝트라면 target을 내리고 런타임을 함께 설치한다.

// npm install react-compiler-runtime@latest 후
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', { target: '18' }],
  ],
}

05왜 중요한가

설정은 컴파일러를 자기 프로젝트 사정에 맞추는 손잡이다. 특히 점진 도입(annotation)과 낮은 버전 지원(target)은 실제로 자주 만지는 지점이다. 다만 대부분의 앱은 기본값에 target만 맞추면 충분해서, 모든 옵션을 외울 필요는 없다. 필요할 때 이 표를 다시 보면 된다.

Reference