Capacitor로 웹앱을 앱스토어에 올리는 법 — 네이티브 래퍼가 뭔지부터 알아보자

1. 네이티브 래퍼란 무엇인가?

여러분이 React로 멋진 웹앱을 하나 만들었다고 가정해봅시다. 그런데 클라이언트가 갑자기 이런 말을 합니다.

"그거 앱스토어에도 올려주실 수 있나요? 아이폰이랑 안드로이드 둘 다요."

순간 머릿속에 Swift, Kotlin, Xcode, Android Studio가 스쳐 지나갑니다. 패닉이 오기 시작하죠.

바로 이때 네이티브 래퍼(Native Wrapper) 가 구원자로 등장합니다.

네이티브 래퍼란, 기존 웹 코드를 iOS·Android 네이티브 앱의 껍데기 안에 넣어주는 도구입니다. 내부적으로는 WebView라는 내장 브라우저를 띄우고, 그 안에서 여러분의 웹앱이 실행됩니다. 마치 앱처럼 보이지만, 실제로는 웹 페이지가 돌아가는 거죠.

---

2. Capacitor의 동작 원리

Capacitor는 Ionic 팀이 만든 오픈소스 네이티브 래퍼입니다. 아키텍처를 간단히 그려보면 이렇습니다.

┌─────────────────────────────────────────┐
│   웹 앱 레이어 (React / Vue / Vanilla)   │
└─────────────────────┬───────────────────┘
                      ↕
┌─────────────────────────────────────────┐
│     Capacitor Bridge (JS ↔ Native)      │
└─────────────────────┬───────────────────┘
                      ↕
┌─────────────────────────────────────────┐
│      네이티브 플랫폼 (iOS / Android)      │
│   카메라, GPS, 푸시알림, 파일시스템 등    │
└─────────────────────────────────────────┘

핵심은 가운데 있는 Capacitor Bridge입니다. 웹 코드에서 카메라를 쓰고 싶을 때, 자바스크립트가 직접 카메라에 접근할 수는 없습니다. Capacitor가 그 요청을 받아서 네이티브 API로 전달하고, 결과를 다시 JS로 돌려줍니다.

// camera.ts
import { Camera, CameraResultType } from '@capacitor/camera';

const takePhoto = async () => {
  // 이 한 줄이 iOS/Android 카메라를 호출합니다
  const image = await Camera.getPhoto({
    quality: 90,
    allowEditing: true,
    resultType: CameraResultType.Uri
  });
  console.log(image.webPath);
};

웹 개발자 입장에서 카메라, GPS, 푸시 알림 같은 네이티브 기능을 이렇게 간단하게 쓸 수 있다는 게 Capacitor의 가장 큰 매력입니다.

---

3. Cordova vs Capacitor vs React Native

비슷해 보이는 도구들이 많은데, 핵심 차이를 정리해봤습니다.

도구	만든 곳	렌더링 방식	추천 여부
Cordova	Apache	WebView	❌ 레거시 (신규 프로젝트 비추)
Capacitor	Ionic	WebView	✅ 현대적 표준, 신규 프로젝트 추천
React Native	Meta	네이티브 컴포넌트	✅ 성능 중요할 때
Flutter	Google	자체 렌더링 엔진	✅ 완전한 크로스플랫폼

💡 React Native는 엄밀히는 네이티브 래퍼가 아닙니다. JS 브릿지를 통해 실제 네이티브 UI 컴포넌트를 렌더링하는 별도의 패러다임입니다. 성능은 더 좋지만 학습 비용도 더 높습니다.

---

4. Capacitor 시작하기

설치

기존 React(또는 다른 프레임워크) 프로젝트가 있다면 그냥 붙일 수 있습니다.

# Capacitor 핵심 패키지 설치
npm install @capacitor/core @capacitor/cli

# 프로젝트 초기화
npx cap init

# iOS / Android 플랫폼 추가
npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android

capacitor.config.ts 설정

// capacitor.config.ts
import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'My App',
  webDir: 'dist',   // 빌드 결과물 폴더
  server: {
    androidScheme: 'https'
  }
};

export default config;

빌드 & 동기화

웹 코드를 빌드한 후, Capacitor로 네이티브 프로젝트에 동기화합니다.

npm run build        # 웹앱 빌드
npx cap sync         # 네이티브에 반영
npx cap open ios     # Xcode에서 열기
npx cap open android # Android Studio에서 열기

이후 Xcode나 Android Studio에서 평소처럼 빌드하고 앱스토어에 배포하면 됩니다.

자주 쓰는 공식 플러그인

npm install @capacitor/camera        # 카메라
npm install @capacitor/geolocation   # GPS
npm install @capacitor/push-notifications  # 푸시 알림
npm install @capacitor/filesystem    # 파일 시스템
npm install @capacitor/storage       # 로컬 스토리지

---

5. 장단점 및 언제 쓰면 좋을까?

✅ 장점

• 웹 지식만으로 iOS · Android 앱 출시 가능
• 기존 React / Vue 프로젝트에 빠르게 적용
• 카메라, GPS 등 네이티브 API를 JS로 접근 가능
• 풍부한 공식 플러그인 생태계
• Cordova 플러그인과 호환성 지원

❌ 단점

• 순수 네이티브 대비 성능 열위
• 복잡한 애니메이션 구현에 한계
• WebView 버전에 종속적 (구형 기기 이슈)
• 일부 고급 네이티브 기능 미지원
• 앱 용량이 다소 큼

🎯 언제 쓰면 좋을까?

추천하는 경우

• 콘텐츠 중심 앱 (뉴스, 블로그, 커머스)
• 사내 업무 도구 / 대시보드
• MVP 빠른 출시가 목표인 경우
• 기존 웹앱을 앱스토어에 올려야 하는 경우

비추하는 경우

• 게임, 영상 편집 등 GPU 집약적 앱
• 네이티브 수준의 애니메이션이 필수인 앱
• AR / VR 기능이 필요한 앱

---

6. 마무리

Capacitor는 "웹 개발자가 앱도 만들 수 있어야 한다"는 생각에서 출발합니다. 완벽한 성능을 원한다면 Swift나 Kotlin을 배워야 하지만, 빠르게 앱을 출시해야 하는 현실에서 Capacitor는 매우 실용적인 선택지입니다.

📌 핵심 요약

• 네이티브 래퍼 = 웹앱을 앱 껍데기에 넣어주는 도구
• Capacitor = WebView + JS-Native Bridge로 동작
• 기존 React/Vue 프로젝트에 npx cap init으로 바로 적용 가능
• 카메라 · GPS 등 네이티브 기능도 JS로 접근 가능
• 성능보다 개발 속도가 중요한 프로젝트에 추천

---