Preparándonos para Capacitor 9: qué pueden hacer ahora los equipos de apps y plugins

Capacitor 9 ya está disponible en la next dist-tag mientras avanza hacia su disponibilidad general. No necesitas actualizar tu app el día que sale la alpha, pero la guía oficial de actualización de Capacitor 9 y guía de actualización de plugins ya detalla las carencias en el toolchain y las eliminaciones de API que conviene resolver pronto.

Este artículo es una preparación checklist: tareas que puedes hacer en Capacitor 8 (o en una rama) para que la bunx cap migrate transición sea sencilla y no dolorosa. Cuando estés listo para el cambio, sigue las guías de Ionic enlazadas arriba paso a paso.

Limitaciones de toolchain y plataformas (apps)

Planifica tu CI, máquinas locales y pipelines de la tienda basándote en estos mínimos:

Si aún usas Capacitor 8.4 o anterior en iOS, también necesitarás el ciclo de vida UIScene que funciona con la actualización de Capacitor 8.5 previa a Cap 9; Xcode 27 lo requiere. Las apps en 8.5 pueden saltarse este paso.

En iOS, Swift 6 (con Xcode 27) rechaza @UIApplicationMain; al actualizar, reemplázalo con @main en AppDelegate.swift como se indica en la guía oficial.

Cordova al sincronizar la app (no es un paso de preparación de plugin)

En Capacitor 9, la capa de compatibilidad de Cordova se conecta a tu app solo cuando cap sync detecta un plugin de Cordova instalado. Android elimina los módulos Gradle extra si no hay ninguno; iOS deja de añadir CapacitorCordova al Podfile o Package.swift cuando no hay ninguno presente.

Ese es un cambio de comportamiento a nivel de app tras la actualización. Mientras sigas en Cap 8, no hace falta que elimines Cordova de tu template por adelantado. Solo audita si algún code nativo personalizado (propio o de un plugin fork) importa símbolos de Cordova sin tener un plugin de Cordova real en el proyecto; esas referencias fallarán cuando se aplique la conexión opcional de Cordova.

Android: gradle.properties y los valores predeterminados de AGP 9

El AGP Upgrade Assistant suele escribir flags gradle.properties explícitos para mantener el comportamiento de AGP 8. Las apps con Capacitor 9 deberían eliminar esas entradas en lugar de arrastrarlas: la mayoría quedan obsoletas antes de AGP 10, y algunas rompen builds de Cap 9 (por ejemplo, android.builtInKotlin=false desactiva el soporte de Kotlin que incluye AGP 9, y android.sdk.defaultTargetSdkToCompileSdkIfUnset=false evita que AGP infiera targetSdkVersion).

Al migrar, también deberás:

• Subir variables.gradle los mínimos (compile/target SDK 37, minSdkVersion 26, versiones de AndroidX actualizadas; consulta la doc oficial).
• Elimina lo explícito targetSdkVersion de la app build.gradle para que AGP 9 pueda inferirlo de compileSdkVersion.
• Declara variables.gradle símbolos al principio de app/build.gradle (Gradle 9.6 depreca la búsqueda implícita desde el proyecto raíz).
• Cambia los nombres de archivos ProGuard, migra core-ktx a androidx.core:core 1.19.0+, deja de usar el plugin de Kotlin Gradle independiente y elimina jcenter().

Puedes leer los diff hunks en el Actualización a 9.0 sección de Android y aplica las mismas limpiezas en una rama antes de subir las versiones de Capacitor.

CLI: cap run --url

Capacitor 9 unifica los flags de host/port/https de live-reload en un único --url argumento. En lugar de:

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

pasa la URL que imprime tu servidor de desarrollo:

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

Actualiza tus scripts y fragmentos de README para que la memoria muscular no te juegue una mala pasada con el nuevo CLI tras la actualización.

Plugins oficiales: detalles sobre push y splash

Dos cambios de cara al usuario suelen aparecer en apps de producción:

Notificaciones push (iOS): Lo que queda obsoleto alert deprecated presentation ha sido eliminada. Usa banner y/o list en tus opciones de presentación.

Splash Screen (Android): Por defecto launchFadeOutDuration cambios de 200 ms a 0. Si dependías del fade para ocultar glitches de first paint, configúralo launchFadeOutDuration: 200 explícitamente en capacitor.config hasta que ajustes tu UI de inicio.

Revisa las secciones de plugins en la guía de actualización de 9.0 para ver los cambios de versión de AndroidX y Google Play Services en tus plugins oficiales.

Maintainers de plugins: prepárense para Cap 9 sin romper Cap 8

Si distribuyes plugins Capacitor usados en Capacitor 8 y si quieres code listo para Cap 9, enfócate en la eliminación de API obsoletos, no sobre cambios de empaquetado exclusivos de Cap-9.

