Cómo actualizar un plugin de Capacitor a Capacitor 8

Para actualizar un plugin de Capacitor a Capacitor 8, ejecuta bunx @capacitor/plugin-migration-v7-to-v8@latest desde la raíz del plugin y luego revisa el diff: las dependencias de Capacitor pasan a 8.x, Android apunta a SDK 36 con minSdk 24, AGP 8.13 y Gradle 8.14.3, Kotlin sube a 2.2.20 con compilerOptions, y iOS pasa a un deployment target de 15.0 con capacitor-swift-pm 8. Termina compilando la app de ejemplo en ambas plataformas y publicando una nueva versión mayor.

Esta guía es para mantenedores de plugins. Los equipos de apps deben seguir Cómo actualizar tu app de Capacitor a Capacitor 8.

Cambios para autores de plugins

Herramientas de plataforma que necesitas en local y en CI: Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) o superior, y un JDK 21.

Opción 1: ejecutar la herramienta de migración oficial

Desde la raíz del plugin, con un árbol de git limpio:

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

La herramienta:

• Actualiza las dependencias de Capacitor y fija la versión de tu paquete en 8.0.0.
• Actualiza las herramientas de desarrollo que usa la plantilla oficial: @capacitor/docgen, Rollup, TypeScript, @types/node, y Prettier (de v2 a v3 si usas @ionic/prettier-config, además prettier-plugin-java).
• Elimina node_modules/@capacitor y package-lock.json, luego ejecuta npm install. Si usas Bun, ese paso falla con una advertencia. Ejecuta bun install tú mismo después y haz commit bun.lock.
• Regenera el Gradle wrapper con ./gradlew wrapper --gradle-version 8.14.3.
• Reescribe build.gradle: SDK niveles, versiones de AndroidX, AGP, versión de Kotlin, compatibilidad con Java 21 y kotlinOptions a compilerOptions.
• Sube el deployment target del podspec de 14.0 a 15.0, y en Package.swift establece .iOS(.v15) y from: "8.0.0" para capacitor-swift-pm.

Cuando falta una cadena que espera, registra Unable to find "..." in <file>. Try updating it manually. Cada una de esas líneas es un paso manual para ti. Los plugins con lógica Gradle personalizada, carpetas no estándar o archivos renombrados generan la mayoría de ellas.

Si Prettier pasó de v2 a v3, ejecuta tus scripts de formato y lint después de la migración. El diff de formato puede ser grande, así que commítalo por separado de los cambios funcionales.

Opción 2: actualizar manualmente

Usa esto cuando la herramienta no pueda analizar tus archivos o cuando quieras revisar cada cambio. Los pasos siguen la guía oficial de actualización de plugins.

1. Dependencias

{
  "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. Niveles de SDK en Android y sintaxis de 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
    }
}

Mantén el project.hasProperty(...) ? rootProject.ext... : default patrón. Permite que la app host variables.gradle controle los valores, lo que evita el tipo de errores “compile against version 36” en las apps.

El = La sintaxis aplica solo a propiedades. Las llamadas a métodos como mavenCentral() se mantienen igual, y maven { url = "..." } requiere el =.

3. Valores por defecto de AndroidX

Actualiza solo las librerías que tu plugin use realmente. Los valores predeterminados de Capacitor 8 son:

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

Otros de la lista oficial: 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 y el 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

Si tu plugin usa Firebase u otros Google Services, configura com.google.gms:google-services a 4.4.4.

5. Java 21 y Kotlin 2.2

Se recomienda Java 21 para AGP 8.13 y SDK 36. Java 17 sigue funcionando para el plugin.

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

Para plugins de Kotlin, actualiza la versión por defecto y mueve jvmTarget fuera de kotlinOptions. Kotlin 2.2 convierte el bloque antiguo en un error:

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

Mantén jvmTarget y targetCompatibility en la misma versión de Java, o Gradle lanzará un error de “Inconsistent JVM-target compatibility”. Si aún aplicas kotlin-android-extensions, elimínalo. Usa kotlin-parcelize para @Parcelize y view binding para acceder a vistas sintéticas.

6. Deployment target de 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:, no branch: o exact:. El paquete generado de la app CapApp-SPM versiones fijas capacitor-swift-pm a la versión exacta de @capacitor/ios la app instalada; un rango permite que SPM resuelva tu plugin contra ella.

