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

소개

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

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

프로덕션 웹 자산을 빌드하세요.
Capacitor을 올바르게 초기화하세요. webDir,
iOS 및 Android 프로젝트를 추가하세요.
필요한 경우에만 네이티브 플러그인을 연결하세요.

클린 루트와 컴포넌트 로직이 있는 PWA가 있다면, 이 작업은 몇 시간 만에 완료될 수 있습니다.

필수 조건

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

Node.js 18 이상과 Bun
이미 존재하는 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__
모바일 웹뷰와 호환되는 서비스 워커 동작을 확인하십시오:
- 사용자가 도움이 되는 경우 오프라인 지원을 유지하십시오.
- 임베디드 웹뷰에서 사용할 수 없는 브라우저 전용 API를 피하십시오.
PWA 설치提示와 브라우저 전용 UX가 여전히 의미가 있는지 확인하십시오. 일반적으로 Capacitor 앱에서 앱 설치提示는 필요하지 않습니다.

Step 2: 웹 전용 동작을 적응하십시오.

앱 UI를 유지하고 브라우저 전용 논리를 게이트하십시오.

설치 및 푸시提示에 대한 간단한 플랫폼 체크를 사용하십시오:

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 (선택한 플러그인)

Capgo에서 새로운 네이티브 플러그인을 설치할 때마다:

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

bunx cap sync

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

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

제출 전:

테스트 링크 및 라우팅 (/ 및 깊은 경로) 양쪽 플랫폼에서.
상태 바, 안전 영역 및 방향이 올바른지 확인합니다.
사용되지 않는 웹 전용 메타데이터를 제거합니다. 이 메타데이터는 앱 동작과 충돌하는 경우 (예: 설치 프롬프트).
앱 전송 보안 및 개인 정보 보호 설정을 정책에 맞게 유지합니다.
각 플랫폼에 앱 아이콘/스플래시 자산을 추가합니다.

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

최종 체크리스트

웹 앱 빌드는 깨끗하게 (bun run build)
Capacitor이 올바르게 초기화되었습니다. webDir
bunx cap add ios 와 bunx cap add android 완료
실제 기기에서 네이티브 앱을 실행합니다.
브라우저 전용 code 경로는 네이티브 동작을 위해 게이트웨이됩니다.
업데이트 채널 및 앱 스토어 자산이 구성됩니다.

웹 앱을 빌드할 때 이미 대부분의 어려운 작업을 이미 수행했습니다. Capacitor에 wrapping하면 다음과 같은 이점이 있습니다.

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

Start from this flow, then iterate native-by-native based on analytics and user feedback.

Capacitor을 시작으로, Capacitor을 Capacitor에 따라 반복하세요. 분석 및 사용자 피드백을 기반으로 하세요.

__CAPGO_KEEP_0__를 사용하고 있다면 Capacitor을 시작으로, Capacitor을 Capacitor에 따라 반복하세요. __CAPGO_KEEP_0__을 사용하여 __CAPGO_KEEP_0__을 계획하고 __CAPGO_KEEP_0__ 운영을 위해 연결하세요. Capgo Enterprise를 사용하여 Capgo Enterprise의 제품 워크플로우를 관리하세요. Capgo Enterprise를 사용하여 Ionic Enterprise Plugin Alternatives의 제품 워크플로우를 관리하세요. __CAPGO_KEEP_0__ Alternatives를 사용하여 Ionic Enterprise Plugin Alternatives의 제품 워크플로우를 관리하세요. __CAPGO_KEEP_0__ Alternatives를 사용하여 __CAPGO_KEEP_0__ Alternatives의 제품 워크플로우를 관리하세요. Capgo Consulting을 사용하세요. Capgo Consulting을 사용하여 Capgo Alternatives의 제품 워크플로우를 관리하세요. Capgo Consulting을 사용하여 Capgo Enterprise의 제품 워크플로우를 관리하세요. Capgo 제품 워크플로우에서 Capgo 컨설팅을 위해 사용합니다. Capgo 프리미엄 지원 Capgo 프리미엄 지원 제품 워크플로우에서 사용합니다.

Capacitor으로 PWA를 네이티브 앱으로 변환하세요.

소개