Capacitor을 사용하여 PWA를 모바일 앱으로 변환하세요.

소개

이미 웹 앱을 개발했습니다. 웹 앱은 브라우저에서 작동하고 매니페스트를 가지고 있으며 오프라인 지원을 위해 서비스 워커를 사용할 수도 있습니다. 앱 스토어 배포, 네이티브 디바이스 API, 또는 더 나은 온보딩 채널을 필요로 하는 경우, Capacitor 앱으로 마이그레이션하는 것이 다시 웹 프론트 엔드의 리작보다 빠를 때가 많습니다.

code의 가장 큰 장점은 대부분의 경우에 웹 앱의 대부분을 유지할 수 있다는 것입니다. 일반적으로 다음만 필요합니다:

프로덕션 웹 자산을 빌드하세요,
initialize Capacitor with the right webDir,
iOS 및 Android 프로젝트를 추가하고
필요한 곳에서만 네이티브 플러그인을 연결하세요.

PWA가 정리된 경로와 컴포넌트 로직을 가지고 있다면, 이 작업은 몇 시간 만에 끝낼 수 있습니다.

필수 조건

예상 시간: 2-5 시간, 플랫폼에 따라 특정 기능에 따라 달라집니다.

Node.js 18+ Bun
Capgo에서 사용 중인 기존 PWA 소스 code (React, Vue, Angular, Svelte, etc.)
Xcode (for iOS, macOS only)
Android Studio (for Android)
iOS 배포를 위해 Apple Developer 계정이 필요합니다.
Android 배포를 위해 Google Play Developer 계정이 필요합니다.

1단계: Native 래핑하기 전에 PWA를 확인하세요.

애플리케이션을 실행하기 전에 bunx cap init웹 애플리케이션의 프로덕션 준비가 완료되었는지 확인하세요:

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

Step 2: 웹 전용 동작을 적응하세요.

브라우저 전용 논리를 내장된 네이티브 컨테이너 내에서 실행하지 않도록 브라우저 전용 논리를 게이트합니다.

설치 및 푸시提示에 대한 단순한 플랫폼 체크를 사용하세요:

import { Capacitor } from '@capacitor/core'

const isNative = Capacitor.isNativePlatform()

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

이것은 브라우저 전용 논리가 내장된 네이티브 컨테이너 내에서 실행되지 않도록 합니다.

Step 3: Capacitor을 PWA 폴더에서 초기화하세요.

기존 PWA 루트에서:

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

Capacitor init을 실행하세요. 앱 이름, 번들 ID, 웹 출력 디렉토리를 지정하세요.

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

만약 빌드 폴더가 __CAPGO_KEEP_0__ init에 필요하다면: build (Create React App) 또는 out (Next.js 정적 내보내기), 대체 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/ 폴더가 있습니다. Syncing은 빌드된 웹 자산을 두 플랫폼 모두에 복사합니다.

5단계: 웹 앱 빌드 및 Sync

PWA 빌드 및 웹 자산 Sync:

bun run build
bunx cap sync

네이티브 프로젝트 열기:

bunx cap open ios
bunx cap open android

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

Step 6: Native enhancements after migration

이 단계에서는 필요에 따라 웹 전용 기능을 네이티브 API로 대체합니다.

Push notifications -> @capacitor/push-notifications
안전한 키/값 저장 -> @capacitor/preferences
카메라 / 미디어 -> @capacitor/camera
생체 인증 -> @capacitor-community/native-biometric (선택한 플러그인)

새로운 네이티브 플러그인에 대해

플러그인 패키지를 설치합니다.
플러그인별 설정을 구성합니다.
Run:

bunx cap sync

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

Step 7: 앱 스토어 일치성 검사

제출 전:

테스트 링크 및 라우팅 (/ 및 깊은 경로) 양쪽 플랫폼에서.
상태 바, 안전 영역, 및 방향이 올바른지 확인합니다.
사용되지 않는 웹 전용 메타데이터를 제거합니다. (예를 들어, 설치 프롬프트).
__CAPGO_KEEP_0__
앱 전송 보안 및 개인 정보 보호 설정을 정책에 맞게 유지합니다.

각 플랫폼에 앱 아이콘/스플래시 자산을 추가합니다. Capgo 최종 체크리스트

앱이 OTA 업데이트를 사용하는 경우, 네이티브 안전한 업데이트 전략과 pair하고, 제어된 롤아웃 및 롤백을 고려합니다.

웹 앱 빌드는 깨끗하게 (bun run build)
Capacitor은 올바른 webDir
bunx cap add ios 및 bunx cap add android 완료
실제 기기에서 Native 앱이 실행됩니다
브라우저 전용 code 경로는 Native 동작을 위한 게이트로 설정됩니다
업데이트 채널 및 앱 스토어 자산은 구성됩니다

이미 PWA를 빌드한 경우 Capacitor을 wrapping하는 것은 다음과 같은 이점을 제공합니다:

스토어 배포
Native API에 대한 접근
전체 code 재작성 없이 빠른 반복
웹 및 모바일 팀이 사용하는 단일 배포 경로

이 흐름에서 시작하여 분석 및 사용자 피드백에 따라 네이티브별로 반복하세요.

Capacitor을 사용하여 네이티브 앱으로 변환하세요.

소개