capacitor-plugin-upgrade-v5-to-v6

Capacitor プラグインを v5 から v6 にアップグレード

プラグインライブラリを Capacitor 6 に移行します。情報源：https://capacitorjs.com/docs/updating/plugins/6-0

使用するタイミング

• スナップショットで @capacitor/core が 5.x と示されており、プラグインを Capacitor 6 アプリで動作させる必要がある場合。
• definitions.ts で引き続き Promise<PluginListenerHandle> & PluginListenerHandle が宣言されている場合。
• 6 への移行と同時に SPM サポートを追加したい場合。

使用しないケース：

• アプリのアップグレード → capacitor-app-upgrade-v5-to-v6。
• プラグインが 4.x の場合 → まず capacitor-plugin-upgrade-v4-to-v5 を使用してください。6.x の場合 → capacitor-plugin-upgrade-v6-to-v7 を使用してください。複数バージョンをまたぐ場合 → capacitor-plugin-upgrades。
• SPM への完全な変換の詳細 → capacitor-plugin-spm-support。

ライブプロジェクトのスナップショット

プラグインと Capacitor パッケージのスナップショット： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=['package.name='+(pkg.name||''),'package.version='+(pkg.version||'')];for(const section of ['peerDependencies','dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.join('\n'))"

サンプルとネイティブプロジェクトのパス： !find . -maxdepth 3 \( -path './example-app' -o -path './ios' -o -path './android' \)

参考資料

ファイル	読み込むタイミング
references/android.md	Gradle または Kotlin の変更を手動で適用する場合

事前確認

ツール	最小バージョン
Node.js	18+
Xcode	15.0+
Java	17
AGP / Gradle	8.2.1 / 8.2.1
Android SDK のデフォルト値	compileSdk 34、targetSdk 34、minSdk 22
iOS のデプロイメントターゲット	13.0（変更なし）

手順

1. 5.x であること、および作業ツリーがクリーンであることを確認します。

2. プラグインのルートで実行します。

   npx @capacitor/plugin-migration-v5-to-v6@latest
   

   git diff を確認します。

3. 手動で仕上げます（references/android.md）：開発用依存関係を latest-6 に、ピア依存関係の @capacitor/core を ^6.0.0 に設定し、compileSdk（compileSdkVersion ではありません）のデフォルトを 34、targetSdkVersion のデフォルトを 34、AGP を 8.2.1、Gradle を 8.2.1、Kotlin を 1.9.10 にします。

4. definitions.ts：すべての addListener オーバーロードの戻り値を Promise<PluginListenerHandle> のみにします。

     addListener(
       eventName: 'resume',
       listenerFunc: () => void,
   - ): Promise<PluginListenerHandle> & PluginListenerHandle;
   + ): Promise<PluginListenerHandle>;
   

   web.ts と README／docgen の出力も同様に更新します。同期ハンドルを使用していた利用者にとって、これは破壊的変更です。

5. iOS：プラグインの .m ファイルから CAP_PLUGIN_METHOD(removeAllListeners, CAPPluginReturnPromise); を削除します。これはすべてのプラグインで標準実装になりました。

6. 任意の SPM 対応：Capacitor 6 では実験的な SPM サポートが追加されます。今追加するかユーザーに確認します。希望する場合は capacitor-plugin-spm-support に従います（Package.swift の追加、Swift での CAPBridgedPlugin 適合）。

7. capacitor-app-upgrade-v5-to-v6 を使用してサンプルアプリをアップグレードし、プラグインのメジャーバージョンを上げ、「Requires Capacitor 6」と記載します。

検証

grep -n "\"@capacitor/" package.json                               # 6.x
grep -rn "& PluginListenerHandle" src/                             # expect none
grep -rn "removeAllListeners" ios/ --include=*.m 2>/dev/null       # expect none
grep -n "compileSdkVersion project\|gradle:8.2.1" android/build.gradle   # compileSdk + 8.2.1
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties   # gradle-8.2.1
npm run build
npm run verify        # if the repo has the template verify scripts

両方のプラットフォームでサンプルアプリを実行し、各リスナーを追加および削除します。

エラー処理

エラー	修正方法
サンプル／テストでの TS エラー：Property 'remove' does not exist on type 'Promise<PluginListenerHandle>'	addListener の呼び出しに await を付けます。
compileSdkVersion に関する AGP の非推奨警告	compileSdk を使用します。
.m ファイルに removeAllListeners がまだ記載されている	CAP_PLUGIN_METHOD の行を削除します（手順 5）。このメソッドは標準実装です。
サンプルアプリで @capacitor/core に関する ERESOLVE が発生する	ピア依存関係の範囲がまだ ^5 です。^6.0.0 に設定します。