Cómo usar CocoaPods con Capacitor 8 (y cuándo no hacerlo)

Para usar CocoaPods con Capacitor 8, crea la plataforma iOS con bunx cap add ios --packagemanager CocoaPods, instala CocoaPods (Homebrew o un Gemfile con Bundler) y deja que bunx cap sync ios gestione el Podfile y ejecute pod install. Capacitor 8 sigue siendo totalmente compatible con CocoaPods. Solo ha cambiado el valor por defecto para nuevos proyectos a Swift Package Manager.

CocoaPods ya no es la dirección a largo plazo y su trunk pasa a solo lectura el 2 de diciembre de 2026. Así que la verdadera pregunta es cuándo sigue siendo la opción correcta, cómo mantenerlo funcionando y cómo salir de él de forma limpia. Esta guía cubre las tres cosas.

Cuándo CocoaPods sigue siendo la opción correcta

Quédate en CocoaPods, o elígelo, si se da alguno de estos casos:

• Un plugin que necesitas no tiene Package.swift. En un proyecto SPM, CLI avisa: “Some installed Capacitor plugins are not compatible with SPM” y deja ese plugin fuera, así que falla en runtime con “plugin is not implemented”.
• Un SDK de un vendor se distribuye solo como pod. Algunos SDK de analíticas, pagos e identidad todavía solo incluyen CocoaPods, o vienen con un xcframework que tendrías que envolver tú mismo.
• Un plugin de Cordova depende de pods. Capacitor genera un Swift package para plugins de Cordova en proyectos SPM, pero los más complejos con <podspec> dependencias suelen funcionar mejor con CocoaPods.
• Dependes de los subspecs de podspec para elegir variantes de SDK. SPM ya tiene package traits, y Capacitor los soporta experimentalmente desde CLI 8.3 (ver SPM package traits en Capacitor), pero el plugin debe definir los traits primero.
• Un proyecto de Xcode grande y personalizado donde una migración no vale el riesgo en este ciclo de lanzamiento.

Las colisiones de identidad de paquetes solían ser otro motivo. Desde CLI 8.4 puedes sortearlas en SPM con experimental.ios.spm.packageOptions (symlink o moduleAliases) en tu configuración de Capacitor.

Si no aplica ninguno de estos casos, usa SPM. No necesita toolchain de Ruby, ni Podfile ni .xcworkspace.

CocoaPods vs SPM en Capacitor 8

Instalar CocoaPods

Elige un enfoque y úsalo en todas partes, incluida la CI.

Homebrew (lo más simple para un solo desarrollador):

brew install cocoapods
pod --version

Bundler (fija la versión para todo el equipo, recomendado para CI). Crea un Gemfile en la raíz del proyecto o en ios/App:

source 'https://rubygems.org'
gem 'cocoapods', '~> 1.16'

bundle install

Cuando el Capacitor CLI encuentra un Gemfile que menciona CocoaPods, ejecuta bundle exec pod install en lugar de pod install. Si pod está en una ruta inusual, configura CAPACITOR_COCOAPODS_PATH apuntando al binario.

Crea una app de Capacitor 8 con CocoaPods

bun add @capacitor/ios
bun run build
bunx cap add ios --packagemanager CocoaPods
bunx cap open ios

cap open ios abre App.xcworkspace. Siempre haz el build desde el workspace. Abrir App.xcodeproj te da directamente No such module 'Capacitor'.

El Podfile, explicado

Este es el Podfile que genera Capacitor 8:

require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'

platform :ios, '15.0'
use_frameworks!

install! 'cocoapods', :disable_input_output_paths => true

def capacitor_pods
  pod 'Capacitor', :path => '../../node_modules/@capacitor/ios'
  pod 'CapacitorCordova', :path => '../../node_modules/@capacitor/ios'
end

target 'App' do
  capacitor_pods
  # Add your Pods here
end

post_install do |installer|
  assertDeploymentTarget(installer)
end

Qué puedes y qué no puedes modificar:

• def capacitor_pods ... end pertenece al CLI. En cada sync, reemplaza todo el bloque por uno pod con una línea por plugin, apuntando a la carpeta del plugin en node_modules. Cualquier cosa que añadas dentro se perderá.
• Añade tus propios pods bajo target 'App', después de capacitor_pods.
• assertDeploymentTarget eleva cualquier pod con un deployment target inferior a 15.0 a 15.0, evitando así los warnings de Xcode sobre targets no soportados. Mantén esto y añade tu propia post_install lógica dentro del mismo bloque.
• platform :ios debe ser al menos 15.0 para Capacitor 8.

Ejemplo con un pod extra y un fix de build setting:

target 'App' do
  capacitor_pods
  pod 'GoogleMLKit/BarcodeScanning', '~> 7.0'
end

post_install do |installer|
  assertDeploymentTarget(installer)
  installer.pods_project.targets.each do |target|
    if target.respond_to?(:product_type) && target.product_type == 'com.apple.product-type.bundle'
      target.build_configurations.each do |config|
        config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
      end
    end
  end
end

