Preparing for Capacitor 9: What App and Plugin Teams Can Do Now

Capacitor 9 está disponible en el next No necesitas actualizar tu aplicación el día que se lanza la versión alpha, pero debes tener en cuenta que se realizarán actualizaciones en el futuro. official Capacitor 9 update guide y Guía de actualización de plugins ya identifiquen herramientas de cadena y API eliminaciones que merecen abordarse temprano.

Este artículo es un Preparación lista de tareas: trabajo que puedes hacer en Capacitor 8 (o en una rama) para asegurarte de que bunx cap migrate La transición es aburrida en lugar de dolorosa. Cuando estés listo para realizar el cambio, sigue las guías de Ionic línea por línea.

Plataformas de herramientas y suelos de aplicaciones

Planifica tus CI, máquinas locales y pipelines de almacenamiento alrededor de estos mínimos:

Si aún estás en Capacitor 8.4 o anterior para iOS, también necesitarás Ciclo de vida de la escena de IU Trabaja desde la actualización Capacitor 8.5 antes de Cap 9 — Xcode 27 lo espera. Las aplicaciones ya en 8.5 pueden saltarse ese paso adicional.

On iOS, Swift 6 (con Xcode 27) rechaza @UIApplicationMain; cuando actualices, reemplaza con @main in AppDelegate.swift como se describe en la guía oficial.

Cordova at app sync time (not a plugin prep step)

En Capacitor 9, la capa de compatibilidad de Cordova está solamente conectada a tu aplicación cuando cap sync detecta un plugin de Cordova instalado. Android elimina los módulos de Gradle adicionales cuando no están presentes; iOS deja de agregar CapacitorCordova a la Podfile o Package.swift cuando no estén presentes.

Eso es un app-level behavior change after you upgrade. While you are still on Cap 8, you do not need to rip Cordova out of your template preemptively. Do audit whether any nativo personalizado code (yours or a forked plugin) imports Cordova symbols without an actual Cordova plugin in the project — those references will fail once optional Cordova wiring applies.

Android: gradle.properties y AGP 9 por defecto

El asistente de actualización de AGP escribe explícitamente gradle.properties flags so builds keep AGP 8 behavior. Capacitor 9 apps should que en lugar de llevarlos adelante: la mayoría están descontinuados con anticipación a AGP 10, y algunos rompen los builds de Cap 9 (por ejemplo) android.builtInKotlin=false desactiva el soporte de Kotlin que AGP 9 incluye, y android.sdk.defaultTargetSdkToCompileSdkIfUnset=false detiene a AGP de inferir targetSdkVersion).

Cuando migres, también espera a:

• Aumentar variables.gradle las mínimas (compilar/objetivo SDK 37, minSdkVersion 26, versiones actualizadas de AndroidX — consulte la documentación oficial).
• Eliminar explícitos targetSdkVersion del aplicativo build.gradle para que AGP 9 pueda inferirlo de compileSdkVersion.
• Declarar variables.gradle símbolos en la parte superior de app/build.gradle (Gradle 9.6 deprecia la búsqueda implícita desde el proyecto raíz).
• Swap nombres de archivo de ProGuard por defecto, migra core-ktx to androidx.core:core 1.19.0+, dejar de usar el plugin de Gradle Kotlin de forma independiente y eliminar jcenter().

Puedes leer los bloques de diferencias en el Actualizando a 9.0 Sección de Android y aplicar las mismas limpiezas en una rama antes de actualizar las versiones Capacitor.

CLI: cap run --url

Capacitor 9 combina las banderas de host/porto/https de live-reload en una sola --url __CAPGO_KEEP_0__ 9 combina las banderas de host/porto/https de la carga en vivo en un solo

bunx cap run android -l --host 192.168.1.181 --port 5173

pasar la URL que imprime tu servidor de desarrollo:

bunx cap run android --url http://192.168.1.181:5173/

Actualice los scripts y fragmentos de README ahora para que la memoria muscular no se oponga al nuevo CLI después de la actualización.

Plugins oficiales: trampas de notificaciones push y splash

Dos cambios de usuario que se muestran con frecuencia en aplicaciones de producción:

Notificaciones push (iOS): El obsoleto alert Opción de presentación se ha eliminado. Utilice banner y/o list Pantalla de bienvenida (Android):

El valor por defecto de ha cambiado de launchFadeOutDuration Cambios desde 200 ms a 0Si confiaste en la desaparición gradual de los primeros artefactos de pintado, establece launchFadeOutDuration: 200 de manera explícita en capacitor.config until you adjust your startup UI.

Escanea las secciones de plugins en el guía de actualización 9.0 para actualizaciones de AndroidX y servicios de Google Play relacionadas con plugins oficiales que utilizas.

Los mantenedores de plugins: prepárense en Cap 8 sin romper Cap 8

