Capacitor 9 está disponible en el next dist-tag mientras avanza hacia la disponibilidad general. No tienes que actualizar tu app el día que llegue la alpha, pero la guía oficial de actualización a Capacitor 9 y guía de actualización de plugins ya detallan los requisitos mínimos de toolchain y las eliminaciones de API que conviene abordar pronto.
Este artículo es una preparation checklist: trabajo que puedes realizar en Capacitor 8 (o en una rama) para que el bunx cap migrate El paso es aburrido, no doloroso. Cuando estés listo para hacer el cambio, sigue las guías de Ionic enlazadas arriba, línea por línea.
Herramientas y versiones mínimas de plataforma (apps)
Planifica tu CI, tus máquinas locales y tus pipelines de tiendas en torno a estos mínimos:
| Área | Requisito de Capacitor 9 |
|---|---|
| Node.js | 24+ (la LTS más reciente es la recomendada; npm 11 incluye Node 24) |
| Xcode | 27+ |
| Target de despliegue de iOS | 16.0+ |
| Android Studio | 2026.1.1+ |
| Android Gradle Plugin (AGP) | 9.2.1 |
| Gradle wrapper | 9.5.1 |
Si todavía usas Capacitor 8.4 o anterior en iOS, también necesitarás el ciclo de vida de UIScene usa la actualización Capacitor 8.5 antes de Cap 9; Xcode 27 lo requiere. Las apps en 8.5 pueden saltarse ese paso.
En iOS, Swift 6 (con Xcode 27) rechaza @UIApplicationMain; al actualizar, reemplázalo con @main en AppDelegate.swift como se describe en la guía oficial.
Cordova al sincronizar la app (no es un paso de preparación de plugins)
En Capacitor 9, la capa de compatibilidad de Cordova se solo se conecta a tu app 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.
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 de forma preventiva. Solo audita si algún código nativo personalizado de code (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 gradle.properties flags para que los builds mantengan el comportamiento de AGP 8. Capacitor 9 apps deben eliminar esas entradas en lugar de arrastrarlas: la mayoría están deprecadas 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.gradlelos mínimos (compile/target SDK 37,minSdkVersion26, versiones de AndroidX actualizadas — consulta la doc oficial). - Eliminar explícitamente
targetSdkVersionde la appbuild.gradlepara que AGP 9 pueda inferirlo a partir decompileSdkVersion. - Declarar
variables.gradlesímbolos al inicio deapp/build.gradle(Gradle 9.6 deprecó la búsqueda implícita desde el proyecto raíz). - Cambia los nombres predeterminados de ProGuard, migra
core-ktxaandroidx.core:core1.19.0+, elimina el uso del plugin standalone de Kotlin Gradle y quitajcenter().
Puedes leer los diff hunks en la 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 live-reload host/port/https 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 dev:
bunx cap run android --url http://192.168.1.181:5173/
Actualiza tus scripts y fragmentos del README ahora para que la memoria muscular no choque con el nuevo CLI tras la actualización.
Plugins oficiales: trampas con push y splash
Dos cambios orientados al usuario suelen aparecer en las apps en producción:
Notificaciones push (iOS): La opción obsoleta alert presentation se ha eliminado. Usa banner y/o list en tus opciones de presentación.
Pantalla de inicio (Android): Predeterminado launchFadeOutDuration cambia de 200 ms a 0. Si dependías del desvanecimiento 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 actualizaciones de versión de AndroidX y Google Play Services vinculadas a los plugins oficiales que utilices.
Mantenedores de plugins: prepárense para Cap 9 sin romper Cap 8
Si publicas plugins Capacitor consumidos en Capacitor 8 y quiere que code esté listo para Cap 9, céntrate en deprecación y eliminación de API, no en los cambios de empaquetado exclusivos de Cap-9.
Seguro de hacer mientras Cap 8 siga soportado:
- Reemplazar
@NativePlugincon@CapacitorPluginy migrar las APIs legacy de permisos / activity-result a@PermissionCallback/@ActivityCallbackpatrones (ver la guía del plugin 9.0 tabla). - Eliminar
PluginCall.hasOption,Plugin.getConfigValue, antiguosCapConfigconstructores y getters,PluginCall.save()/isSaved(), y otras eliminaciones de Java listadas bajo «Cambios incompatibles en code». - En iOS, deja de usar la
CAPBridgeclase de compatibilidad y losCAPBridgeProtocolhelpers obsoletos; usaApplicationDelegateProxy, losPluginCallaccessors y propiedades del bridge de la tabla de migración. - Ejecuta
bunx @capacitor/plugin-migration-v8-to-v9@latesten una rama y conserva solo las ediciones de API que aún compilan con las dependencias peer de Cap 8 hasta que publiques una versión mayor para Cap 9.
No elimines el Cordova producto SPM de tu plugin en Package.swift mientras sigas soportando Capacitor 8. Los proyectos de Cap 8 esperan esa dependencia cuando tu plugin es SPM; eliminarla pronto rompe a los consumidores que siguen en 8. Trata opcional Cordova / eliminación de lo incondicional Cordova producto como un solo Capacitor 9 línea de release (o un semver major documentado explícitamente como Cap 9+), después de dejar de soportar Cap 8 — como se describe en la guía de plugins, no como trabajo preparatorio en la línea Cap 8.
La misma regla general se aplica al bump 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.
live updates de Capgo y el build nativo de la store para Cap 9
Capgo entrega web bundle actualizaciones OTA; el shell nativo sigue viniendo de la App Store y Google Play. Al pasar tu app a Capacitor 9:
- Publicar al menos un build de la tienda compilado para 9 proyectos nativos de Capacitor 9 (iOS y Android). Ese binario establece la base nativa que apuntan los canales de Capgo.
- 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.
- Configura los canales de producción en
metadataestrategia 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-incompatibley--auto-min-update-versionen las subidas OTA diarias posteriores. Ver Flujo de trabajo de channels Native + OTA. - Mantén alineados el channel y las reglas de semver para no subir un bundle que asuma APIs de Cap 9 a dispositivos que aún usan un native shell antiguo.
Si usas Build de Capgo o en tu propio CI, refresca los agentes antes el release de tienda de Cap 9 para que el pipeline coincida con lo que instalan los usuarios: macOS los runners necesitan Node 24+ y Xcode 27+; Linux los runners necesitan Node 24+ y las herramientas de Android del host alineadas con AGP 9.2.1 / Gradle 9.5.1 (Xcode es exclusivo de macOS).
Orden de operaciones sugerido
- Actualizar las herramientas instaladas en hosts de CI y máquinas de desarrollo hasta las capas superiores (Node, Xcode, Android Studio, JDK). No actualiza la dependencia de AGP, el wrapper de Gradle u otros archivos del proyecto Android de la app Cap 8 a los valores de Cap 9 hasta
bunx cap migrate— esos cambios de proyecto pertenecen al paso de migración. - Corregir APIs nativas obsoletas en la app code y los plugins (especialmente los personalizados
AppDelegatemanejo de URLs y uso del bridge de Android). - Limpiar Android Gradle archivos y scripts (
gradle.properties, valores por defecto de ProGuard,--urlen scripts de dev). - 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.
- Cuando Cap 9 sea GA (o cuando aceptes
next), ejecutabun add -d @capacitor/cli@next(o@latesttras el lanzamiento), entoncesbunx cap migrate, y sigue Actualización a 9.0. - Publica el build nativo de Cap 9 en las tiendas, luego retoma o amplía los rollouts OTA de Capgo en el canal correspondiente.
La versión 9 de Capacitor va sobre todo de eliminar deprecaciones y alinearse con los toolchains modernos de Android y Apple. Hacer ese trabajo en Cap 8 mantiene pequeño el diff de la actualización y tus plugins compatibles con los equipos que siguen publicando la 8.x hoy.