Metro Bundler: 개념, 프로젝트 번들링 및 작동 원리

Metro Bundler란

Metro Bundler는 Meta가 React Native용으로 개발한 오픈소스 JavaScript 번들러로, 모든 프레임워크 프로젝트에서 기본적으로 사용됩니다. Metro의 역할은 프로젝트의 JavaScript 코드를 종속성과 함께 가져와 장치에서 실행되는 하나 이상의 번들로 묶는 것입니다. 범용 번들러(Webpack, Rollup, Parcel)와 달리 Metro는 모바일 개발의 특성에 최적화되어 있습니다. 최소 빌드 시간, 개발 중 증분 업데이트, 플랫폼 모듈(Objective-C, Swift, Java, Kotlin 네이티브 모듈)의 올바른 처리를 제공합니다. Metro는 React Native CLI의 일부로 제공되며 별도 설치가 필요하지 않습니다. React Native 0.72부터 Metro 버전 0.80+는 모듈의 병렬 트랜스파일을 지원하여 멀티코어 프로세서에서 빌드 속도를 최대 40%까지 향상시킵니다.

Metro 아키텍처: Resolver, Transformer, Bundler

Metro의 아키텍처는 Resolver, Transformer, Bundler의 세 가지 독립적인 구성 요소로 나뉩니다. Resolver는 모듈 검색 및 해석을 담당하며 import/require 표현식을 읽고 플랫폼 확장자를 고려하여 해당 파일을 찾아 절대 경로를 반환합니다. Transformer는 트랜스파일을 수행하며 Babel을 프리셋 및 플러그인과 함께 적용하여 JSX, TypeScript 또는 Flow를 순수 JavaScript로 변환합니다. Bundler는 최종 단계로, Resolver의 종속성 그래프와 Transformer의 변환된 파일을 가져와 하나 이상의 번들(모듈 번들)로 직렬화합니다. 세 단계로 분리하면 Metro가 각 단계의 결과를 캐시할 수 있습니다. 하나의 파일만 변경된 경우 Resolver와 Bundler는 나머지 모듈에 캐시를 사용할 수 있어 개발 모드에서 빌드 속도가 최대 10배 향상됩니다.

Resolver: 모듈 해석 및 플랫폼 인식 검색

Metro의 Resolver는 Node.js 모듈 해석과 부분적으로 호환되는 모듈 해석 알고리즘을 구현합니다. Node.js와의 주요 차이점은 플랫폼 확장자 지원입니다. require(‘./Component’)는 지정된 우선순위 순서로 Component.native.js, Component.ios.js, Component.android.js를 검색합니다. Resolver는 또한 모듈을 대체 구현에 매핑하기 위한 package.json 필드 “react-native”를 지원합니다. 이는 플랫폼별 코드가 있는 라이브러리의 표준 메커니즘입니다. 파일을 찾을 수 없는 경우 Resolver는 전체 검색 스택과 함께 오류를 발생시킵니다.

Transformer: Babel 및 트랜스파일

Metro 내부의 Transformer는 metro-react-native-babel-preset 프리셋과 함께 Babel을 사용합니다. 표준 구성에는 JSX를 React.createElement로 변환, TypeScript 지원(타입 제거), Flow 지원, 최신 JavaScript 표준(async/await, optional chaining, nullish coalescing)을 위한 폴리필이 포함됩니다. Transformer는 병렬 모드로 작동하며 각 모듈은 워커 프로세스 풀을 사용하여 독립적으로 트랜스파일됩니다(기본적으로 수는 CPU 수에 해당). Metro 0.80부터 Granular Transformer Cache가 지원되어 개별 파일 수준에서 캐시 무효화가 가능합니다.

Metro의 플랫폼별 확장자

Metro의 주요 기능 중 하나는 플랫폼 파일 확장자 지원입니다. React Native 프로젝트는 동일한 모듈의 세 가지 버전을 포함할 수 있습니다: Component.ios.js(iOS), Component.android.js(Android), Component.native.js(두 플랫폼 모두). require(‘./Component’)를 가져올 때 Resolver는 대상 빌드 플랫폼에 따라 자동으로 올바른 버전을 선택합니다. 이를 통해 조건부 Platform.OS 구문 없이 플랫폼 종속 코드를 작성할 수 있습니다. 우선순위 순서: name.platform.js > name.native.js > name.js입니다. .native.js 확장자는 두 플랫폼에서 작동하지만 웹과는 호환되지 않는 공통 코드에 사용됩니다. .ios.js 및 .android.js 확장자는 탐색, 제스처, 파일 시스템 작업과 같은 특정 기능 구현에 사용됩니다. Metro는 resolver.sourceExts 구성을 통해 사용자 정의 확장자를 지원합니다.

// metro.config.js — sourceExts 및 watchFolders 설정
const config = {
  resolver: {
    sourceExts: ['jsx', 'js', 'tsx', 'ts', 'json'],
    platformExtensions: ['ios', 'android', 'native'],
  },
  transformer: {
    babelTransformerPath: require('metro-react-native-babel-transformer'),
  },
  watchFolders: [path.resolve('../shared')],
};

Metro의 핫 리로드와 Fast Refresh

