React + Capacitor로 안드로이드 앱 실행하기 (Android Studio)

최근 React로 만든 프로젝트를 Capacitor를 이용해 안드로이드 앱으로 실행해 보았습니다. 처음 설정할 때 Gradle이나 Android Studio 버전 때문에 애를 먹었는데, 정리해 두면 다음에 훨씬 수월할 것 같아서 과정을 공유합니다.

---

1. React 프로젝트 생성

npx create-react-app projectName
cd projectName

React 앱을 기본 구조로 생성합니다.

---

2. Capacitor 설치 및 초기화

npm install @capacitor/core @capacitor/cli
npx cap init projectName com.example.projectName

• projectName → 앱 이름
• com.example.projectName → 패키지 ID (원하는 값으로 지정)

---

3. 안드로이드 플랫폼 추가

npx cap add android

명령어 실행 후 android/ 폴더가 생성됩니다.

---

4. React 앱 빌드 후 Capacitor 동기화

npm run build
npx cap copy android
npx cap sync android

React 프로젝트를 빌드하고, Capacitor를 통해 안드로이드 프로젝트와 동기화합니다.

---

5. Android Studio로 열기

npx cap open android

Android Studio가 열리면, 연결된 실제 기기나 에뮬레이터를 선택 후 실행 버튼 ▶️을 클릭하면 앱이 실행됩니다.

---

🚩 문제 해결 TIP

• Gradle Sync Fail → Android Studio를 최신 안정판(권장: Koala 2024.1.2)으로 업데이트
• capacitor.settings.gradle not found → npx cap sync android 다시 실행
• 앱 빌드 후 화면 반영 안됨 → npm run build & npx cap copy android 실행

---

정리

React + Capacitor 조합을 사용하면 기존 React 웹 코드를 재활용하면서도 안드로이드에서 앱 형태로 실행할 수 있습니다. 추후 푸시 알림이나 위치 서비스 같은 네이티브 기능도 Capacitor 플러그인을 통해 확장할 수 있습니다.