React Native CLI 로 시작하기

기억 앵커

이 문서는 React Native CLI 로 시작하기 내용을 완전히 잊었을 때도 다시 따라 할 수 있게 보기 위한 실행 노트다.

언제 쓰나

React Native 프로젝트를 새로 만들거나 모노레포 구조로 다시 세팅할 때 본다.

시작 전 확인

Node/Yarn이 실행되는지 확인한다.
iOS를 다루면 Xcode, CocoaPods, Ruby/bundler 상태를 확인한다.
Android를 다루면 Android Studio, SDK, emulator 또는 기기를 준비한다.

따라하기 순서

프로젝트 루트와 앱 폴더 위치를 정한다.
문서의 생성 명령을 실행한다.
iOS 의존성은 pod install까지 끝낸다.
Metro 설정이 필요한 구조인지 확인한다.
yarn ios 또는 yarn android로 실제 실행한다.

완료 기준

앱이 시뮬레이터/기기에서 열린다.
Metro가 프로젝트 파일을 정상 감지한다.
초기 화면 수정 후 hot reload가 동작한다.

프로젝트 생성

React Native CLI는 Expo 없이 네이티브 프로젝트를 직접 다루고 싶을 때 사용한다. Android/iOS 네이티브 폴더가 바로 생기기 때문에, 나중에 Firebase, Fastlane, native module, Gradle, CocoaPods를 직접 만질 일이 있으면 이 방식이 편하다.

0. 먼저 확인할 것

node -v
yarn -v
java -version

Android만 할 거면 Android Studio, Android SDK, emulator 또는 실제 기기가 준비되어 있어야 한다.
iOS도 할 거면 Xcode, Xcode Command Line Tools, CocoaPods 환경이 준비되어 있어야 한다.
예전에 전역 react-native-cli를 설치해둔 적이 있으면 충돌 원인이 될 수 있으니 제거한다.

npm uninstall -g react-native-cli @react-native-community/cli

1. 새 앱 만들기

공식 문서 기준 명령은 아래 형태다. 앱 이름은 예시로 mobile을 사용한다.

npx @react-native-community/cli@latest init mobile

Yarn Berry 환경에서 같은 감각으로 실행하고 싶으면 아래처럼 해도 된다.

yarn dlx @react-native-community/cli@latest init mobile

생성이 끝나면 앱 폴더로 이동한다.

cd mobile

2. Metro 켜기

Metro는 React Native의 JS 번들러다. 이 터미널은 계속 켜둔다.

yarn start

3. Android 실행

다른 터미널을 열고 앱 폴더에서 실행한다.

yarn android

안 되면 먼저 확인한다.

Android emulator가 켜져 있는가
실제 기기라면 USB 디버깅이 켜져 있는가
ANDROID_HOME과 platform-tools 경로가 잡혀 있는가
java -version이 프로젝트가 요구하는 JDK와 맞는가

4. iOS 의존성 설치

cd ios
bundle install
bundle exec pod install
cd ..

bundle 구성이 없는 오래된 프로젝트라면 아래처럼 직접 실행해도 된다.

cd ios
pod install
cd ..

iOS 실행:

yarn ios

5. 화면 수정으로 확인하기

App.tsx에서 텍스트를 하나 바꾸고 저장한다. 앱에서 바로 반영되면 Metro, native build, 파일 감지가 모두 살아 있는 상태다.

export default function App() {
  return (
    <View>
      <Text>React Native CLI 시작 성공</Text>
    </View>
  );
}

1. core 패키지 설치

yarn add @react-navigation/native

2. 대부분의 navigator가 요구하는 native 의존성 설치

yarn add react-native-screens react-native-safe-area-context

iOS를 사용하면 pods를 다시 설치한다.

cd ios
bundle exec pod install
cd ..

3. native stack까지 쓸 때

yarn add @react-navigation/native-stack

4. Android 설정

react-native-screens는 Android에서 Activity 재시작 상태 복원 문제를 피하기 위해 MainActivity.kt 설정이 필요하다.

android/app/src/main/java/<패키지명>/MainActivity.kt를 연다.

import android.os.Bundle
import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory

class MainActivity: ReactActivity() {
  // ...

  override fun onCreate(savedInstanceState: Bundle?) {
    supportFragmentManager.fragmentFactory = RNScreensFragmentFactory()
    super.onCreate(savedInstanceState)
  }
}

Android 13 이상에서 뒤로가기 제스처가 이상하면 android/app/src/main/AndroidManifest.xml의 <application> 또는 <activity>에 아래 옵션을 확인한다.

<application
  android:enableOnBackInvokedCallback="false">
  <!-- ... -->
</application>

5. 최소 연결 코드

import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import { Text, View } from 'react-native';

type RootStackParamList = {
  Home: undefined;
};

const Stack = createNativeStackNavigator<RootStackParamList>();

function HomeScreen() {
  return (
    <View>
      <Text>Home</Text>
    </View>
  );
}

export default function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

자주 막히는 지점

Metro cache가 꼬였을 때

yarn start --reset-cache

iOS에서 native module을 못 찾을 때

cd ios
bundle exec pod install
cd ..
yarn ios

Android에서 방금 설치한 native module을 못 찾을 때

cd android
./gradlew clean
cd ..
yarn android

기억할 핵심

yarn start는 JS 번들러를 켜는 명령이다.
yarn android, yarn ios는 native 앱을 빌드하고 실행하는 명령이다.
JS 패키지만 설치했으면 Metro 재시작으로 해결되는 경우가 많다.
native module을 설치했으면 iOS는 pod install, Android는 rebuild가 필요할 수 있다.