capacitor-plugin-upgrade-v4-to-v5

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

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

使用する状況

• スナップショットで @capacitor/core がピア依存関係または開発依存関係に 4.x として表示され、プラグインを Capacitor 5 アプリで動作させる必要がある場合。
• Capacitor 5 アプリでこのプラグインをビルドすると、Namespace not specified または Java 17 に関するエラーが発生する場合。
• プラグインが CAPBridgedPlugin に手動で準拠している、または getObject()／getArray() を呼び出している場合。

次の場合は使用しないでください。

• アプリのアップグレード → capacitor-app-upgrade-v4-to-v5。
• プラグインがすでに 5 の場合 → capacitor-plugin-upgrade-v5-to-v6。複数段階の移行 → capacitor-plugin-upgrades。

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

プラグインと 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、マニフェスト、Java、Kotlin の変更を手動で適用するとき

事前確認

ツール	最小要件
Node.js	16+
Xcode	14.1+
Java	17（AGP 8）
AGP / Gradle	8.0.0 / 8.0.2
Android SDK のデフォルト値	compileSdk 33、targetSdk 33、minSdk 22
iOS のデプロイメントターゲット	13.0（変更なし）

手順

1. スナップショットでプラグインが 4.x であることを確認し、作業ツリーがクリーンであることを確認します（git status）。

2. プラグインのルートから次を実行します。

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

   これにより package.json、android/build.gradle、ラッパー、gradle.properties、マニフェストが編集されます。git diff を確認してください。

3. 手動で適用されなかった項目を仕上げます（references/android.md）。

   • @capacitor/cli、core、android、ios の開発依存関係を latest-5 にし、ピア依存関係の @capacitor/core を ^5.0.0 にします。
   • SDK のデフォルト値を 33、AGP を 8.0.0、Gradle を 8.0.2 にし、android {} に namespace を設定し、マニフェストから package= を削除して、Java 17、Jetifier の削除、Kotlin 1.8.20 と kotlin-stdlib を適用します。

4. iOS コード：プラグインが手動で CAPBridgedPlugin に準拠している場合（CAP_PLUGIN マクロを使っていない場合）、要件をインスタンスレベルに移し、pluginId を identifier に変更し、pluginMethods の型を [CAPPluginMethod] にして、getMethod(_:) を削除します。マクロベースのプラグインは変更不要です。

5. Android コード：call.getObject(key) と call.getArray(key) は null を返す場合があります。null チェックを追加し、必須の場合は明確なメッセージを付けて call.reject(...) を呼び出します。

6. サンプルアプリがある場合は、capacitor-app-upgrade-v4-to-v5 を使って Capacitor 5 に更新します。

7. プラグインのメジャーバージョンを上げ、変更履歴または README に「Requires Capacitor 5」と記載します。

検証

grep -n "\"@capacitor/" package.json                         # 5.x everywhere
grep -n "package=" android/src/main/AndroidManifest.xml      # expect none
grep -n "namespace\|VERSION_17\|gradle:8.0.0" android/build.gradle
grep -rn "kotlin-stdlib-jdk" android/build.gradle            # expect none
grep -rn "getObject(\|getArray(" android/src/main/           # each result null-checked
grep -rn "pluginId\b" ios/                                   # only CAPPlugin usages remain
npm run build
npm run verify        # plugin template script: verify:ios + verify:android + verify:web, if present
cd android && ./gradlew clean build test

両方のプラットフォームでサンプルアプリを実行し、すべてのメソッドを試してください。

エラーへの対処

エラー	修正方法
Namespace not specified	プラグインの build.gradle 内の android {} に namespace "<package>" を追加します。
Android Gradle plugin requires Java 17 to run	Gradle JDK を 17 に切り替えます。
getObject／getArray による NullPointerException	null チェックを追加します（手順 5）。
Swift：型がプロトコル CAPBridgedPlugin に準拠していない	インスタンスレベルの identifier、jsName、pluginMethods を使うか、マクロに切り替えます。
Duplicate class ... kotlin-stdlib-jdk8	kotlin-stdlib-jdk7/jdk8 を kotlin-stdlib に置き換えます。