capacitor-plugin-upgrade-v7-to-v8

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

プラグインライブラリを Capacitor 8 に移行します。正確な情報は https://capacitorjs.com/docs/updating/plugins/8-0 を参照してください。

使用する状況

• スナップショットで @capacitor/core が 7.x と表示され、プラグインを Capacitor 8 アプリで動作させる必要がある場合。
• Kotlin 2.2 に対してプラグインをビルドすると、kotlinOptions または kotlin-android-extensions で失敗する場合。
• Gradle が Properties should be assigned using the 'propName = value' syntax と警告する場合。

使用しないでください：

• アプリのアップグレード → capacitor-app-upgrade-v7-to-v8。
• プラグインが 6.x の場合 → まず capacitor-plugin-upgrade-v6-to-v7 を使用します。複数段階の移行 → capacitor-plugin-upgrades。
• プラグインがすでに 8.x の場合 → capacitor-plugin-upgrade-v8-to-v9。
• 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	依存関係のデフォルト値、SDK、AGP／Gradle、= 構文、Java 21、Kotlin 2.2 の変更
references/ios.md	podspec／Package.swift／旧構造プロジェクトの iOS 15、capacitor-swift-pm 8

事前確認

ツール	最小バージョン
Node.js	22+
Xcode	26.0+
iOS デプロイメントターゲット	15.0
Java	21 を推奨（AGP 8.13 では 17+ をサポート）
AGP／Gradle	8.13.0／8.14.3
Android SDK のデフォルト値	minSdk 24、compileSdk 36、targetSdk 36
Kotlin（使用する場合）	2.2.20

手順

1. 7.x であることと、ワーキングツリーがクリーンであることを確認します。

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

   npx @capacitor/plugin-migration-v7-to-v8@latest
   

   git diff を確認します。

3. package.json：開発依存関係の @capacitor/cli、core、android、ios を ^8.0.0 に更新し、ピア依存関係の @capacitor/core を >=8.0.0 に更新します。

4. Android は references/android.md に従います：

   • プラグインが実際に使用する依存関係のデフォルト値のみを ext {} に追加または更新します。
   • SDK のデフォルト値を 24／36／36、AGP を 8.13.0、Gradle を 8.14.3、google-services を 4.4.4（使用する場合）にします。
   • すべてのプロパティ代入を = に変換します（namespace = ...、compileSdk = ...、url = ...、abortOnError = ...）。mavenCentral() などのメソッド呼び出しは変更しません。
   • compileOptions を Java 21 にします。
   • Kotlin プラグイン：kotlin_version を 2.2.20 にし、kotlinOptions {} を kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_21 } } に置き換え、kotlin-android-extensions を削除します（kotlin-parcelize／ビュー バインディングを使用します）。
   • R.layout.bridge_layout_main を参照するコードでは、capacitor_bridge_layout_main を使用する必要があります。

5. iOS は references/ios.md に従います：podspec を 15.0、Package.swift を .iOS(.v15)、capacitor-swift-pm を from: "8.0.0" にします。プラグイン自身が .capacitorViewDidAppear／.capacitorViewWillTransition を通知していた場合は、そのコードを削除します。Capacitor 8 が通知します。

6. capacitor-app-upgrade-v7-to-v8 を使ってサンプルアプリをアップグレードし、プラグインのメジャーバージョンを上げ、「Capacitor 8 が必要」と記載します。

8.x 以降：次の手順

• Capacitor 8.5 アプリでは iOS UIScene ライフサイクルを採用します（Xcode 27 で必須）。AppDelegate のメソッド（application(_:open:options:)、continue userActivity、applicationDidBecomeActive、...）をフックする、または UIApplication.shared.windows／keyWindow を使用するプラグインは、シーンベースのアプリに対応する必要があります。capacitor-uiscene-migration を参照してください。
• その後、capacitor-plugin-upgrade-v8-to-v9 を使用します（Capacitor 9 は GA ではなく next です）。

検証

grep -n "\"@capacitor/" package.json                                    # ^8.0.0 / >=8.0.0
grep -nE "^\s*(namespace|compileSdk|url|abortOnError|minSdkVersion|targetSdkVersion) [^=]" android/build.gradle   # expect none
grep -n "kotlinOptions\|kotlin-android-extensions" android/build.gradle # expect none
grep -n "VERSION_21\|gradle:8.13.0" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties   # gradle-8.14.3
grep -rn "bridge_layout_main" android/src | grep -v capacitor_bridge   # expect none
grep -n "deployment_target" *.podspec                                  # '15.0'
grep -n "iOS(\|capacitor-swift-pm" Package.swift 2>/dev/null           # .v15, from: "8.0.0"
npm run build
npm run verify         # if the repo has the template verify scripts
cd android && ./gradlew build --warning-mode all

両方のプラットフォームでサンプルアプリを実行します。

エラー処理

エラー	修正方法
Properties should be assigned using the 'propName = value' syntax	プロパティの代入に = を追加します。
Kotlin：Kotlin 2.2 で kotlinOptions が非推奨またはエラーになる	import org.jetbrains.kotlin.gradle.dsl.JvmTarget を指定し、kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_21 } } を使用します。
Plugin [id: 'kotlin-android-extensions'] was not found	削除し、kotlin-parcelize とビューバインディングを使用します。
Inconsistent JVM-target compatibility detected for tasks	Java の compileOptions と Kotlin の jvmTarget を同じバージョン（21）にします。
R.layout.bridge_layout_main で cannot find symbol が発生する	capacitor_bridge_layout_main を使用します。
SPM の解決で Capacitor 7 が選択される	capacitor-swift-pm に from: "8.0.0" を設定します。