[React Native] 맥(MacOS)에서 React Native CLI 앱 개발 환경 세팅하기! (feat. XCode, Android Studio)
React Native로 앱 만들기!
Expo가 아닌 React Native CLI로 시작한 이유?
React Native 공식 문서에서도 Expo 사용을 권장한다. Expo는 복잡한 환경 세팅 없이도 간편하게 앱을 개발할 수 있는 프레임워크다. 간단한 앱을 빠르게 만들어보고 싶다면 분명 Expo가 적합하다.
하지만 내가 만들고자 하는 앱에는 모바일 화면 공유 기능이 반드시 포함되어야 했다. Expo는 기본적으로 제공하는 네이티브 기능 외에는 확장이 제한적이고, 필요한 라이브러리를 자유롭게 추가하기 어려운 편이다. 그리고 기왕 공부하는 김에 React Native의 근본부터 배우고 싶다는 마음도 있어서 React Native CLI로 시작했다.
나는 주로 Windows 환경에서 개발을 진행하지만, iOS 시뮬레이터는 macOS에서만 사용 가능하기 때문에 책상 구석에 있던 맥북을 조심스럽게 꺼내보았다. 추후에는 Windows 환경에서도 세팅을 해보고 내용을 공유해보도록 하겠다.
전체 개요
React Native CLI 환경 세팅은 설치해야 할 것이 굉장히 많다. 공식 문서나 블로그 글들이 잘 정리되어 있어 전체적인 흐름을 따라가기 어렵진 않지만, 실제로 진행하면서 현재 버전과 맞지 않는 것이나 자잘한 오류들을 자주 마주치게 된다.
기본적으로는 React Native 공식 문서를 참고하여 따라 진행했지만, 따라하면서 세부적인 설정 방법은 이 글을 참고하여 해결했다. 그렇게 하면서도 자잘한 에러를 생각보다 많이 마주쳤던 것 같다. 이 글에서는 그런 부분들을 함께 정리해 보고자 한다.
Homebrew 설치
macOS에서 패키지 설치와 관리를 도와주는 패키지 관리자이다. 대부분의 의존성 도구들을 Homebrew를 통해 설치하게 된다. Homebrew 공식 웹사이트에 나와있는 설치 스크립트로 간단하게 설치할 수 있다.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"rbenv 설치
macOS에는 기본적으로 Ruby가 설치되어 있지만, iOS 개발에 필요한 Cocoapods가 Ruby 2.7.0 이상의 버전을 요구하고 있기 때문에, rbenv를 설치하고 버전 업데이트가 필요하다. 이 때 버전이 맞지 않으면 Cocoapods 설치시에 문제가 될 수 있다.
brew install rbenv #rbenv 설치설치 이후에 버전 업데이트를 위해 설치 가능한 버전을 확인 해보자.
rbenv install -l내 경우에는 아래와 같은 버전들이 확인되었다.
- 3.1.7
- 3.2.8
- 3.3.8
- 3.4.4
- jruby-10.0.0.1
- mruby-3.4.0
- picoruby-3.0.0
- truffleruby-24.2.1
- truffleruby+graalvm-24.2.1
이 중에 3.1.7이 제일 만만해 보여서 이걸로 골랐다.
rbenv install 3.1.7
rbenv global 3.1.7업데이트까지 마쳤으면 .zshrc 파일을 열어서 아래의 환경변수 구문을 추가해주자.
vi ~/.zshrc맨 아래에 다음과 같은 구문을 추가한 뒤 저장하고 닫아주자.(:wq)
eval "$(rbenv init - zsh)"이후 환경 변수를 적용시켜주자.
source ~/.zshrcNode.js 설치
React Native는 JavaScript(TypeScript)로 앱을 개발하는 프레임워크이기 때문에 브라우저가 아닌 환경에서 JavaScript를 실행할 수 있게 해주는 런타임인 Node.js가 반드시 필요하다.
Node.js 공식 웹사이트에서 직접 다운로드 받을 수도 있고, Homebrew 명령어를 통해 간단하게 설치할 수도 있다.
brew install node #Node.js 설치Node.js를 설치하면 Node.js 패키지 매니저인 npm도 같이 설치된다. 설치가 잘 되었는지 확인하기 위해서는 아래와 같은 명령어를 통해 버전 확인을 할 수 있다.
node -v #Node.js 버전 확인
npm -v #npm 버전 확인Watchman 설치
개발 중 코드가 바뀌면 파일 변경을 감지해서 자동으로 변경 사항을 반영해주는 도구이다. 이런 방식을 Fast Refresh라고 하는데, 파일을 변경 후 저장했을 때, 변경된 파일만 다시 로드하고 필요한 부분만 리렌더링해서 앱을 빠르게 업데이트 해주는 기능이다.
필수는 아니지만 개발 효율을 떨어뜨릴 수 있는 여러 문제가 생길 수 있기에 설치가 강력하게 권장된다.
brew install watchman #watchman 설치🙅♂️ React Native CLI 설치 (❌)
내가 참고했던 글에서는 React Native CLI를 설치하라고 되어있는데, 찾아보니 현재(2024년 12월 31일 이후)는 지원 중단이 되었다... 따라서 react-native init 명령어 또한 사용할 수 없게 됐다.
하지만 이제는 별도의 React Native CLI 설치 없이 React Native 프로젝트를 생성할 수 있는 방법이 있기 때문에 이 부분은 뒤에서 설명하도록 하겠다.
Xcode 설치
React Native로 iOS 앱 개발을 하기 위해서는 iOS 개발 툴인 Xcode가 필요하다. 이 때문에 Window에서는 Xcode를 설치할 수 없어서 iOS 개발이 쉽지않다. Mac App Store에서 Xcode를 설치하도록 하자.
Xcode 설치가 완료되면, Command Line Tools를 설정해줘야 한다.
Xcode를 실행하고 상단 메뉴에서 Xcode > Settings... 로 이동한 뒤
Locations 탭에서 Command Line Tools가 잘 설정되어있는지 확인해보자. 만약에 설정이 안 되어있다면, 드롭다운을 클릭해서 선택해주거나 아래의 명령어를 통해 설정할 수 있다.
xcode-select --install #Command Line Tools 설치Cocoapods 설치
Cocoapods는 iOS 앱 개발에 사용되는 네이티브 모듈의 의존성 관리를 담당하는 툴이다. React Native 프로젝트를 만들면 iOS 관련 네이티브 모듈들이 자동으로 추가된다. 이런 모듈들은 내부적으로 Swift나 Objective-C로 구현된 네이티브 코드를 포함하고 있는데, iOS 빌드시 제대로 동작하게 만드려면 Cocoapods가 이 모듈들을 Xcode 프로젝트에 연결해줘야 하는 것이다.
아래와 같은 명령어를 통해 설치할 수 있다.
sudo gem install cocoapods #Cocoapods 설치나는 설치시 아래와 같은 에러를 만났다.
이 에러가 위에서 언급했던 Ruby 버전 이슈였고, 읽어보면 2.7.0 이상의 Ruby 버전이 필요하다고 한다. 이를 해결하기 위해서는 위에 언급한 방법으로 Ruby 버전을 업데이트 해주면 된다.
JDK 설치 (Java 17)
Android 빌드를 위해 Gradle이 사용되는데, Gradle이 Java 기반으로 만들어진 빌드 도구이기 때문에 Java가 필요하다. 내가 참고했던 글에서는 AdoptOpenJDK8를 설치하라고 되어있는데, 현재는 공식 명칭이 바뀌어서 Temurin을 통해 설치할 수 있다. 어떤 걸 설치해야하나 고민하다 React Native 공식 문서에 있는 Zulu OpenJDK를 설치했다.
React Native는 Java 17까지 안정적으로 지원한다고 한다.
brew install --cask zulu@17 #Zulu OpenJDK 설치
brew info --cask zulu@17 #버전 확인이 또한 버전이 맞지 않을 경우에 안드로이드 빌드시에 에러를 마주할 수 있으니 호환되는 버전을 잘 확인하고 설치하도록 하자. 필자는 뒤에 17을 빼먹어서 최신 버전을 설치 되었는데, 확인해보니 Java 24가 설치되었고, 결국 호환성 문제로 Java 17로 버전을 다운그레이드 했다.
혹시 필자처럼 자바 버전을 잘못 설치한 경우, 지우고 Java 17을 다시 설치해주면 된다.
brew uninstall --cask zulu # 현재 설치된 최신 Zulu 제거
brew install --cask zulu17 # Zulu JDK 17 설치Android Studio 설치
React Native로 Android 앱을 개발하기 위해서는 Android Studio가 필요하다. Android 앱을 빌드하고 실행시켜주는 것 뿐만 아니라 에뮬레이터(가상 디바이스)를 기본적으로 제공해준다. Android Studio 공식 웹사이트에서 스크롤을 쭉 내려보면 여러 패키지 중에 선택해서 설치할 수 있고, 어떤 걸 설치해야할지 모르겠다면 챗지피티에게 살짝 물어보자.
내 경우에는 ARM이 적혀있지 않은 android-studio-2024.3.2.14-mac.dmg를 설치하면 된다고 한다.
내가 참고했던 글에서는 설치 과정에서 여러 가지 선택 사항이 있었던 것 같은데, 내 경우에는 Standard/Custom 선택을 제외하고는 딱히 선택할 게 없어서 이것만 Custom으로 선택하고 전부 Next를 눌러 빠르게 넘겼던 것 같다.
SDK 설정
참고했던 글에서는 오른쪽 하단이라고 되어있었는데, 인터페이스가 달라져서 찾기가 힘들었다.
내 버전 기준에서는 화면 중앙에 있는 More Actions 드롭다운을 누르면 SDK Manager를 찾을 수 있었다. 이를 눌러 들어간 뒤에
위 화면에서 Show Package Details를 체크하고, 아래 내용을 찾아 선택해주자. 이 부분 또한 참고했던 글에서 선택하라고 알려준 버전이 조금 오래된(?) 느낌이 들어서 조금 더 최신 버전으로 선택해주었다.
- Android SDK Platform 34
- Intel x86_64 Atom System Image
Google APIs ARM 64 v8a System Image(삭제)- Google APIs Intel x86_64 Atom System Image
글을 작성하다 세 번째 항목에 ARM이 적혀있는 걸 보고, 뭔가 느낌이 이상해서 챗지피티에게 물어봤더니 역시나 Intel 맥에서는 선택하지 않는 것이 좋다는 답변을 받았다. 이 부분과 관련해서도 챗지피티 등을 적극 활용해서 본인 개발 환경에 맞게 선택항목을 정하면 좋을 것 같다.
환경 변수 설정
.zshrc 파일을 열어서
vi ~/.zshrc아래 환경변수 구문을 추가하면 된다.
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools일반적으로 macOS에서 Android SDK가 설치되는 위치는 SDK 경로는 ~/Library/Android/sdk이기 때문에 위와 같이 작성해주면 된다. 혹시나 문제가 생길 경우 경로는 이전의 SDK 설정 화면 상단에 Android SDK Location에서 확인할 수 있다.
마찬가지로 환경변수를 적용시켜주자.
source ~/.zshrcReact Native 프로젝트 생성 및 실행
이제 드디어 환경 세팅을 위해 필요한 설치가 끝났다. 이제부터는 React Native 프로젝트를 생성해보자!
위에서 언급했던 것처럼 이제는 react-native-cli를 설치하지 않고도, 프로젝트를 생성할 수 있게 되었다. 아래의 명령어를 통해 프로젝트를 생성해주자.
npx @react-native-community/cli init MyApp해당 프로젝트로 이동하면
cd MyApp
우선 앱 최상단에 있는 App.tsx 파일이 바로 우리가 개발을 시작하게 될 루트 컴포넌트일 것이고, /ios와 /android가 각각의 네이티브 플랫폼용 프로젝트 설정과 코드를 포함하고 있는 디렉토리일 것이다.
일단 무작정 실행시켜 보자.
iOS 앱 실행
아래의 명령어를 통해 iOS 앱을 빌드하고 실행할 수 있다.
npm run ios순탄할 것이라고 생각지는 않았지만, 역시나 또 에러를 마주했다.
이는 Cocoapods 설정이 누락되었을 때 발생하는 에러이다.
처음 프로젝트 생성 후에 Cocoapods를 지금 설치하겠냐는 말에 나는 '전 이미 설치했는데요?' 하며 no를 선택했기 때문인 것이다. 여기서 yes를 눌러서 Cocoapods 설정을 해주거나 아니면 프로젝트 루트 디렉토리에 있는 /ios 디렉토리로 이동해서 pod install을 해줘야 한다.
cd ios
pod install이젠 되...ㄱ...
어림도 없지! 바로 에러!
이건 또 무엇인고 하니 /User/dongglim/.../script/react_native_pods.rb 라는 파일을 로드할 수가 없다고 한다. 이 부분을 해결하기 위해 정말 많은 시간이 소요가 됐는데, 결과적으로는 파일을 불러오는 부분의 코드를 변경했다.
(프로젝트 루트 디렉토리)/ios/Podfile :
# Resolve react_native_pods.rb with node to allow for hoisting
require Pod::Executable.execute_command('node', ['-p',
'require.resolve(
"react-native/scripts/react_native_pods.rb",
{paths: [process.argv[1]]},
)', __dir__]).strip
platform :ios, min_ios_version_supported
prepare_react_native_project!
linkage = ENV['USE_FRAMEWORKS']
if linkage != nil
Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
use_frameworks! :linkage => linkage.to_sym
end
여기서 파일을 로드하는 부분을
require Pod::Executable.execute_command('node', ['-p',
'require.resolve(
"react-native/scripts/react_native_pods.rb",
{paths: [process.argv[1]]},
)', __dir__]).strip아래 코드와 같이 변경해주었다.
require_relative '../node_modules/react-native/scripts/react_native_pods'이 부분이 뭔가 프로젝트 생성시에 디폴트 설정값을 임의로 변경하는 것 같아서 껄끄럽기도 하고, 추후에 문제가 생길까 싶긴 하다. 기존의 코드는 require.resolve()를 통해 react_native_pods.rb의 정확한 경로를 찾아서 불러오는 동적인 방식이다. 이를 좀 더 단순하게 변경한 것인데, 내가 프로젝트 구조를 크게 변경하지 않는 한 루트 디렉토리에 node_modules가 있을 것이고, 그 안에 해당 파일만 온전하게 설치되어 있으면 잘 동작할 것이기 때문에 이렇게 써줘도 큰 문제는 없을 것 같아서 이 방식을 채택했다.
다만, react_native_pods와 관련해서 설치되는 디렉토리가 변경된다거나 프로젝트 구조가 변경됨에 따라 ../와 같은 상대경로를 변경해야된다던가 하는 부분은 스스로 인지하고 있다가 문제가 생겼을 때 잘 대응할 수 있어야 하겠다.
수정한 뒤에 /ios 디렉토리에서 아래 명령어를 실행시켜주면 정상적으로 동작하는 것을 확인할 수 있다.
pod install
뭔진 몰라도 초록색을 보니 마음이 매우 편안하다... 이것 저것 열심히 설치가 진행되고 있구나 싶다...
이후에 다시 처음으로 되돌아가 iOS 앱 실행 명령어를 입력하면
npm run ios맥북을 너무 오랜만에 꺼내서 그런지 빌드 중에 팬 소리가 꽤나 커진 것 같다... 약 3~4분 가량의 빌드를 마치고 나면 Xcode 시뮬레이터에서 자동으로 앱을 실행시켜준다.
쫘잔~!! 드디어... 드디어.. 성공했다!
✅ 추가 이슈
생각해보니 한 번의 이슈가 더 있었다. 그렇게 큰 이슈는 아니기 때문에 뒤에 짤막하게 추가하도록 하겠다. npm run ios로 실행시켰을 때 만났던 에러인데,
시뮬레이터가 감지되지 않는다는 에러였다. Xcode에서 시뮬레이터를 설치해줘야하는데, Xcode 설치만 하고 시뮬레이터를 설치해주지 않아 생긴 에러였다.
Xcode를 실행하고, 상단 메뉴에서 Xcode > Settings...를 선택하여 설정창으로 들어간다. 그 다음으로 Components 탭에 들어가게 되면
위와 같은 화면이 뜨는데, 여기서 원하는 기종의 시뮬레이터를 추가할 수 있다. 나는 모바일 앱을 만들거기 때문에 두 번째 줄에 있는 iOS 18.4를 Get 해주었다!!!!
Android 앱 실행
이제 드디어 마지막으로 Android 앱을 실행시켜보자!!
npm run android다행히 크게 해결이 복잡한 에러는 없었고, 마주쳤던 에러는 하나였다.
이 당시 설치되어 있던 Java의 버전이 24버전이었는데,
Unsupported class file major version 68major version 68이 Java 24버전을 의미하고, 'Java 24에서 컴파일된 클래스 파일을 지원하지 않는다.' 뭐 그런 뜻이라고 한다.
이 부분은 위에서 언급했던 것 처럼 지우고 Java 17을 다시 설치해주면 된다.
brew uninstall --cask zulu
brew install --cask zulu17이렇게 해주면, 빌드가 에러 없이 정상적으로 잘 되는 것을 확인할 수 있고
아주 깔끔하게 실행이 된다!!!
마무리
React Native CLI 기반으로 환경을 설정하는 과정은 다소 복잡하지만, 네이티브 기능을 직접 활용할 수 있다는 장점이 있다. 뿐만 아니라 중간에 발생하는 오류들도 차근차근 해결해가며 학습하면, React Native의 구조와 동작 원리에 대해 더 확실하게 이해할 수 있는 것 같다. 어찌저찌 여러 시행착오들을 겪으면서 앱 개발에 첫 발을 내딛게 되었다.
이젠... 진짜로 앱 개발을 시작해보자!!!