Es seguro hacerlo mientras Cap 8 tenga soporte:

• Reemplaza @NativePlugin con @CapacitorPlugin y migra las APIs de permisos / activity-result antiguas a @PermissionCallback / @ActivityCallback nuevos patrones (consulta la guía del plugin 9.0 en la tabla).
• Eliminar PluginCall.hasOption, Plugin.getConfigValue, antiguos CapConfig constructores y getters, PluginCall.save() / isSaved(), y otras eliminaciones de Java listadas en “Breaking changes in code.”
• En iOS, deja de usar la CAPBridge clase de compatibilidad y los CAPBridgeProtocol helpers obsoletos; usa ApplicationDelegateProxy, tipados PluginCall accessors y propiedades de bridge de la tabla de migración.
• Ejecuta bunx @capacitor/plugin-migration-v8-to-v9@latest en una rama y mantén solo los cambios de API que aún compilen con las peer dependencies de Cap 8 hasta que publiques una versión mayor para Cap 9.

No elimines el Cordova producto SPM de tu plugin Package.swift mientras sigas dando soporte a Capacitor 8. Los proyectos de Cap 8 esperan esa dependencia si tu plugin usa SPM; eliminarla antes romperá a los usuarios que sigan en la 8. Trata opcional de Cordova / eliminar lo incondicional Cordova producto como un Capacitor solo para 9 línea de lanzamiento (o un semver major documentado como Cap 9+), una vez que dejes de soportar Cap 8 — tal como indica la guía de plugins, no como preparación en la línea de Cap 8.

La misma regla general se aplica al subir la versión de capacitor-swift-pm a 9.0.0-alpha.x en Package.swift: eso pertenece a tu major de Cap 9, no a un release compatible con Cap 8.

Capgo live updates y el Native Build de Cap 9 para tiendas

Capgo entrega web bundles vía OTA; el shell nativo sigue viniendo de la App Store y Google Play. Al migrar tu app a Capacitor 9:

1. Publicar al menos un build de la tienda compilado con proyectos nativos de Capacitor 9 (iOS y Android). Ese binario establece la base nativa que apuntan los canales Capgo.
2. Solo cuando ese build esté en manos de los usuarios deberías confiar en bundles OTA probados con el comportamiento de WebView y plugins de Cap 9.
3. Configura los canales de producción en la metadata estrategia y sube el bundle de Cap 9 correspondiente a cada canal con --auto-min-update-version. Para esa subida intencional de la base nativa, omite --fail-on-incompatible (se supone que los paquetes nativos cambian). Mantén --fail-on-incompatible y --auto-min-update-version en los uploads OTA diarios después. Ver Flujo de trabajo Native + canal OTA.
4. Mantén alineados el canal y las reglas de semver para no subir un bundle que use APIs de Cap 9 a dispositivos con un native shell antiguo.

Si usas Build con Capgo o tu propio CI, actualiza los agentes antes el release de la tienda de Cap 9 para que el pipeline coincida con lo que instalan los usuarios: macOS runners requieren Node 24+ y Xcode 27+; Linux los runners requieren Node 24+ y herramientas de Android alineadas con AGP 9.2.1 / Gradle 9.5.1 (Xcode es solo para macOS).

Orden de operaciones sugerido

1. Actualizar las herramientas instaladas en hosts de CI y máquinas locales a las versiones mencionadas (Node, Xcode, Android Studio, JDK). No actualices la dependencia de AGP, el Gradle wrapper u otros archivos de Android de la app en Cap 8 a valores de Cap 9 hasta que bunx cap migrate — esos cambios pertenecen al paso de migración.
2. Corregir APIs nativas obsoletas en la app code y plugins (especialmente custom AppDelegate manejo de URLs y uso del bridge de Android).
3. Limpiar Android Gradle archivos y scripts (gradle.properties, valores por defecto de ProGuard, --url en scripts de dev).
4. Auditar el uso de Cordova a nivel de app; no cambies los productos Cordova SPM de los plugins hasta los lanzamientos exclusivos de Cap 9.
5. Cuando Cap 9 sea GA (o cuando aceptes next), ejecuta bun add -d @capacitor/cli@next (o @latest tras el lanzamiento), entonces bunx cap migrate, y sigue Actualización a la versión 9.0.
6. Publica el Native Build de Cap 9 en las tiendas, y luego retoma o expande los rollouts OTA de Capgo en el canal correspondiente.

La versión 9 de Capacitor consiste principalmente en "eliminar deprecations y alinearse con los toolchains modernos de Android y Apple". Hacer ese trabajo en Cap 8 mantiene el diff de la actualización pequeño y tus plugins compatibles con los equipos que aún lanzan la 8.x hoy en día.