Cara Menggunakan CocoaPods dengan Capacitor 8 (dan Kapan Sebaiknya Tidak)

Untuk menggunakan CocoaPods dengan Capacitor 8, buat platform iOS dengan bunx cap add ios --packagemanager CocoaPods, instal CocoaPods (Homebrew atau Gemfile dengan Bundler), lalu bunx cap sync ios kelola Podfile dan jalankan pod install. Capacitor 8 masih mendukung penuh CocoaPods. Hanya default untuk proyek baru yang berubah ke Swift Package Manager.

CocoaPods bukan lagi arah jangka panjang, dan trunk-nya akan menjadi read-only pada 2 Desember 2026. Jadi pertanyaannya adalah kapan ia masih menjadi pilihan tepat, cara menjaganya tetap jalan, dan cara migrasi dengan bersih. Panduan ini membahas ketiganya.

Kapan CocoaPods masih menjadi pilihan tepat

Tetap gunakan, atau pilih, CocoaPods jika salah satu kondisi ini terpenuhi:

• Plugin yang Anda butuhkan tidak memiliki Package.swift. Dalam proyek SPM, CLI memberi peringatan “Some installed Capacitor plugins are not compatible with SPM” dan tidak menyertakan plugin tersebut, sehingga gagal saat runtime dengan pesan “plugin is not implemented”.
• Vendor SDK hanya didistribusikan sebagai pod. Beberapa SDK analytics, payment, dan identity masih hanya menyediakan CocoaPods, atau menyediakan xcframework yang harus Anda wrap sendiri.
• Plugin Cordova bergantung pada pods. Capacitor membuat Swift package untuk plugin Cordova di proyek SPM, namun plugin kompleks dengan <podspec> dependencies cenderung bekerja lebih baik dengan CocoaPods.
• Anda mengandalkan subspec podspec untuk memilih varian SDK. SPM sekarang punya package traits, dan Capacitor mendukungnya secara eksperimental sejak CLI 8.3 (lihat SPM package traits di Capacitor), tapi plugin harus mendefinisikan traits-nya dulu.
• Proyek Xcode besar yang sudah dikustomisasi yang migrasinya tidak sepadan dengan risikonya di siklus rilis ini.

Tabrakan identitas package dulu juga jadi alasan lain. Sejak CLI 8.4 Anda bisa mengatasinya di SPM dengan experimental.ios.spm.packageOptions (symlink atau moduleAliases) di konfigurasi Capacitor Anda.

Jika tidak ada yang sesuai, gunakan SPM. Tidak perlu Ruby toolchain, Podfile, maupun .xcworkspace.

CocoaPods vs SPM di Capacitor 8

Instal CocoaPods

Pilih satu pendekatan dan gunakan di mana saja, termasuk CI.

Homebrew (paling simpel untuk satu developer):

brew install cocoapods
pod --version

Bundler (mengunci versi untuk seluruh tim, direkomendasikan untuk CI). Buat sebuah Gemfile di root proyek atau di ios/App:

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

bundle install

Saat Capacitor CLI menemukan Gemfile yang menyebutkan CocoaPods, ia akan menjalankan bundle exec pod install alih-alih pod install. Jika pod berada di lokasi yang tidak biasa, atur CAPACITOR_COCOAPODS_PATH ke binary tersebut.

Buat aplikasi Capacitor 8 dengan CocoaPods

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

cap open ios membuka App.xcworkspace. Selalu build dari workspace. Membuka App.xcodeproj langsung memberi Anda No such module 'Capacitor'.

Penjelasan Podfile

Ini Podfile yang dihasilkan 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

Apa yang bisa dan tidak bisa Anda ubah:

• def capacitor_pods ... end belongs to the CLI. Setiap kali sinkronisasi, seluruh blok diganti dengan satu pod baris per plugin, yang mengarah ke folder plugin di node_modules. Anything you add inside is lost.
• Tambahkan pod Anda sendiri di bawah target 'App', setelah capacitor_pods.
• assertDeploymentTarget menaikkan semua pod dengan deployment target di bawah 15.0 ke 15.0, untuk menghindari peringatan Xcode tentang target yang tidak didukung. Biarkan saja, dan tambahkan post_install logika Anda sendiri di dalam blok yang sama.
• platform :ios harus minimal 15.0 untuk Capacitor 8.

Contoh dengan pod tambahan dan perbaikan 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

Loop ini menonaktifkan signing code untuk target resource bundle. Ini memperbaiki masalah Signing for "X" requires a development team pada pod yang menyertakan resource bundle. Tambahkan hanya jika Anda menemui error tersebut.

Perintah sehari-hari

# 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 juga menjalankan xcodebuild clean pada proyek setelah pod install, jadi Anda tidak perlu melakukan clean manual setelah menambah plugin.