Si envías Capacitor plugins consumidos en Capacitor 8 y Quieres un code listo para Capacitor 9, enfócate en la eliminación de API descontinuada,no en cambios de empaque solo para Cap-9.

Seguro de hacer mientras Cap 8 sigue siendo compatible:

• Sustituir @NativePlugin por @CapacitorPlugin y migrar las APIs de permisos / resultados de actividad a @PermissionCallback / @ActivityCallback patrones (consulte la Guía del plugin 9.0 table).
• ). PluginCall.hasOption, Plugin.getConfigValueEliminar CapConfig , constructores y getters antiguos, PluginCall.save() / isSaved(), y otras eliminaciones de Java listadas bajo “Cambios de ruptura en code.”
• En iOS, detenga el uso de la CAPBridge clase de compatibilidad y deprecada CAPBridgeProtocol helpers; use ApplicationDelegateProxy, typed PluginCall accesores y propiedades de puente desde la tabla de migración.
• Ejecutar bunx @capacitor/plugin-migration-v8-to-v9@latest on a branch and keep only the API edits that still compile against Cap 8 peer dependencies until you publish a major for Cap 9.

No elimine la Cordova producto de SPM de tu plugin Package.swift mientras todavía soportes Capacitor 8. Proyectos basados en SPM de Cap 8 esperan esa dependencia; eliminarla temprano rompe a los consumidores que aún están en 8. opcional Cordova / eliminando la condicional Cordova product Ejecuta Capacitor 9-solo release line (or a semver major explicitly documented as Cap 9+), after you stop supporting Cap 8 — as described in the plugin guide, not as prep work on the Cap 8 line.

La misma regla de dedo aplica para actualizar capacitor-swift-pm to 9.0.0-alpha.x in Package.swiftEso pertenece a su Cap 9 mayor, no a una versión compatible con Cap-8.

Capgo actualizaciones en vivo y la construcción nativa de Cap 9

Capgo entrega paquete web actualiza sobre la red; la caja nativa sigue proveniendo de la Tienda de Mac App y Google Play. Cuando muevas tu aplicación a Capacitor 9:

1. Envía al menos una compilación de tienda compilado contra Capacitor 9 proyectos nativos (iOS y Android). Ese binario establece la base nativa Capgo para los canales de destino.
2. Sólo después de que esa compilación esté en manos de los usuarios, debería confiar en paquetes de actualizaciones OTA probados contra Cap 9 WebView y comportamiento de plugins.
3. Coloque los canales de producción en el metadata No omita (los paquetes nativos están supuestos a cambiar). Mantenga --auto-min-update-versionPara ese subida de línea base nativa intencional. omit --fail-on-incompatible Flujo de trabajo de canal NATIVO + OTA --fail-on-incompatible and --auto-min-update-version después de cada carga OTA diaria. Ver Flujo de trabajo de canal nativo + OTA.
4. Keep channel and semver rules aligned so you never push a bundle that assumes Cap 9 APIs to devices still running an older native shell.

Si utilizas Capgo Construcción o su propio CI, agentes de actualización antes La liberación del almacén Cap 9 para que el pipeline coincida con lo que los usuarios instalan. macOS los ejecutores necesitan Node 24+ y Xcode 27+; Linux los ejecutores necesitan Node 24+ y herramientas de Android de host alineadas con AGP 9.2.1 / Gradle 9.5.1 (Xcode es solo para macOS).

Orden sugerido de operaciones

1. Actualice las herramientas instaladas en los hosts CI y máquinas de desarrolladores a los pisos por encima (Node, Xcode, Android Studio, JDK). No incremente la dependencia de AGP de la aplicación Cap 8, el wrapper de Gradle o otros archivos de proyecto Android a valores de Cap 9 hasta bunx cap migrate que esos cambios de proyecto pertenezcan al paso de migración.
2. Corrija las API nativas obsoletas en la aplicación code y plugins (especialmente personalizados) AppDelegate Limpie los archivos y scripts de Gradle de Android
3. Clean Gradle Android por defecto de ProGuard,gradle.propertiesen los scripts de desarrollo). --url (in scripts de desarrollo).
4. Revisar Cordova No cambie plugins SPM Cordova hasta las versiones de Cap 9 únicamente.
5. Cuando Cap 9 esté disponible (o cuando acepte next), ejecute bun add -d @capacitor/cli@next (o @latest después de su lanzamiento) bunx cap migratedespués de su lanzamiento), luego Actualizando a 9.0.
6. Publica la compilación nativa de Cap 9 a las tiendas, luego reanude o amplíe Capgo actualizaciones OTA en el canal correspondiente.

Capacitor 9 is mostly “pay down deprecations and align with modern Android and Apple toolchains.” Doing that work on Cap 8 keeps your upgrade diff small and your plugins compatible with the teams still shipping 8.x today.