Cómo actualizar un plugin Capacitor a Capacitor 8

Para actualizar un plugin de Capacitor a Capacitor 8, ejecute bunx @capacitor/plugin-migration-v7-to-v8@latest desde la raíz del plugin, luego revise la diferencia: las dependencias de Capacitor se mueven a 8.x, los objetivos de Android de SDK 36 con minSdk 24, AGP 8.13 y Gradle 8.14.3, Kotlin se va a 2.2.20 con compilerOptionsy iOS se mueve a un objetivo de despliegue de 15.0 con capacitor-swift-pm 8. Finalice construyendo la aplicación de ejemplo en ambas plataformas y publicando una nueva versión mayor.

Esta guía es para los mantenedores de plugins. Los equipos de aplicaciones deben seguir Cómo actualizar su aplicación de Capacitor a Capacitor 8.

¿Qué cambia para los autores de plugins

Las herramientas de plataforma que necesitas localmente y en CI: Node.js 22+, Xcode 26+, Android Studio Otter (2025.2.1) o posterior, y un JDK 21.

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

Desde la raíz del plugin, en un árbol de Git limpio:

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

La herramienta:

• Actualiza las dependencias Capacitor y establece tu versión de paquete en 8.0.0.
• Actualiza las herramientas de desarrollo que utiliza el modelo oficial: @capacitor/docgen, Rollup, TypeScript @types/node, y Prettier (desde v2 a v3 si utilizas @ionic/prettier-config, más prettier-plugin-java).
• Elimina node_modules/@capacitor y package-lock.json, luego ejecuta npm install. Si utiliza Bun, ese paso falla con una advertencia. Ejecute bun install commítate después y hágalo bun.lock.
• Regenera el wrapper de Gradle con ./gradlew wrapper --gradle-version 8.14.3.
• Redescribe build.gradle: SDK niveles, versiones de AndroidX, AGP, versión de Kotlin, compatibilidad con Java 21 y kotlinOptions para compilerOptions.
• Aumenta el objetivo de despliegue de podspec de 14.0 a 15.0, y en Package.swift establece .iOS(.v15) y from: "8.0.0" para capacitor-swift-pm.

When a string is missing, it logs Unable to find "..." in <file>. Try updating it manuallyEvery one of those lines is a manual step for you. Plugins with custom Gradle logic, non-standard folders or renamed files produce the most of them.

If Prettier moved from v2 to v3, run your format and lint scripts after the migration. The formatting diff can be large, so commit it separately from the functional changes.

Option 2: upgrade manualmente

Utiliza esto cuando el herramienta no pueda analizar tus archivos, o cuando quieras revisar cada cambio. Los pasos siguen el Guía oficial de actualización del plugin.

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

Conserva el project.hasProperty(...) ? rootProject.ext... : default patrón. Le permite a la aplicación de host. variables.gradle controlar los valores, lo que evita la clase de errores "compilar contra la versión 36" en aplicaciones.

El = La sintaxis se aplica solo a propiedades. Llamadas a métodos como mavenCentral() se mantienen sin cambios, y maven { url = "..." } necesita el =.

3. Los valores predeterminados de AndroidX

Solo actualiza las bibliotecas que tu plugin utiliza realmente. Las Capacitor 8 por defecto 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 wrapper de 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 tu plugin utiliza Firebase o otros servicios de Google, establece 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 en sí.

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

Para plugins de Kotlin, actualiza la versión predeterminada y mueve jvmTarget fuera de kotlinOptions. Kotlin 2.2 hace que el bloque antiguo sea 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 Si aplicas la actualización en la misma versión de Java, o Gradle se detiene con un error de “incompatibilidad de compatibilidad JVM”. kotlin-android-extensionsen la misma versión de Java, o Gradle se detiene con un error de compatibilidad de JVM-inconsistente "Inconsistent JVM-target compatibility". Si aún aplicas kotlin-parcelize for @Parcelize y acceso a vistas sintéticas mediante vinculación de vistas.

