CapacitorでPWAをネイティブアプリに変換する

既存のPWAを、iOSおよびAndroid向けのネイティブなCapacitorモバイルアプリに変換しましょう。最小限のcode変更でPWAをパッケージングするための実践的なガイドです。

はじめに

すでに Progressive Web App をお持ちかもしれません。ブラウザで動作し、manifest があり、オフライン対応のために service worker を使用しているかもしれません。もし今後、App Store での配信やネイティブデバイス API、より優れた onboarding フネルが必要になった場合、フロントエンドを書き直すよりも Capacitor アプリへ移行する方が通常は早いです。

最大のメリットは、既存の Web code のほとんどをそのまま維持できることです。多くの場合、以下の手順だけで済みます：

本番用の Web アセットを build し、
適切な設定で Capacitor を初期化し、 webDir,
iOS と Android のプロジェクトを追加し、
必要な場所にのみネイティブプラグインを組み込む。

PWA のルートとコンポーネントロジックが整理されていれば、これにはわずか数時間しかかかりません。

前提条件

推定時間：プラットフォーム固有の機能によりますが、2〜5時間程度です。

Node.js 18以降、および Bun
既存のPWAソースコード code (React, Vue, Angular, Svelteなど)
iOSプロファイリング (iOS、macOSのみ)
デバッグ (Android用)
iOS公開予定の場合はApple Developerアカウント
Android配布用のGoogle Play Developerアカウント

ステップ 1: ネイティブでラップする前に PWA を確認する

実行前の準備 bunx cap init、ウェブアプリが本番環境に備えられているか確認してください：

PWAに本番用ビルドスクリプトがあることを確認します（例： bun run build).
ウェブの出力フォルダが決定論的であることを確認します（多くの場合、 dist, build、または out).
ブラウザ環境のみを前提とした、ハードコードされた絶対リダイレクトを削除します。
Service Workerの挙動がモバイルWebViewと互換性があるか確認します：
- ユーザーの利便性が向上する場合は、オフラインサポートを維持してください。
- 埋め込みWebViewでは利用できない、ブラウザ専用のAPIの使用を避けてください。
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
}

これにより、ネイティブコンテナ内でブラウザ専用のロジックが実行されるのを防げます。

ステップ 3: PWAフォルダ内で Capacitor を初期化する

既存のPWAルートディレクトリから：

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

アプリ名、bundle ID、およびWeb出力ディレクトリを指定して Capacitor init を実行します：

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

ビルドフォルダが build (Create React App) または out (Next.js static export) の場合は、 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/ フォルダです。Syncを行うと、ビルドされたWebアセットが両方のプラットフォームにコピーされます。

ステップ 5: Webアプリのビルドと同期

PWAをビルドしてWebアセットを同期します：

bun run build
bunx cap sync

次に、ネイティブプロジェクトを開きます：

bunx cap open ios
bunx cap open android

XcodeまたはAndroid Studioから、デバイスまたはエミュレータに接続して実行してください。

ステップ 6: 移行後のネイティブ機能の強化

必要に応じて、Web限定の機能をネイティブAPIに置き換えます：

プッシュ通知 -> @capacitor/push-notifications
セキュアなキー/バリュー保存 -> @capacitor/preferences
カメラ / メディア -> @capacitor/camera
生体認証 -> @capacitor-community/native-biometric (または任意のプラグイン)

新しいネイティブプラグインを追加する場合：

プラグインパッケージをインストール
プラグイン固有の設定を行う
実行:

bunx cap sync

その後、再ビルドして実行します。

ステップ 7: App Storeとの機能差分チェック

提出前に：

ディープリンクとルーティング（/ およびディープルート）を両プラットフォームでテストします。
ステータスバー、セーフエリア、画面の向きが正しいか確認します。
アプリの挙動と競合する、Web専用の不要なメタデータ（インストールプロンプトなど）を削除します。
App Transport Securityやプライバシー設定を、ポリシーと一致させておきます。
各プラットフォーム用のアプリアイコンとスプラッシュ画面を追加します。

OTAアップデートを利用する場合は、リリースパイプラインをネイティブ環境に適した更新戦略と組み合わせ、 Capgo 段階的なロールアウトやロールバックを検討してください。

最終チェックリスト

Webアプリのビルドが正常に完了 (bun run build)
Capacitor が適切な設定で初期化されている webDir
bunx cap add ios と bunx cap add android 完了
実機でネイティブアプリが動作することを確認
ブラウザ専用の code パスがネイティブ動作時に制限されていること
UpdateチャンネルとApp Store用アセットの設定が完了していること

PWAの開発において、すでに最も困難な作業は完了しています。Capacitorでラップすることで、以下のメリットが得られます：

アプリストアでの配信
ネイティブAPIへのアクセス
codeのフル書き換えなしでの高速なイテレーション
Webとモバイルチーム共通のデプロイフロー

このフローから開始し、分析やユーザーフィードバックに基づいてネイティブ機能を一つずつ拡張していきましょう。

CapacitorでPWAをネイティブアプリへ変換する手法の続きはこちら

使用している場合 CapacitorでPWAをネイティブアプリに変換する 移行とエンタープライズ運用を計画するには、次と連携してください Capgo エンタープライズ Capgo Enterprise のプロダクトワークフロー向けに、 Ionic Enterprise プラグインの代替案 Ionic Enterprise Plugin Alternatives のプロダクトワークフロー向けに、 Capgo の代替案 Capgo Alternatives でのプロダクトワークフロー向け、 Capgo コンサルティング Capgo Consulting でのプロダクトワークフロー向け、および Capgo プレミアムサポート Capgo Premium Support でのプロダクトワークフロー向け。