El bucle desactiva el signing de code para targets de resource bundle. Corrige Signing for "X" requires a development team en pods que incluyen resource bundles. Solo añádelo si te da ese error.

Comandos del día a día

# After installing or removing a plugin
bunx cap sync ios

# Use the exact versions in Podfile.lock (good for CI)
bunx cap sync ios --deployment

# Refresh the spec repo when a new pod version isn't found
cd ios/App && pod repo update && pod install

# Update one pod past its locked version
cd ios/App && pod update FirebaseMessaging

cap sync ios also runs xcodebuild clean en el proyecto después de pod install, así que no necesitas un clean manual tras añadir plugins.

Haz commit de Podfile y Podfile.lock. No hagas commit de ios/App/Pods/. Se regenera mediante pod install.

Cambiar una app existente de SPM a CocoaPods

No existe un comando de migración inversa. Hazlo manualmente:

1. Haz commit y luego copia ios/ en un lugar seguro.
2. Eliminar ios/.
3. Ejecuta bunx cap add ios --packagemanager CocoaPods.
4. Reaplica los cambios nativos: Info.plist keys, entitlements y capabilities, signing team, bundle identifier, app icons y splash assets, URL schemes, extensions (widgets, notification service) y cualquier Swift personalizado en AppDelegate.
5. bunx cap sync ios y compila.

Comparar las carpetas ios/App/App antigua y nueva es la forma más rápida de ver qué olvidaste.

Cómo solucionar errores comunes de CocoaPods

CocoaPods could not find compatible versions for pod "X". Tu repo de specs local está desactualizado o dos pods requieren versiones incompatibles. Ejecuta pod install --repo-update en ios/App. Si sigue fallando, revisa la cadena de dependencias en el error, busca el plugin con la versión fija, actualízalo o parchear su podspec.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. El Pods la carpeta no coincide con el lock file, normalmente tras cambiar de rama. Ejecuta bunx cap sync ios.

[!] Unable to find a specification for 'X'. La caché del spec repo está desactualizada o el nombre del pod es incorrecto. Ejecuta pod repo update.

Unable to find compatibility version string for object version '70' (o 77). Tu proyecto de Xcode usa un formato más reciente de lo que permite tu gema CocoaPods/xcodeproj. Actualiza CocoaPods a la última versión. Si no puedes, haz una copia de seguridad project.pbxproj y establece objectVersion a un valor que soporte tu CocoaPods.

Sandbox: rsync(...) deny(1) file-write-create. El sandboxing de scripts de usuario de Xcode bloquea el script de embed de CocoaPods. En Build Settings del proyecto, establece Sandboxing de User Scripts (ENABLE_USER_SCRIPT_SANDBOXING) a No para el target App.

No such module 'Capacitor'. Abriste App.xcodeproj. Abre App.xcworkspace, o ejecuta bunx cap open ios.

pod: command not found en CI. Instala CocoaPods en el job, o usa Bundler con una caché vendor/bundle. Sin esto, el CLI registra “Skipping pod install because CocoaPods is not installed” y el build falla más tarde.

Más errores de build en iOS se cubren en el Guía de troubleshooting de iOS de Capacitor.

La fecha de solo lectura de CocoaPods Trunk

Los mantenedores de CocoaPods anunciaron que trunk, el repositorio central de especificaciones, pasará a ser de solo lectura el 2 de diciembre de 2026, tras una prueba a principios de noviembre de 2026. Lo que esto significa para una app de Capacitor:

• Las builds existentes siguen funcionando. Cada podspec publicado sigue disponible.
• No hay nuevas versiones a través de trunk. Los SDK que obtienes de trunk (Firebase, Google ML Kit, SDK de proveedores) dejarán de recibir actualizaciones allí. Las correcciones de seguridad y el nuevo soporte para iOS SDK solo se distribuirán a través de SPM u otros canales.
• Los propios plugins de Capacitor no se ven afectados directamente. Se instalan desde npm y se referencian mediante :path en el Podfile. Sus dependencias pod transitivas sí se ven afectadas.

Considera CocoaPods como un puente. Identifica qué dependencia te mantiene en él y revísalo cuando esa dependencia añada soporte para SPM.

Cómo dejar de usar CocoaPods

Cuando estés listo:

bunx cap spm-migration-assistant

Se ejecuta pod deintegrate, elimina el Podfile, Podfile.lock y App.xcworkspace, crea CapApp-SPM, y escribe un debug.xcconfig. Luego agregas CapApp-SPM como un paquete local en Xcode y configuras debug.xcconfig como archivo de configuración de Debug. La guía completa está en cómo migrar tu app de Capacitor a SPM, y las compensaciones se abordan en SPM vs CocoaPods para Capacitor.

Los autores de plugins que necesiten añadir soporte SPM deberían leer migrar un plugin de Capacitor a SPM.

Si gestionar las versiones de Ruby, CocoaPods y Xcode en las máquinas de build es la parte dolorosa, Build de Capgo compila proyectos de CocoaPods y SPM en la nube con la versión actual de Xcode.