y el acceso de vista sintética.

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")
],

Podspec: from:Utiliza branch: o exact:La aplicación generada CapApp-SPM package pins capacitor-swift-pm hasta la versión exacta de @capacitor/ios la aplicación instalada, y un rango permite que SPM resuelva su plugin en contra de ella.

Plugins con el antiguo layout de proyecto de Xcode también necesitan que el objetivo de despliegue se eleve en el proyecto Configuración de compilación o ios/Podfile (platform :ios, '15.0').

Si su plugin no Package.swift yet, do that next. Apps created with Capacitor 8 default to SPM and will skip your plugin with a “not compatible with SPM” warning. Follow Cómo Migrar un Capacitor a Gestor de Paquetes de Swift.

Opción 3: deje que un agente se encargue de ello

El abierto Capgo Habilidades incluyen capacitor-plugin-upgrade-v7-to-v8, capacitor-plugin-upgrades para saltos de varias versiones, y capacitor-plugin-spm-supportInstale con bunx skills add Cap-go/capgo-skills y pida a su agente que actualice el complemento. La habilidad ejecuta la herramienta oficial, luego maneja los pasos que la herramienta registra como omitidos. Revisa la diferencia de la misma manera que revisarías un PR de un compañero de equipo.

¿Cuál enfoque utilizar

Comience con la herramienta en casi todos los casos. Su registro le dice exactamente qué queda.

Verifique antes de publicar

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

Release

• Bump to a new major (the tool uses 8.0.0. Eleva minSdk y el piso de iOS es un cambio de ruptura para los consumidores.
• Redacta un breve BREAKING.md o entrada de cambios: nueva gama de pares, minSdk 24, iOS 15, Java 21 para compilaciones, cualquier API cambios de comportamiento.
• Mantén un 7.x rama si todavía envías correcciones para Capacitor 7 usuarios, y publica esas bajo una etiqueta de distribución como latest-7.
• Actualiza la sección de instalación del README y la tabla de compatibilidad.

Capgo mantiene un gran conjunto de plugins en este ciclo, con cada @capgo/* major que sigue a un Capacitor major. Puedes explorarlos en el directorios de plugins.

Solución de problemas

invalid source release: 21. Gradle está ejecutándose en JDK 17 o versiones anteriores. Utilice el JDK 21 incluido con Android Studio Otter y configure JAVA_HOME en CI.

Unsupported class file major version 65. El problema opuesto: ejecuta JDK 21 con un wrapper de Gradle antiguo que no puede leer archivos de clase Java 21. Regenera el wrapper en 8.14.3.

Namespace not specified. AGP 8+ requiere namespace = "..." en el plugin android viejo. Los plugins más antiguos solo tenían un package . Muevelo a Gradle y elimina AndroidManifest.xmlde la declaración de manifiesto. package desde el manifiesto.

'compileDebugJavaWithJavac' task (current target is 21) and 'compileDebugKotlin' task (current target is 17). no coincide con jvmTarget no coincide targetCompatibilityEstablezca ambos a 21 o ambos a 17.

Errores que mencionan proguard-android.txt con AGP 9. Algunas aplicaciones ya ejecutan AGP 9. Cambie a proguard-android-optimize.txt Así tu plugin se compila también en esas aplicaciones. Los detalles están en solucione errores de compilación del plugin Capacitor con AGP 9.

SPM: product 'Capacitor' required by package ... not found. Su Package.swift línea de dependencias tiene un error de ortografía o utiliza una versión que no existe. Utilice from: "8.0.0" contra https://github.com/ionic-team/capacitor-swift-pm.git.

16 KB de tamaño de página advertencias en el Console de Play. Si su plugin envía nativos .so tamaño de página de 16 KB de Android y Android 16 KB de tamaño de página y plugins Capacitor.

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