Los plugins con el layout antiguo de Xcode también necesitan subir el deployment target en los Build Settings del proyecto y en ios/Podfile (platform :ios, '15.0').

Si tu plugin no tiene Package.swift aún no, hazlo a continuación. Las apps creadas con Capacitor 8 usan SPM por defecto y omitirán tu plugin con un aviso de “no compatible con SPM”. Sigue Cómo migrar un plugin de Capacitor a Swift Package Manager.

Opción 3: deja que un agente lo haga

El open Capgo Skills abiertas incluyen capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades para saltos de varias versiones, y capacitor-plugin-spm-support. Instala con bunx skills add Cap-go/capgo-skills y pide a tu agente que actualice el plugin. La skill ejecuta la herramienta oficial y luego gestiona los pasos que la herramienta registra como omitidos. Revisa el diff igual que revisarías el PR de un compañero.

Qué enfoque usar

Empieza con la herramienta en casi todos los casos. Su log te dice exactamente qué falta.

Verifica antes de publicar

1. bun install && bun run build (o tu verify script).
2. Android: cd android && ./gradlew clean build test. Haz el build con JDK 21.
3. iOS con CocoaPods: cd ios && pod install && xcodebuild -workspace Plugin.xcworkspace -scheme Plugin -destination generic/platform=iOS (los nuevos plugins de layout usan xcodebuild -scheme <YourPackageName> -destination generic/platform=iOS).
4. iOS con SPM: swift package resolve, luego haz el build del scheme.
5. Instala el plugin en una app Capacitor 8 limpia (bunx cap add ios te da SPM por defecto) y en una app de CocoaPods. Llama a cada método público en un dispositivo real.
6. Ejecuta bunx cap doctor en la app de prueba.

Lanzamiento

• Bump to a new major (the tool uses 8.0.0). Subir minSdk y el mínimo de iOS es un cambio que rompe la compatibilidad para los consumidores.
• Escribe una breve BREAKING.md o entrada en el changelog: nuevo rango de peer, minSdk 24, iOS 15, Java 21 para builds, cambios de comportamiento en API.
• Mantén una 7.x rama si todavía publicas correcciones para los usuarios de Capacitor 7, y publícalas bajo un dist-tag como latest-7.
• Actualiza la sección de instalación del README y la tabla de compatibilidad.

Capgo mantiene un amplio conjunto de plugins en este ciclo, con cada @capgo/* una major que sigue a una major de Capacitor. Puedes consultarlas en el directorio de plugins.

Solución de problemas

invalid source release: 21. Gradle se está ejecutando con JDK 17 o inferior. Usa el JDK 21 incluido en Android Studio Otter y configúralo JAVA_HOME en CI.

Unsupported class file major version 65. El problema inverso: usas JDK 21 con un Gradle wrapper antiguo que no puede leer archivos de clase de Java 21. Regenera el wrapper a la versión 8.14.3.

Namespace not specified. AGP 8+ requiere namespace = "..." en el plugin android bloque del plugin. Los plugins antiguos solo tenían un package atributo en AndroidManifest.xml. Muévelo a Gradle y elimina package del manifest.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). Tu Kotlin jvmTarget no coincide targetCompatibility. Pon ambas en 21 o ambas en 17.

Errores que mencionan proguard-android.txt con AGP 9. Algunas apps ya usan AGP 9. Cambia a proguard-android-optimize.txt para que tu plugin también compile en ellas. Detalles en arreglar errores de build del plugin Capacitor con AGP 9.

SPM: product 'Capacitor' required by package ... not found. Tu Package.swift la línea de dependencia tiene un typo o usa una versión que no existe. Usa from: "8.0.0" contra https://github.com/ionic-team/capacitor-swift-pm.git.

Advertencias de tamaño de página de 16 KB en Play Console. Si tu plugin incluye bibliotecas nativas .so , reconstrúyelas con alineación de 16 KB. Consulta Tamaño de página de 16 KB en Android y plugins Capacitor.

Una vez que el plugin esté en la 8, el siguiente paso es prepararse para la 9. Preparándote para Capacitor 9 enumera los cambios que los equipos de plugins pueden hacer ahora sin romper a los usuarios de Capacitor 8.