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

Introduction

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

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

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

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

Prerequisites

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

Node.js 18세 이상 Bun
code (React, Vue, Angular, Svelte, etc.)
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는 임베디드 웹 뷰에서 사용할 수 없습니다.
Confirm PWA install prompts and browser-specific UX still make sense. In a Capacitor app, app install prompts are usually not needed.

앱 UI를 유지하고 브라우저 전용 논리를 게이트하세요.

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

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

import { Capacitor } from '@capacitor/core'

const isNative = Capacitor.isNativePlatform()

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

__CAPGO_KEEP_0__ 앱에서 앱 설치 알림과 브라우저 전용 UX가 여전히 의미가 있는지 확인하세요. 일반적으로 앱 설치 알림이 필요하지 않습니다.

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

만약 빌드 폴더가 build (Create React App) 또는 out (Next.js 정적 내보내기), dist.

Capacitor config을 기본으로 설정하세요.

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/ 폴더를 생성했습니다. Syncing은 빌드된 웹 자산을 두 플랫폼에 복사합니다. android/ __CAPGO_KEEP_0__ init 명령어를 실행하세요.

__CAPGO_KEEP_0__:

__CAPGO_KEEP_1__:

bun run build
bunx cap sync

__CAPGO_KEEP_2__:

bunx cap open ios
bunx cap open android

__CAPGO_KEEP_3__:

__CAPGO_KEEP_4__:

__CAPGO_KEEP_5__:

__CAPGO_KEEP_6__: @capacitor/push-notifications
__CAPGO_KEEP_7__: @capacitor/preferences
__CAPGO_KEEP_8__: @capacitor/camera
__CAPGO_KEEP_9__: @capacitor-community/native-biometric __CAPGO_KEEP_10__:

__CAPGO_KEEP_11__:

__CAPGO_KEEP_0__
플러그인 설정을 구성하세요.
Run:

bunx cap sync

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

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

제출하기 전에:

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

앱이 OTA 업데이트를 사용하는 경우, 릴리스 PIPELINE을 Pair하여 Native-safe 업데이트 전략과 함께 고려하십시오. Capgo controlled rollout 및 rollback을위한 __CAPGO_KEEP_0__

Final checklist

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

애플리케이션을 빌드할 때 이미 대부분의 어려운 작업을 수행했습니다. Capacitor를 wrapping하여 다음을 제공합니다:

배포를 위한 저장소
원시 API에 대한 접근
code 재작성 없이 빠른 반복
웹 및 모바일 팀을 위한 단일 배포 경로

이 흐름에서 시작하여 분석 및 사용자 피드백에 따라 원시-원시로 반복

Capacitor를 사용하여 PWA를 원시 앱으로 변환

이러한 기능을 사용 중이라면 Capacitor를 사용하여 PWA를 원시 앱으로 변환 이동 및 기업 운영을 위한 계획과 연결하려면 Capgo Enterprise Capgo Enterprise의 제품 워크플로우 Ionic Enterprise Plugin 대체 Ionic Enterprise Plugin 대체 제품의 제품 워크플로에 대해 Capgo Alternatives Capgo 제품 워크플로에 대해 Capgo Consulting Capgo 제품 워크플로에 대해 Consulting, 그리고 Capgo Premium Support Capgo 제품 워크플로에 대해 Premium Support.

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