Skip to main content

React Native Gradle Plugin

이 가이드에서는 안드로이드용 React Native 애플리케이션을 빌드할 때 React Native Gradle Plugin(RNGP로 불림)을 설정하는 방법을 설명한다.

플러그인 사용하기​

React Native Gradle 플러그인은 별도의 NPM 패키지로 배포되며, react-native와 함께 자동으로 설치된다.

npx react-native init 명령어로 새 프로젝트를 생성하면, 이 플러그인은 이미 설정된 상태다. 따라서 별도의 설치 과정이 필요 없다.

기존 프로젝트에 React Native를 통합하는 경우, 해당 페이지를 참고하면 된다. 여기에는 플러그인을 설치하는 구체적인 방법이 안내되어 있다.

플러그인 설정하기​

기본적으로 이 플러그인은 별다른 설정 없이도 바로 사용할 수 있도록 합리적인 기본값을 제공한다. 이 가이드를 참고해 필요한 경우에만 동작을 커스터마이징하면 된다.

플러그인을 설정하려면 android/app/build.gradle 파일 내부의 react 블록을 수정하면 된다:

groovy
apply plugin: "com.facebook.react"

/**
 * React Native Android 앱을 커스터마이징하기 위한 설정 블록이다.
 * 기본적으로 아무런 설정을 적용할 필요는 없으며, 필요한 줄만 주석을 해제하면 된다.
 */
react {
  // 여기에 커스텀 설정을 추가한다.
}

각 설정 키에 대한 설명은 다음과 같다:

root​

이 부분은 React Native 프로젝트의 루트 폴더를 가리킨다. 즉, package.json 파일이 위치한 디렉토리를 의미한다. 기본값은 ..로 설정되어 있다. 다음과 같이 커스텀 설정할 수 있다:

groovy
root = file("../")

reactNativeDir​

reactNativeDir는 react-native 패키지가 위치한 폴더를 가리킨다. 기본값은 ../node_modules/react-native로 설정되어 있다. 모노레포를 사용하거나 다른 패키지 매니저를 사용하는 경우, reactNativeDir를 환경에 맞게 조정할 수 있다.

다음과 같이 커스터마이징할 수 있다:

groovy
reactNativeDir = file("../node_modules/react-native")

codegenDir​

이 폴더는 react-native-codegen 패키지가 위치하는 곳이다. 기본값은 ../node_modules/react-native-codegen이다. 모노레포를 사용하거나 다른 패키지 매니저를 사용하는 경우, codegenDir을 설정에 맞게 조정할 수 있다.

다음과 같이 커스터마이즈할 수 있다:

groovy
codegenDir = file("../node_modules/@react-native/codegen")

cliFile​

이 파일은 React Native CLI의 진입점(entrypoint)이다. 기본값은 ../node_modules/react-native/cli.js로 설정되어 있다.
이 진입점 파일은 플러그인이 앱 번들링 및 생성 과정에서 CLI를 호출할 때 필요하다.

모노레포(monorepo)를 사용하거나 다른 패키지 매니저를 사용하는 경우, cliFile을 자신의 환경에 맞게 조정할 수 있다.
다음과 같이 커스터마이징할 수 있다:

groovy
cliFile = file("../node_modules/react-native/cli.js")

debuggableVariants​

이 설정은 디버깅 가능한 변형(variants) 목록을 정의한다. (변형에 대한 자세한 내용은 using variants 참조)

기본적으로 플러그인은 debug 변형만을 debuggableVariants로 간주하며, release는 포함하지 않는다. 만약 staging, lite 등과 같은 다른 변형이 있다면, 이 설정을 적절히 조정해야 한다.

debuggableVariants로 지정된 변형은 번들로 제공되지 않으므로, Metro를 통해 실행해야 한다.

다음과 같이 커스텀 설정할 수 있다:

groovy
debuggableVariants = ["liteDebug", "prodDebug"]

nodeExecutableAndArgs​

이 설정은 모든 스크립트를 실행할 때 사용할 node 명령어와 인자 목록을 정의한다. 기본값은 [node]이지만, 다음과 같이 추가 플래그를 포함하도록 커스터마이즈할 수 있다:

groovy
nodeExecutableAndArgs = ["node"]

bundleCommand​

이 설정은 앱의 번들을 생성할 때 호출할 bundle 커맨드의 이름을 지정한다. RAM 번들을 사용하는 경우 유용하다. 기본값은 bundle이지만, 다음과 같이 추가 플래그를 포함해 커스터마이징할 수 있다:

groovy
bundleCommand = "ram-bundle"

bundleConfig​

이 설정은 bundle --config <file> 명령에 전달될 구성 파일의 경로를 지정한다. 기본값은 비어 있으며, 이 경우 구성 파일이 제공되지 않는다. 번들링 구성 파일에 대한 자세한 정보는 CLI 문서에서 확인할 수 있다. 다음과 같이 커스텀 설정이 가능하다:

groovy
bundleConfig = file(../rn-cli.config.js)

bundleAssetName​

이 옵션은 생성될 번들 파일의 이름을 지정한다. 기본값은 index.android.bundle이다. 다음과 같이 커스텀 설정할 수 있다:

groovy
bundleAssetName = "MyApplication.android.bundle"

번들 생성에 사용되는 진입 파일이다. 기본적으로 index.android.js 또는 index.js 파일을 검색한다. 다음과 같이 커스텀 설정이 가능하다:

groovy
entryFile = file("../js/MyApplication.android.js")

extraPackagerArgs​

bundle 명령에 전달할 추가 플래그 목록이다. 사용 가능한 플래그 목록은 CLI 문서에서 확인할 수 있다. 기본값은 빈 배열이다. 다음과 같이 커스터마이징할 수 있다:

groovy
extraPackagerArgs = []

hermesCommand는 Hermes Compiler(hermesc)의 경로를 나타낸다. React Native는 기본적으로 Hermes 컴파일러를 함께 제공하므로, 일반적으로 이 설정을 직접 수정할 필요는 없다. 해당 플러그인은 시스템에 맞는 올바른 컴파일러를 기본적으로 사용한다.

hermesFlags​

hermesc에 전달할 플래그 목록을 정의한다. 기본값은 ["-O", "-output-source-map"]이다. 다음과 같이 커스텀 설정이 가능하다.

groovy
hermesFlags = ["-O", "-output-source-map"]

플레이버와 빌드 변형 사용하기​

안드로이드 앱을 개발할 때, 동일한 프로젝트에서 시작해 다양한 버전의 앱을 만들기 위해 커스텀 플레이버를 사용할 수 있다.

공식 안드로이드 가이드(official Android guide)를 참고해 staging과 같은 커스텀 빌드 타입이나 full, lite와 같은 커스텀 플레이버를 설정할 수 있다. 기본적으로 새로운 앱은 debug와 release 두 가지 빌드 타입으로 생성되며, 초기에는 커스텀 플레이버가 설정되어 있지 않다.

모든 빌드 타입과 플레이버를 조합하면 빌드 변형이 생성된다. 예를 들어 debug, staging, release 빌드 타입과 full, lite 플레이버가 있다면, 총 6개의 빌드 변형이 만들어지게 된다. fullDebug, fullStaging, fullRelease 등이 그 예시다.

debug와 release 외에 커스텀 변형을 사용한다면, React Native Gradle 플러그인에 어떤 변형이 디버깅 가능한지 알려줘야 한다. 이를 위해 debuggableVariants 설정을 사용한다:

diff
apply plugin: "com.facebook.react"

react {
+ debuggableVariants = ["fullStaging", "fullDebug"]
}

이 설정은 플러그인이 debuggableVariants에 포함된 변형에 대해 JS 번들링을 건너뛰기 때문에 필요하다. 이 경우 Metro를 실행해야 한다. 예를 들어 fullStaging을 debuggableVariants에 포함시켰다면, 번들이 누락되어 스토어에 출시할 수 없게 된다.

플러그인이 내부적으로 수행하는 작업​

React Native Gradle 플러그인은 React Native 애플리케이션을 프로덕션 환경에 배포하기 위해 애플리케이션 빌드를 구성하는 역할을 한다. 또한 이 플러그인은 새 아키텍처(New Architecture)에서 사용되는 Codegen을 실행하기 위해 서드파티 라이브러리 내부에서도 활용된다.

플러그인의 주요 역할을 요약하면 다음과 같다:

  • 디버그 가능하지 않은 모든 변형(variant)에 대해 createBundle<Variant>JsAndAssets 태스크를 추가한다. 이 태스크는 bundle, hermesc, compose-source-map 명령어를 실행하는 역할을 한다.
  • react-native의 package.json에서 React Native 버전을 읽어와 com.facebook.react:react-android와 com.facebook.react:hermes-android 의존성을 적절한 버전으로 설정한다.
  • 필요한 모든 Maven 의존성을 사용할 수 있도록 Maven Central, Google Maven Repo, JSC 로컬 Maven repo 등의 Maven 저장소를 구성한다.
  • 새 아키텍처를 사용하는 앱을 빌드할 수 있도록 NDK를 설정한다.
  • 런타임에 Hermes 또는 새 아키텍처가 활성화되었는지 확인할 수 있도록 buildConfigFields를 설정한다.
  • 앱이 연결할 포트를 알 수 있도록 Metro DevServer Port를 Android 리소스로 설정한다.
  • 라이브러리나 앱이 새 아키텍처를 위해 Codegen을 사용하는 경우, React Native Codegen을 호출한다.

이러한 작업을 통해 React Native Gradle 플러그인은 애플리케이션의 빌드 프로세스를 효율적으로 관리하고, 새 아키텍처와 같은 최신 기능을 원활하게 지원한다.