Fast Refresh는 Metro 위에 구축된 React Native의 핫 리로드 메커니즘입니다. 개발자가 파일을 변경하면 Metro는 변경된 모듈만 다시 트랜스파일하고 WebSocket을 통해 앱에 업데이트를 전송합니다. Fast Refresh는 전체 애플리케이션을 다시 로드하지 않고 UI를 업데이트하며 JSX나 스타일만 변경된 경우 React 컴포넌트 상태를 유지합니다. 훅이나 상태가 포함된 코드가 변경된 경우 Fast Refresh는 변경된 컴포넌트만 다시 마운트합니다. Metro는 두 가지 모드를 지원합니다: Hot Module Replacement(HMR)은 실시간 모듈 교체, Live Reload는 네이티브 모듈이나 구성 변경 시 전체 애플리케이션 다시 로드입니다. Fast Refresh는 React Native 0.76에서 기본적으로 활성화되어 있으며 추가 구성이 필요하지 않습니다. npx react-native start만 실행하면 됩니다.

Metro 설정: metro.config.js

metro.config.js 파일은 React Native 프로젝트 루트에 있는 Metro 구성 파일입니다. 여기에서 resolver(sourceExts, platformExtensions, extraNodeModules), transformer(babelTransformerPath, minifierConfig), server(port, host, enableFastRefresh), watcher(watchFolders, healthCheck)를 구성합니다. 표준 Metro 구성은 @react-native/metro-config 패키지(React Native 0.76+)에서 상속됩니다. 모노레포 프로젝트의 경우 watchFolders를 추가하여 Metro가 프로젝트 루트 외부의 패키지 변경을 추적할 수 있도록 합니다. sourceExts를 구성하려면 사용자 정의 변환기를 위해 ‘svg’, ‘png’, ‘gql’을 추가합니다. Metro는 async 함수를 통한 비동기 구성을 지원하여 환경에 따른 동적 구성 생성에 유용합니다.

구성을 통한 빌드 최적화

Metro 빌드 최적화는 적절한 캐시 구성에서 시작됩니다. maxWorkers를 CPU 수에서 1을 뺀 값으로 설정합니다. 배포의 경우 CI에서 resetCache를 사용합니다. sourceExts를 최소화합니다. 추가 확장자는 모듈 해석을 느리게 합니다. 대규모 프로젝트의 경우 watchFolders를 필요한 디렉토리로만 구성합니다. Metro는 Hermes 바이트코드 축소를 지원하여 표준 Terser보다 작은 번들 크기를 제공합니다. minifierPath: ‘metro-minify-terser’를 사용하세요.

Hermes 번들링: 바이트코드 빌드

Metro는 JavaScript AST 단계를 건너뛰고 직접 Hermes 바이트코드로 빌드하는 모드를 지원합니다. HermesTransformer로 빌드하면 모듈이 일반 JavaScript 대신 HBC(Hermes ByteCode)로 컴파일됩니다. 이를 통해 번들 크기 감소(30-40%), 더 빠른 애플리케이션 시작(20-30%), 메모리 소비 감소를 제공합니다. 활성화하려면 metro.config.js에서 hermesCommand를 설정하고 build.gradle(Android) 또는 Podfile(iOS)에서 Hermes 플래그를 활성화합니다. Hermes 번들 빌드는 두 단계로 수행됩니다. 먼저 Metro가 JavaScript 번들을 빌드한 다음 Hermes CLI가 이를 HBC로 변환합니다. React Native 0.70부터 Hermes는 Android의 기본 엔진이며 iOS에서는 명시적 활성화가 필요합니다.

Metro vs Webpack: 접근 방식 비교

Metro와 Webpack의 차이는 서로 다른 목표에 기인합니다. Webpack은 방대한 플러그인 및 로더 생태계를 갖춘 웹용 범용 번들러입니다. Metro는 React Native용 특화 번들러로, 증분 빌드 속도와 네이티브 모듈과의 올바른 작동을 우선시합니다. Webpack은 스마트 캐시 무효화를 갖춘 장기 모듈 그래프를 사용하여 웹에서 빠른 재빌드를 제공하지만 플랫폼 확장자에 문제가 발생합니다. Metro는 빌드 간에 그래프를 캐시하지 않고 매번 구축하여 플랫폼 확장자와 Haste 모듈 처리를 단순화합니다. Webpack은 청크를 사용한 동적 가져오기를 지원하며 Metro도 React.lazy() 및 Suspense를 통해 지원하지만 하나의 활성 요청으로 제한됩니다. Metro의 생태계는 훨씬 작으며 style-loader, css-loader, file-loader의 대체품이 없습니다. 이러한 작업은 React Native에서 다르게 해결됩니다.

Metro를 선택해야 하는 경우

Metro는 React Native 프로젝트의 유일한 올바른 선택입니다. Webpack은 기본적으로 플랫폼 인식 해석을 지원하지 않으며 Webpack으로 React Native를 설정하려면 상당한 노력이 필요합니다(haul bundler, expo web packager). Metro는 React Native CLI에 통합되어 있고 Meta 공식 팀의 지원을 받으며 React Native의 모든 릴리스와 함께 업데이트를 받습니다. React Native Web 프로젝트의 경우 모바일 번들에는 Metro를 유지하면서 웹 빌드에는 Webpack을 사용할 수 있습니다.