Progressive Web App을 네이티브 앱으로 변환하는 Capacitor

Transform Your PWA to a Native App with Capacitor

Convert an existing Progressive Web App into a native Capacitor mobile app for iOS and Android. A practical guide to packaging your PWA with minimal code changes.

작성

마틴 도나디유

작가

발레리아

리뷰어

조던

편집자

소개

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

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

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

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

사전 요구 사항

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

Node.js 18+ Bun
이미 존재하는 PWA 소스 code (React, Vue, Angular, Svelte, etc.)
Xcode (iOS, macOS 전용)
안드로이드 스튜디오 (Android 전용)
iOS 배포를 위한 Apple Developer 계정
Android 배포를 위한 Google Play Developer 계정

1단계: Capgo에서 PWA를 네이티브 앱으로 변환하기 전에 PWA를 확인하세요.

실행하기 전에 bunx cap init생산 환경에서 웹 앱이 준비되어 있는지 확인하세요:

생산 환경에서 PWA를 빌드하는 스크립트가 있는지 확인하세요 (예를 들어, bun run build).
웹 앱 출력 폴더가 결정적인지 확인하세요 (일반적으로 dist, build, or out).
서비스 워커의 동작이 모바일 웹 뷰와 호환되는지 확인하세요:
오프라인 지원을 유지하세요. 오프라인 지원이 사용자에게 도움이 된다면.
- 브라우저 전용 API를 피하세요. 이 API는 웹 뷰에 내장된 웹뷰에서 사용할 수 없습니다.
- PWA 설치提示와 브라우저 전용 UX가 여전히 의미가 있는지 확인하세요. Capgo 앱에서 일반적으로 설치提示가 필요하지 않습니다.
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
}

이것은 네이티브 컨테이너 내에서 브라우저 전용 로직이 실행되는 것을 피합니다.

Step 3: Capgo를 사용하여 PWA 폴더에 Capacitor을 초기화하세요.

기존 PWA 루트에서:

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

애플리케이션 이름, 번들 ID, 웹 출력 디렉토리와 함께 Capacitor init 명령을 실행하세요.

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

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

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

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

이 단계에서 Capacitor은 ios/ 그리고 android/ 폴더에 저장됩니다. 동기화는 웹 앱을 빌드하여 두 플랫폼 모두에 복사합니다.

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

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

bun run build
bunx cap sync

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

bunx cap open ios
bunx cap open android

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

6단계: 네이티브 업그레이드 후

이것은 웹 전용 기능을 네이티브 API로 대체해야 하는 곳입니다:

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

새로운 네이티브 플러그인마다:

플러그인 패키지를 설치하세요
플러그인별 설정을 구성하세요
Run:

bunx cap sync

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

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

제출하기 전에:

양쪽 플랫폼에서 깊이 있는 링크 및 라우팅 (/ 및 깊이 있는 루트) 테스트하세요.
상태 바, 안전 영역 및 방향이 올바른지 확인하세요.
사용하지 않는 웹 전용 메타데이터를 제거하세요. 예를 들어, 설치提示와 같은 앱 동작과 충돌하는 항목입니다.
앱의 전송 보안 및 개인 정보 보호 설정을 정책에 맞게 유지하세요.
각 플랫폼에 대한 앱 아이콘/스플래시 자산을 추가하세요.

앱이 OTA 업데이트를 사용하는 경우, 릴리스 PIPELINE을 네이티브로 안전한 업데이트 전략과 pair하고, 제어된 롤아웃 및 롤백을 고려하세요. Capgo 제어된 롤아웃 및 롤백을 위해.

최종 체크리스트

웹 앱 빌드가 깨끗하게 작동합니다. (bun run build)
Capacitor이 올바른 webDir
bunx cap add ios 그리고 bunx cap add android 완료
네이티브 앱이 실제 장치에서 작동합니다.
브라우저 전용 code 경로들은 네이티브 동작을 위해 게이트드입니다.
업데이트 채널과 앱 스토어 자산은 구성되었습니다.

Capacitor로.wrap하는 것은 PWA를 빌드할 때 이미 대부분의 어려운 작업을했습니다. Capacitor로 wrap하면 다음과 같은 이점이 있습니다:

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

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

Transform Your PWA를 네이티브 앱으로 변환하는 Capacitor로 계속 진행하세요.

__CAPGO_KEEP_0__를 사용하여 마이그레이션 및 기업 운영을 계획하고 연결하세요. Capacitor를 사용하여 마이그레이션 및 기업 운영을 계획하고 연결하세요. __CAPGO_KEEP_0__를 사용하여 마이그레이션 및 기업 운영을 계획하고 연결하세요. Capgo 기업 Capgo 기업 workflow를 위한 아이온 Enterprise 플러그인 대체 아이온 Enterprise 플러그인 대체 workflow를 위한 Capgo 대체 Capgo 대체 workflow를 위한 Capgo 컨설팅 Capgo 컨설팅 workflow를 위한, Capgo 프리미엄 지원 Capgo 프리미엄 지원 workflow를 위한.