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

소개

Progressive Web App이 이미 있습니다. 브라우저에서 작동하고 매니페스트가 있으며 오프라인 지원을 위해 서비스 워커를 사용하는 경우가 있습니다. 앱 스토어 배포, 네이티브 디바이스 API 또는 온보딩 채널을 개선해야 하는 경우 Capacitor 앱으로 마이그레이션하는 것이 프론트 엔드 다시 작성하는 것보다 일반적으로 더 빠릅니다.

가장 큰 장점은 대부분의 기존 웹 code를 유지하는 것입니다. 대부분의 경우에 다음만 필요합니다:

프로덕션 웹 자산을 빌드합니다.
Capacitor를 올바른 것으로 초기화합니다. webDir,
iOS 및 Android 프로젝트를 추가합니다.
필요한 경우 네이티브 플러그인을 연결합니다.

PWA가 깨끗한 경로와 컴포넌트 논리를 가지고 있다면 이 작업은 몇 시간 만에 끝낼 수 있습니다.

필수 조건

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

Node.js 18세 이상과 Bun
code (React, Vue, Angular, Svelte, etc.)가 있는 현재 PWA 소스
Xcode (iOS, macOS 전용)
Android Studio (Android 전용)
iOS를 배포하려면 Apple Developer 계정이 필요합니다.
Android 배포를 위해 Google Play Developer 계정이 필요합니다.

1단계: PWA를 네이티브로 wrapping하기 전에 확인하세요.

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

웹 앱을 네이티브 앱으로 변환하는 방법 bun run build).
웹 앱의 빌드 스크립트가 프로덕션 빌드 스크립트인지 확인하세요 (예를 들어) dist, build웹 앱의 출력 폴더가 결정적인지 확인하세요 (일반적으로) out).
하드 코딩된 절대적인 리다이렉트를 제거하세요. 이 리다이렉트는 브라우저 전용 컨텍스트를 가정합니다.
서비스 워커의 동작이 모바일 웹 뷰와 호환되는지 확인하세요:
- 오프라인 지원을 유지하세요. 이 오프라인 지원이 사용자에게 도움이 된다면.
- 브라우저 전용 API를 사용하지 마세요. 이 API는 임베디드 웹 뷰에서 사용할 수 없습니다.
웹 앱 설치提示와 브라우저 전용 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 루트에서:

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

Capacitor init 명령어를 실행하여 앱 이름, 번들 ID, 웹 출력 디렉토리를 지정합니다.

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

빌드 폴더가 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

Step 4: 네이티브 플랫폼 추가

핵심 네이티브 패키지를 설치하고 프로젝트 폴더를 생성합니다.

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

Capacitor은 ios/ 폴더를 생성하고, 빌드된 웹 자산을 두 플랫폼에同步합니다. android/ 그리고

Step 5: 웹 앱을 빌드하고 동기화

PWA를 빌드하고 웹 자산을 동기화:

bun run build
bunx cap sync

현재 네이티브 프로젝트를 열어보세요:

bunx cap open ios
bunx cap open android

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

Step 6: 네이티브 앱으로의 마이그레이션 후

이제 네이티브 API에서 웹 전용 기능을 대체하세요:

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

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

설치 플러그인 패키지를 설치하세요.
플러그인에 대한 설정을 구성하세요.
Run:

bunx cap sync

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

7단계: 앱스토어 동일성 검사

제출하기 전에:

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

OTA 업데이트를 사용하는 앱이 있다면, 릴리스 PIPELINE을 Native-safe 업데이트 전략과 Pair하고 Consider하세요. Capgo 제어된 롤아웃과 롤백을 위해.

최종 체크리스트

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

PWA를 빌드한 대부분의 어려운 작업을 이미 수행했습니다. Capacitor으로 wrapping하면:

배포 채널,
자연어 API에 대한 접근,
code 재작성 없이 빠른 반복,
웹 및 모바일 팀이 하나의 배포 경로를 사용할 수 있도록 하는 것.

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

Transform Your PWA를 Capacitor로 Native 앱으로 변환하세요.

__CAPGO_KEEP_0__를 사용 중이라면, Transform Your PWA를 Capacitor로 Native 앱으로 변환하세요. 계획 및 기업 운영을 위한 이주와 Enterprise 운영을 계획하고 싶다면, __CAPGO_KEEP_0__ Enterprise와 연결하세요. Capgo Enterprise의 제품 워크플로, for the product workflow in Capgo Enterprise, __CAPGO_KEEP_0__ Enterprise Capacitor 제품 워크플로우에 대하여 Capgo 대체 for the product workflow in Capgo Alternatives, Capgo 컨설팅 Capacitor 제품 워크플로우에 대하여 Capgo 컨설팅, Capgo 프리미엄 지원 Capacitor 제품 워크플로우에 대하여 Capgo 프리미엄 지원.

Capacitor을 이용한 PWA를 네이티브 앱으로 변환하기

소개