Capacitor로 PWA를 Native App으로 전환하기

기존의 Progressive Web App을 iOS 및 Android용 네이티브 Capacitor 모바일 앱으로 변환하세요. 최소한의 code 변경만으로 PWA를 패키징하는 실무 가이드를 소개합니다.

소개

이미 Progressive Web App을 보유하고 계실 겁니다. 브라우저에서 작동하고, manifest가 있으며, 오프라인 지원을 위해 service worker를 사용하고 있을 수도 있죠. 만약 이제 App Store 배포, 네이티브 디바이스 API, 또는 더 나은 onboarding 퍼널이 필요하다면, 프론트엔드를 새로 작성하는 것보다 Capacitor 앱으로 마이그레이션하는 것이 훨씬 빠릅니다.

가장 큰 장점은 기존 웹 code를 거의 그대로 유지할 수 있다는 점입니다. 대부분의 경우, 다음 작업만 수행하면 됩니다:

production 웹 에셋 build
올바른 설정으로 Capacitor를 초기화하고, webDir,
iOS 및 Android 프로젝트를 추가한 뒤,
필요한 곳에만 네이티브 플러그인을 연결하세요.

PWA의 라우팅과 컴포넌트 로직이 깔끔하다면, 단 몇 시간 만에 끝낼 수 있습니다.

사전 요구사항

예상 소요 시간: 플랫폼별 기능에 따라 2~5시간.

Node.js 18 버전 이상, Bun
기존 PWA 소스 code (React, Vue, Angular, Svelte 등)
iOS 프로파일링 (iOS, macOS 전용)
디버깅하기 (Android 전용)
iOS 배포를 위한 Apple Developer 계정
Android 배포를 위한 Google Play Developer 계정

1단계: 네이티브로 전환하기 전 PWA 점검

실행하기 전에 bunx cap init, 웹 앱이 프로덕션 준비가 되었는지 확인하세요:

PWA에 프로덕션 빌드 스크립트가 있는지 확인하세요 (예: bun run build).
웹 출력 폴더가 결정론적인지 확인하세요 (보통 dist, build, 또는 out).
브라우저 환경만 가정하는 하드코딩된 절대 경로 리다이렉트를 제거하세요.
서비스 워커 동작이 모바일 WebView와 호환되는지 확인하세요:
- 사용자에게 도움이 된다면 오프라인 지원을 유지하세요.
- 임베디드 웹뷰에서 사용할 수 없는 브라우저 전용 API는 피해야 합니다.
PWA 설치 프롬프트와 브라우저 전용 UX가 여전히 적절한지 확인하세요. Capacitor 앱에서는 보통 앱 설치 프롬프트가 필요하지 않습니다.

2단계: 웹 전용 동작 최적화

앱 UI는 유지하되, 브라우저 전용 로직은 제한하세요.

설치 및 푸시 프롬프트 주변에 간단한 플랫폼 체크를 추가하세요:

import { Capacitor } from '@capacitor/core'

const isNative = Capacitor.isNativePlatform()

function registerInstallPrompt() {
  if (isNative) return
  // existing browser-only install or Web Push code
}

이렇게 하면 네이티브 컨테이너 내부에서 브라우저 전용 로직이 실행되는 것을 방지할 수 있습니다.

3단계: PWA 폴더에 Capacitor 초기화

기존 PWA 루트 디렉토리에서:

bun add @capacitor/core
bun add -D @capacitor/cli

앱 이름, bundle ID, 웹 출력 디렉토리를 사용하여 Capacitor init을 실행하세요:

bunx cap init MyPWAApp com.example.my-pwa-app --web-dir dist

빌드 폴더가 build (Create React App) 또는 out (Next.js static export)를 교체하세요. dist.

기본 Capacitor 설정을 추가하세요:

import type { CapacitorConfig } from '@capacitor/cli'

const config: CapacitorConfig = {
  appId: 'com.example.my-pwa-app',
  appName: 'MyPWAApp',
  webDir: 'dist',
  server: {
    iosScheme: 'https',
  },
}

export default config

4단계: 네이티브 플랫폼 추가

핵심 네이티브 패키지를 설치하고 프로젝트 폴더를 생성하세요:

bun add @capacitor/ios @capacitor/android
bunx cap add ios
bunx cap add android

이제 Capacitor가 ios/ 및 android/ 폴더를 생성했습니다. Sync를 실행하면 빌드된 웹 에셋이 두 플랫폼 모두에 복사됩니다.

5단계: 웹 앱 빌드 및 Sync

PWA를 빌드하고 웹 에셋을 Sync하세요:

bun run build
bunx cap sync

이제 네이티브 프로젝트를 여세요:

bunx cap open ios
bunx cap open android

Xcode 또는 Android Studio에서 디바이스나 에뮬레이터를 연결하고 실행하세요.

6단계: 마이그레이션 후 Native 기능 강화

필요에 따라 웹 전용 기능을 Native API로 교체합니다:

푸시 알림 -> @capacitor/push-notifications
보안 키/값 저장소 -> @capacitor/preferences
카메라 / 미디어 -> @capacitor/camera
생체 인증 -> @capacitor-community/native-biometric (또는 원하는 플러그인)

새로운 Native 플러그인을 추가할 때마다:

플러그인 패키지 설치
플러그인별 설정 구성
실행:

bunx cap sync

그 다음 다시 빌드하고 실행하세요.

7단계: 앱 스토어 출시 전 최종 점검

제출 전:

양쪽 플랫폼 모두에서 딥링크와 라우팅(/ 및 딥 라우트를 테스트하세요.
상태 표시줄, 세이프 에어리어, 화면 방향이 올바른지 확인하세요.
앱 동작과 충돌하는 웹 전용 메타데이터(예: 설치 프롬프트)를 제거하세요.
앱 전송 보안 및 개인정보 설정이 정책과 일치하도록 유지하세요.
각 플랫폼에 맞는 앱 아이콘과 스플래시 에셋을 추가하세요.

OTA 업데이트를 사용하는 경우, 릴리스 파이프라인을 네이티브 환경에 안전한 업데이트 전략과 결합하고, Capgo 제한적 배포(rollout) 및 롤백 방안을 고려하세요.

최종 체크리스트

웹 앱 빌드 성공 (bun run build)
Capacitor가 올바르게 초기화됨) webDir
bunx cap add ios 및 bunx cap add android 완료
실제 기기에서 실행되는 Native 앱
브라우저 전용 code 경로는 네이티브 동작을 위해 제한됨
업데이트 채널 및 앱 스토어 에셋 설정 완료

PWA를 구축하며 이미 대부분의 어려운 작업을 마쳤습니다. Capacitor로 래핑하면 다음과 같은 이점이 있습니다:

스토어 배포,
Native API 접근,
전체 code 재작성 없는 빠른 반복 개발,
웹 및 모바일 팀을 위한 단일 배포 경로.

이 워크플로우로 시작한 뒤, 분석 데이터와 사용자 피드백을 바탕으로 네이티브 기능을 하나씩 점진적으로 구현해 나가세요.

Capacitor를 사용하여 PWA를 네이티브 앱으로 전환하기

사용 중이라면 Capacitor로 PWA를 Native App으로 전환하기 마이그레이션과 엔터프라이즈 운영을 계획하려면 다음과 연결하세요: Capgo 엔터프라이즈 Capgo Enterprise의 제품 워크플로우를 위해, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우를 위해, Capgo 대안 Capgo Alternatives의 제품 워크플로우용, Capgo 컨설팅 Capgo Consulting의 제품 워크플로우용, Capgo 프리미엄 지원 Capgo Premium Support의 제품 워크플로우용.