Come aggiornare un plugin Capacitor a Capacitor 8

Per aggiornare un plugin Capacitor a Capacitor 8, esegui bunx @capacitor/plugin-migration-v7-to-v8@latest dalla root del plugin, poi rivedi il diff: le dipendenze Capacitor passano a 8.x, Android punta a SDK 36 con minSdk 24, AGP 8.13 e Gradle 8.14.3, Kotlin passa a 2.2.20 con compilerOptions, e iOS passa a un deployment target 15.0 con capacitor-swift-pm 8. Per finire, fai il build dell'app di esempio su entrambe le piattaforme e pubblica una nuova major version.

Questa guida è per i maintainer dei plugin. I team delle app dovrebbero seguire Come aggiornare la tua app Capacitor a Capacitor 8.

Cosa cambia per gli autori di plugin

Strumenti di piattaforma necessari in locale e in CI: Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) o versioni successive, e un JDK 21.

Opzione 1: esegui lo strumento di migrazione ufficiale

Dalla root del plugin, con un working tree git pulito:

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

Lo strumento:

• Aggiorna le dipendenze Capacitor e imposta la versione del pacchetto a 8.0.0.
• Aggiorna i dev tool usati dal template ufficiale: @capacitor/docgen, Rollup, TypeScript, @types/node, e Prettier (da v2 a v3 se usi @ionic/prettier-config, e anche prettier-plugin-java).
• Elimina node_modules/@capacitor e package-lock.json, poi esegue npm install. Se usi Bun, quel passaggio fallisce con un warning. Esegui bun install tu stesso dopo e fai il commit bun.lock.
• Rigenera il Gradle wrapper con ./gradlew wrapper --gradle-version 8.14.3.
• Riscrive build.gradle: livelli SDK, versioni AndroidX, AGP, versione Kotlin, compatibilità Java 21 e kotlinOptions a compilerOptions.
• Porta il deployment target del podspec da 14.0 a 15.0 e Package.swift imposta .iOS(.v15) e from: "8.0.0" per capacitor-swift-pm.

Se manca una stringa attesa, logga Unable to find "..." in <file>. Try updating it manually. Ognuna di queste righe è un passaggio manuale per te. I plugin con logica Gradle personalizzata, cartelle non standard o file rinominati ne producono la maggior parte.

Se Prettier è passato dalla v2 alla v3, esegui i tuoi script di format e lint dopo la migrazione. Il diff di formattazione può essere ampio, quindi fai il commit separatamente dalle modifiche funzionali.

Opzione 2: upgrade manuale

Usa questa opzione se lo strumento non riesce ad analizzare i file o se vuoi rivedere ogni modifica. I passaggi seguono la guida ufficiale all'upgrade dei plugin.

1. Dipendenze

{
  "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. Livelli SDK Android e sintassi 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
    }
}

Mantieni il project.hasProperty(...) ? rootProject.ext... : default pattern. Consente all'app host di variables.gradle controllare i valori, evitando così errori del tipo “compilato contro la versione 36” nelle app.

Il = La sintassi si applica solo alle proprietà. Le chiamate a metodi come mavenCentral() restano invariate, e maven { url = "..." } richiede =.

3. Default AndroidX

Aggiorna solo le librerie che il tuo plugin usa effettivamente. I default di Capacitor 8 sono:

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'
}

Altri dalla lista ufficiale: 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 e Gradle wrapper

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

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

Se il tuo plugin usa Firebase o altri Google Services, imposta com.google.gms:google-services a 4.4.4.

5. Java 21 e Kotlin 2.2

Si consiglia Java 21 per AGP 8.13 e SDK 36. Java 17 funziona ancora per il plugin stesso.

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

Per i plugin Kotlin, aggiorna la versione di default e sposta jvmTarget fuori da kotlinOptions. Kotlin 2.2 trasforma il vecchio blocco in un errore:

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
    }
}

Mantieni jvmTarget e targetCompatibility sulla stessa versione di Java, altrimenti Gradle si ferma con un errore “Inconsistent JVM-target compatibility”. Se applichi ancora kotlin-android-extensions, rimuovilo. Usa kotlin-parcelize per @Parcelize e view binding per l'accesso a viste sintetiche.

6. Target di deployment 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")
],

