Comment mettre à jour un plugin Capacitor vers Capacitor 8

Pour mettre à jour un plugin Capacitor vers Capacitor 8, lancez bunx @capacitor/plugin-migration-v7-to-v8@latest depuis la racine du plugin, puis examinez le diff : les dépendances Capacitor passent en 8.x, Android cible SDK 36 avec minSdk 24, AGP 8.13 et Gradle 8.14.3, Kotlin passe en 2.2.20 avec compilerOptions, et iOS passe à une cible de déploiement 15.0 avec capacitor-swift-pm 8. Terminez en compilant l'application d'exemple sur les deux plateformes et en publiant une nouvelle version majeure.

Ce guide s'adresse aux mainteneurs de plugins. Les équipes applicatives doivent suivre Comment mettre à jour votre application Capacitor vers Capacitor 8.

Ce qui change pour les auteurs de plugins

Les outils de plateforme nécessaires en local et en CI : Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) ou plus récent, et un JDK 21.

Option 1 : utiliser l'outil de migration officiel

Depuis la racine du plugin, sur un arbre git propre :

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

L'outil :

• Met à jour les dépendances Capacitor et définit la version de votre package sur 8.0.0.
• Met à jour les outils de dev utilisés par le template officiel : @capacitor/docgen, Rollup, TypeScript, @types/node, et Prettier (de v2 à v3 si vous utilisez @ionic/prettier-config, ainsi que prettier-plugin-java).
• Supprime node_modules/@capacitor et package-lock.json, puis exécute npm install. Si vous utilisez Bun, cette étape échoue avec un avertissement. Lancez bun install vous-même ensuite et commitez bun.lock.
• Régénère le wrapper Gradle avec ./gradlew wrapper --gradle-version 8.14.3.
• Réécrit build.gradle: SDK niveaux, versions AndroidX, AGP, version Kotlin, compatibilité Java 21, et kotlinOptions vers compilerOptions.
• Relève la cible de déploiement du podspec de 14.0 à 15.0, et dans Package.swift définit .iOS(.v15) et from: "8.0.0" pour capacitor-swift-pm.

Lorsqu’une chaîne attendue est manquante, il logue Unable to find "..." in <file>. Try updating it manually. Chacune de ces lignes est une étape manuelle pour vous. Les plugins avec une logique Gradle personnalisée, des dossiers non standard ou des fichiers renommés en génèrent le plus.

Si Prettier est passé de la v2 à la v3, exécutez vos scripts de formatage et de lint après la migration. Le diff de formatage peut être important, donc commitez-le séparément des modifications fonctionnelles.

Option 2 : mettre à jour manuellement

Utilisez cette méthode lorsque l’outil ne parvient pas à analyser vos fichiers, ou lorsque vous souhaitez examiner chaque modification. Les étapes suivent le guide officiel de mise à niveau du plugin.

1. Dépendances

{
  "devDependencies": {
    "@capacitor/android": "^8.0.0",
    "@capacitor/cli": "^8.0.0",
    "@capacitor/core": "^8.0.0",
    "@capacitor/ios": "^8.0.0"
  },
  "peerDependencies": {
    "@capacitor/core": ">=8.0.0"
  }
}

2. Niveaux d'SDK Android et syntaxe Gradle

android {
    namespace = "com.example.plugin"
    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
    defaultConfig {
        minSdkVersion = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
        targetSdkVersion = project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
    }
    lintOptions {
        abortOnError = false
    }
}

Conservez le project.hasProperty(...) ? rootProject.ext... : default pattern. Il permet à l’app hôte de variables.gradle contrôler les valeurs, ce qui évite les erreurs de type « compile against version 36 » dans les apps.

Le = syntaxe s’applique uniquement aux propriétés. Les appels de méthode comme mavenCentral() restent inchangés, et maven { url = "..." } nécessite le =.

3. Valeurs par défaut AndroidX

Only bump libraries your plugin actually uses. The Capacitor 8 defaults are:

ext {
    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
    androidxCoreVersion = project.hasProperty('androidxCoreVersion') ? rootProject.ext.androidxCoreVersion : '1.17.0'
    androidxActivityVersion = project.hasProperty('androidxActivityVersion') ? rootProject.ext.androidxActivityVersion : '1.11.0'
    androidxWebkitVersion = project.hasProperty('androidxWebkitVersion') ? rootProject.ext.androidxWebkitVersion : '1.14.0'
}

Autres éléments de la liste officielle : androidxCoordinatorLayoutVersion 1.3.0, androidxFragmentVersion 1.8.9, firebaseMessagingVersion 25.0.1, androidxBrowserVersion 1.9.0, androidxMaterialVersion 1.13.0, androidxExifInterfaceVersion 1.4.1, coreSplashScreenVersion 1.2.0.

4. AGP et le wrapper Gradle

buildscript {
    dependencies {
        classpath 'com.android.tools.build:gradle:8.13.0'
    }
}

cd android
./gradlew wrapper --distribution-type all --gradle-version 8.14.3

Si votre plugin utilise Firebase ou d’autres Google Services, définissez com.google.gms:google-services vers 4.4.4.

5. Java 21 et Kotlin 2.2

Java 21 est recommandé pour AGP 8.13 et SDK 36. Java 17 fonctionne toujours pour le plugin lui-même.

compileOptions {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}