Commit Podfile dan Podfile.lock. Jangan commit ios/App/Pods/. File ini dibuat ulang oleh pod install.

Migrasi aplikasi dari SPM ke CocoaPods

Tidak ada perintah migrasi balik. Lakukan secara manual:

1. Commit, lalu salin ios/ ke tempat yang aman.
2. Hapus ios/.
3. Jalankan bunx cap add ios --packagemanager CocoaPods.
4. Terapkan kembali perubahan native: Info.plist keys, entitlements dan capabilities, signing team, bundle identifier, app icons dan splash assets, URL schemes, extensions (widgets, notification service), serta custom Swift di AppDelegate.
5. bunx cap sync ios dan build.

Membandingkan folder lama dan baru ios/App/App adalah cara tercepat untuk mengecek apa yang terlewat.

Memperbaiki error CocoaPods yang umum

CocoaPods could not find compatible versions for pod "X". Repo spec lokal Anda sudah usang atau ada dua pod yang butuh versi tidak kompatibel. Jalankan pod install --repo-update di ios/App. Jika masih gagal, periksa rantai dependensi pada error tersebut, cari plugin dengan versi yang terkunci ketat, lalu upgrade atau patch podspec-nya.

The sandbox is not in sync with the Podfile.lock. Run 'pod install'. Panduan Pods tidak cocok dengan lock file, biasanya setelah pindah branch. Jalankan bunx cap sync ios.

[!] Unable to find a specification for 'X'. Cache repo spec sudah usang atau nama pod salah. Jalankan pod repo update.

Unable to find compatibility version string for object version '70' (atau 77). Proyek Xcode Anda menggunakan format yang lebih baru dari yang dipahami gem CocoaPods/xcodeproj. Update CocoaPods ke versi terbaru. Jika tidak bisa, backup project.pbxproj dan atur objectVersion ke nilai yang didukung CocoaPods Anda.

Sandbox: rsync(...) deny(1) file-write-create. User script sandboxing di Xcode memblokir script embed CocoaPods. Di Pengaturan Build, atur Sandboxing User Script (ENABLE_USER_SCRIPT_SANDBOXING) ke Tidak untuk target App.

No such module 'Capacitor'. Anda membuka App.xcodeproj. Buka App.xcworkspace, atau jalankan bunx cap open ios.

pod: command not found di CI. Install CocoaPods di job, atau gunakan Bundler dengan cache vendor/bundle. Tanpa itu, CLI mencatat “Skipping pod install because CocoaPods is not installed” dan build akan gagal setelahnya.

Error build iOS lainnya dibahas di Panduan troubleshooting Capacitor iOS.

Tanggal read-only trunk CocoaPods

Maintainer CocoaPods mengumumkan bahwa trunk, repositori spec pusat, akan menjadi read-only pada 2 Desember 2026, setelah uji coba di awal November 2026. Berikut dampaknya bagi aplikasi Capacitor:

• Build yang sudah ada tetap berjalan. Setiap podspec yang sudah dipublikasikan tetap tersedia.
• Tidak ada versi baru melalui trunk. SDK yang Anda ambil dari trunk (Firebase, Google ML Kit, SDK vendor) tidak akan menerima update di sana lagi. Perbaikan keamanan dan dukungan iOS SDK terbaru hanya akan tersedia melalui SPM atau channel lainnya.
• Plugin Capacitor sendiri tidak terdampak secara langsung. Plugin tersebut diinstal dari npm dan direferensikan oleh :path di dalam Podfile. Begitu juga dengan transitive pod dependencies mereka.

Anggap CocoaPods sebagai jembatan. Catat dependency mana yang membuat Anda tetap menggunakannya, dan tinjau kembali saat dependency tersebut sudah mendukung SPM.

Beralih dari CocoaPods

Saat Anda siap:

bunx cap spm-migration-assistant

Ini menjalankan pod deintegrate, menghapus Podfile, Podfile.lock dan App.xcworkspace, membuat CapApp-SPM, dan menulis debug.xcconfig. Lalu tambahkan CapApp-SPM sebagai paket lokal di Xcode dan atur debug.xcconfig sebagai file konfigurasi Debug. Panduan lengkapnya ada di cara migrasi aplikasi Capacitor Anda ke SPM, dan perbandingannya dibahas di SPM vs CocoaPods untuk Capacitor.

Developer plugin yang perlu menambahkan dukungan SPM sebaiknya membaca migrasi plugin Capacitor ke SPM.

Jika mengelola versi Ruby, CocoaPods, dan Xcode di mesin build adalah bagian yang menyulitkan, Build Capgo melakukan build proyek CocoaPods dan SPM di cloud menggunakan Xcode terbaru.