라이브러리 컴파일

01무엇

라이브러리 저자는 컴파일러로 최적화한 코드를 미리 빌드해 npm에 올릴 수 있다. 그러면 사용자는 컴파일러를 안 켜도 최적화된 버전을 그대로 받는다.

앱이 아니라 배포용 패키지를 만드는 쪽을 위한 내용이다.

02무슨 일이 일어나나

미리 컴파일해 배포하면 세 가지 이점이 있다. 사용자가 컴파일러를 아직 안 써도 최적화 혜택을 받고, 사용자 쪽에 별도 설정이 필요 없으며, 모두가 같은 최적화 버전을 받아 동작이 일관된다.

대신 최적화된 코드는 런타임 헬퍼에 기댄다. 특히 React 19 미만을 지원하는 라이브러리는 react-compiler-runtime을 **일반 의존성(dependencies)**으로 넣어야 한다. 개발 의존성에 두면 사용자 번들에 안 들어가서 "Cannot find module" 오류가 난다.

03사용법

컴파일러 플러그인은 개발 의존성으로 설치한다.

npm install -D babel-plugin-react-compiler@latest

낮은 버전을 지원한다면 런타임을 일반 의존성으로 설치한다.

npm install react-compiler-runtime@latest

target은 자기 라이브러리가 지원하는 가장 낮은 React 버전에 맞춘다. 이 값이 실제 최소 지원 버전과 어긋나면 호환성이 깨진다. 그리고 컴파일한 버전과 안 한 버전 양쪽으로 테스트해, 지원 범위의 React 버전에서 모두 도는지 확인한다.

04실무 예시

React 17 이상을 지원하는 라이브러리의 설정이다. package.json에 런타임을 일반 의존성으로, React를 peer로 둔다.

{
  "dependencies": {
    "react-compiler-runtime": "^1.0.0"
  },
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
  }
}

빌드 설정은 target을 최소 지원 버전으로 내린다.

module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      target: '17', // 지원하는 가장 낮은 React 버전
    }],
  ],
}

05왜 중요한가

이건 라이브러리를 만들어 배포하는 사람에게만 해당하는 주제라, 앱만 짓는 대부분에겐 지금 당장 쓸 일이 없다. 그래도 자기가 쓰는 라이브러리가 왜 이미 최적화되어 있는지, 왜 react-compiler-runtime이 의존성에 딸려 오는지를 이해하는 데는 도움이 된다. 실제로 패키지를 낼 때가 오면 그때 자세히 보면 된다.

Reference