Pour les plugins Kotlin, mettez à jour la version par défaut et déplacez jvmTarget hors de kotlinOptions. Kotlin 2.2 rend l’ancien bloc une erreur :

import org.jetbrains.kotlin.gradle.dsl.JvmTarget

buildscript {
    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
}

android {
    // remove: kotlinOptions { jvmTarget = '17' }
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.JVM_21
    }
}

Conservez jvmTarget et targetCompatibility sur la même version de Java, sinon Gradle s’arrête avec une erreur « Inconsistent JVM-target compatibility ». Si vous appliquez encore kotlin-android-extensions, supprimez-le. Utilisez kotlin-parcelize pour @Parcelize et le view binding pour accéder aux vues synthétiques.

6. Cible de déploiement iOS

Podspec :

s.ios.deployment_target = '15.0'

Package.swift:

platforms: [.iOS(.v15)],
dependencies: [
    .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
],

Utiliser from:, et non branch: ou exact:. Le package généré de l'app CapApp-SPM se verrouille capacitor-swift-pm sur la version exacte de @capacitor/ios l'app installée, et une plage permet à SPM de résoudre votre plugin par rapport à celle-ci.

Les plugins avec l'ancienne structure de projet Xcode doivent aussi avoir la cible de déploiement relevée dans le Paramètres de build et dans ios/Podfile (platform :ios, '15.0').

Si votre plugin n'a pas de Package.swift pour l’instant, faites-l’ensuite. Les applications créées avec Capacitor 8 utilisent SPM par défaut et ignoreront votre plugin avec un avertissement « non compatible avec SPM ». Suivez Comment migrer un plugin Capacitor vers Swift Package Manager.

Option 3 : laisser un agent s'en charger

L’open skills Capgo open source incluent capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades pour les sauts de plusieurs versions, et capacitor-plugin-spm-support. Installez avec bunx skills add Cap-go/capgo-skills et demandez à votre agent de mettre à niveau le plugin. La skill exécute l’outil officiel, puis gère les étapes que l’outil a ignorées. Examinez le diff comme vous le feriez pour la PR d’un collègue.

Quelle approche choisir

Commencez par l’outil dans presque tous les cas. Ses logs indiquent exactement ce qu’il reste à faire.

Vérifiez avant de publier

1. bun install && bun run build (ou votre verify script).
2. Android : cd android && ./gradlew clean build test. Compilez avec JDK 21.
3. iOS avec CocoaPods : cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (les plugins avec la nouvelle structure utilisent xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
4. iOS avec SPM : swift package resolve, puis compilez le schéma.
5. Installez le plugin dans une nouvelle application Capacitor 8 (bunx cap add ios utilise SPM par défaut) et dans une application CocoaPods. Appelez chaque méthode publique sur un appareil réel.
6. Exécutez bunx cap doctor dans l'application de test.

Release

• Bump to a new major (the tool uses 8.0.0). Augmenter minSdk et la version minimale iOS est une modification cassante pour les utilisateurs.
• Rédigez une courte BREAKING.md ou entrée de changelog : nouvelle plage de peer, minSdk 24, iOS 15, Java 21 pour les builds, changements de comportement de API.
• Conservez une 7.x branche si vous publiez encore des correctifs pour les utilisateurs de Capacitor 7, et publiez-les sous un dist-tag tel que latest-7.
• Mettez à jour la section d’installation du README et le tableau de compatibilité.

Capgo maintient un grand nombre de plugins sur ce cycle, avec chaque @capgo/* majeure qui suit une majeure de Capacitor. Vous pouvez les parcourir dans le répertoire des plugins.

Troubleshooting

invalid source release: 21. Gradle tourne sur JDK 17 ou une version antérieure. Utilisez le JDK 21 fourni avec Android Studio Otter et définissez JAVA_HOME dans votre CI.

Unsupported class file major version 65. Le problème inverse : vous utilisez JDK 21 avec un ancien wrapper Gradle qui ne sait pas lire les fichiers de classe Java 21. Régénérez le wrapper en 8.14.3.

Namespace not specified. AGP 8+ nécessite namespace = "..." dans le bloc android du plugin. Les anciens plugins n'avaient qu'un package attribut dans AndroidManifest.xml. Déplacez-le vers Gradle et supprimez package du manifeste.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). Votre Kotlin jvmTarget ne correspond pas targetCompatibility. Définissez les deux à 21 ou les deux à 17.

Les erreurs mentionnant proguard-android.txt avec AGP 9. Certaines applications utilisent déjà AGP 9. Passez à proguard-android-optimize.txt so your plugin builds in those apps too. Details are in corriger les erreurs de build du plugin Capacitor avec AGP 9.

SPM : product 'Capacitor' required by package ... not found. Votre Package.swift la ligne de dépendance contient une faute de frappe ou utilise une version inexistante. Utilisez from: "8.0.0" contre https://github.com/ionic-team/capacitor-swift-pm.git.

Avertissements de taille de page 16 Ko dans Play Console. Si votre plugin inclut des bibliothèques .so natives, recompilez-les avec un alignement de 16 Ko. Voir Taille de page Android 16 Ko et plugins Capacitor.

Une fois le plugin en version 8, l'étape suivante consiste à préparer la version 9. Préparation à Capacitor 9 lists the changes plugin teams can make now without breaking Capacitor 8 users.