Skip to main content
Version: Next

React Native Gradle Plugin

이 가이드는 안드로이드용 리액트 네이티브 애플리케이션을 빌드할 때 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 안드로이드 앱을 커스터마이징하기 위한 설정 블록이다.
 * 기본적으로는 아무 설정도 적용할 필요가 없으며, 필요한 줄만 주석을 해제하면 된다.
 */
react {
  // 커스텀 설정을 여기에 추가한다.
}

각 설정 키에 대한 설명은 아래와 같다:

root​

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

groovy
root = file("../")

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의 진입점이다. 기본값은 ../node_modules/react-native/cli.js로 설정된다. 플러그인이 번들링과 앱 생성 과정에서 CLI를 호출하려면 이 진입점 파일이 필요하다.

모노레포를 사용하거나 다른 패키지 매니저를 사용하는 경우, 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 컴파일러(hermesc)의 경로를 지정한다. 리액트 네이티브는 기본적으로 Hermes 컴파일러를 포함하고 있으므로, 일반적으로 이 값을 별도로 설정할 필요는 없다. 플러그인은 시스템에 맞는 적절한 컴파일러를 자동으로 사용한다.

hermesFlags​

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

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

빌드 변형과 플레이버 활용하기​

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

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

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

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

diff
apply plugin: "com.facebook.react"

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

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

플러그인이 내부적으로 어떤 작업을 수행하는가?​

React Native Gradle Plugin은 React Native 애플리케이션을 프로덕션 환경에 배포하기 위해 애플리케이션 빌드를 구성하는 역할을 담당한다. 또한 이 플러그인은 새로운 아키텍처를 위한 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 저장소(Maven Central, Google Maven Repo, JSC 로컬 Maven 저장소 등)를 설정한다.
  • 새로운 아키텍처를 사용하는 앱을 빌드할 수 있도록 NDK를 설정한다.
  • 런타임에 Hermes 또는 새로운 아키텍처가 활성화되어 있는지 확인할 수 있도록 buildConfigFields를 설정한다.
  • 앱이 연결할 포트를 알 수 있도록 Metro DevServer Port를 Android 리소스로 설정한다.
  • 라이브러리나 앱이 새로운 아키텍처를 위해 Codegen을 사용하는 경우 React Native Codegen을 실행한다.