Usa from:, non branch: oppure exact:. L'app generata CapApp-SPM pin dei package capacitor-swift-pm alla versione esatta di @capacitor/ios l'app installata, e un intervallo consente a SPM di risolvere il plugin in base ad essa.

I plugin con il vecchio layout di progetto Xcode richiedono anche l'innalzamento del deployment target nel progetto Impostazioni di Build e in ios/Podfile (platform :ios, '15.0').

Se il tuo plugin non ha Package.swift ancora, fallo subito dopo. Le app create con Capacitor 8 usano SPM di default e salteranno il tuo plugin con un avviso di “non compatibile con SPM”. Segui Come migrare un plugin Capacitor a Swift Package Manager.

Opzione 3: lascia fare a un agente

L'open Competenze Capgo includono capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades per i salti tra più versioni, e capacitor-plugin-spm-support. Installa con bunx skills add Cap-go/capgo-skills e chiedi al tuo agente di aggiornare il plugin. La skill esegue lo strumento ufficiale e poi gestisce i passaggi che lo strumento segnala come saltati. Esamina la diff proprio come faresti con la PR di un collega.

Quale approccio scegliere

Inizia con lo strumento in quasi tutti i casi. Il log ti dice esattamente cosa manca.

Verifica prima di pubblicare

1. bun install && bun run build (o il tuo verify script).
2. Android: cd android && ./gradlew clean build test. Build con JDK 21.
3. iOS con CocoaPods: cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (i plugin con layout nuovo usano xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
4. iOS con SPM: swift package resolve, poi builda la scheme.
5. Installa il plugin in una nuova app Capacitor 8 (bunx cap add ios che usa SPM di default) e in un'app CocoaPods. Chiama ogni metodo pubblico su un dispositivo reale.
6. Esegui bunx cap doctor nell'app di test.

Rilascio

• Passa a una nuova major (lo strumento usa 8.0.0). Aumentare minSdk e il floor iOS è una breaking change per i consumatori.
• Scrivi una breve BREAKING.md o voce di changelog: nuovo intervallo peer, minSdk 24, iOS 15, Java 21 per le build, eventuali modifiche al comportamento di API.
• Mantieni una 7.x branch se pubblichi ancora fix per gli utenti di Capacitor 7, e pubblica quelle versioni con un dist-tag come latest-7.
• Aggiorna la sezione di installazione nel README e la tabella di compatibilità.

Capgo mantiene un ampio set di plugin su questo ciclo, con ogni @capgo/* major che segue un major di Capacitor. Puoi sfogliarli nel directory dei plugin.

Risoluzione problemi

invalid source release: 21. Gradle sta girando su JDK 17 o versioni precedenti. Usa il JDK 21 incluso in Android Studio Otter e imposta JAVA_HOME in CI.

Unsupported class file major version 65. Il problema opposto: usi JDK 21 con un vecchio Gradle wrapper che non riesce a leggere i file di classe Java 21. Rigenera il wrapper alla versione 8.14.3.

Namespace not specified. AGP 8+ richiede namespace = "..." in the plugin’s android blocco. I vecchi plugin avevano solo un package attributo in AndroidManifest.xml. Spostalo in Gradle e rimuovi package dal manifest.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). Il tuo Kotlin jvmTarget non corrisponde targetCompatibility. Imposta entrambi a 21 o entrambi a 17.

Errori che menzionano proguard-android.txt con AGP 9. Alcune app usano già AGP 9. Passa a proguard-android-optimize.txt così il tuo plugin si compila anche in quelle app. I dettagli sono in risolvere gli errori di build del plugin Capacitor con AGP 9.

SPM: product 'Capacitor' required by package ... not found. Il tuo Package.swift la riga di dipendenza contiene un refuso o usa una versione inesistente. Usa from: "8.0.0" contro https://github.com/ionic-team/capacitor-swift-pm.git.

Avvisi per dimensioni di pagina di 16 KB in Play Console. Se il tuo plugin include librerie native .so librerie, ricompila con allineamento a 16 KB. Vedi Android 16 KB page size e plugin Capacitor.

Una volta aggiornato il plugin alla versione 8, il passo successivo è prepararsi alla 9. Prepararsi a Capacitor 9 elenca le modifiche che i team di plugin possono apportare ora senza rompere gli utenti di Capacitor 8.