Cara Migrasi Aplikasi Capacitor ke Swift Package Manager

Capacitor 8 membuat proyek iOS baru dengan Swift Package Manager (SPM) secara default. App yang sudah ada dan masih menggunakan CocoaPods juga bisa migrasi, namun jalur teraman tergantung pada seberapa banyak kustomisasi native iOS pada app Anda.

Panduan ini akan membahas apa saja yang berubah, apa yang perlu di-backup, dan dua jalur migrasi praktis: menggunakan Capacitor migration assistant atau melakukan re-scaffolding proyek iOS dengan SPM.

Mengapa migrasi sekarang

CocoaPods sedang beralih ke trunk read-only. Rencana saat ini adalah CocoaPods trunk akan berhenti menerima podspecs baru pada 2 Desember 2026. Build yang sudah ada seharusnya tetap berjalan, tetapi rilis baru dan update dependency yang bergantung pada trunk tidak akan dipublikasikan di sana setelah transisi.

SPM juga merupakan arah perkembangan Capacitor. Capacitor telah mendukung pemilihan CocoaPods atau SPM sejak Capacitor 6, dan Capacitor 8 kini membuat proyek iOS SPM sebagai template default.

Apa yang berubah dalam proyek Capacitor SPM

Migrasi dari CocoaPods ke SPM mengganti layer dependency iOS. Web app, proyek Android, dan sebagian besar perintah workflow Capacitor tetap sama.

CapApp-SPM menggantikan Podfile

Dalam aplikasi CocoaPods, dependency iOS dihubungkan melalui ios/App/Podfile, Podfile.lock, Pods/, and the generated .xcworkspace.

Dalam aplikasi SPM, Capacitor membuat package lokal bernama CapApp-SPM. Package ini menjadi tempat pusat di mana Capacitor mereferensikan dependency plugin native iOS Anda. Capacitor CLI updates CapApp-SPM saat Anda melakukan sync plugin, jadi perlakukan sebagai output yang di-generate dan hindari mengeditnya secara manual.

debug.xcconfig menggantikan konfigurasi Pods

Migration assistant juga membuat file debug.xcconfig. File ini berisi build settings yang sebelumnya disediakan CocoaPods melalui file xcconfig buatannya.

Setelah migrasi, Anda mungkin perlu menambahkan debug.xcconfig ke konfigurasi proyek Xcode jika asisten menyarankannya.

Setiap plugin harus mendukung SPM

Anda tidak bisa mencampur CocoaPods dan SPM dalam satu proyek iOS Capacitor. Sebelum migrasi, periksa setiap Capacitor dan plugin Cordova di package.json.

Jika plugin belum mendukung SPM, segera update, ganti, atau migrasikan plugin tersebut terlebih dahulu. Plugin Swift sederhana sering kali bisa dikonversi menggunakan capacitor-plugin-converter, namun plugin dengan layout Objective-C dan Swift yang lebih kompleks mungkin butuh penanganan manual.

Apa yang harus di-backup terlebih dahulu

Mulailah dari git branch yang bersih dan commit state saat ini sebelum menyentuh proyek iOS. Kemudian, list file native yang dibutuhkan app Anda.

File umum yang perlu dipertahankan dari ios/App/ termasuk:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, jika aplikasi Anda memilikinya
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, jika Anda menggunakan Firebase
Kustom .xcconfig file
Pengaturan signing, bundle identifier, team ID, dan pengaturan provisioning profile

Simpan juga file native Swift, Objective-C, framework, extension, atau SDK yang Anda tambahkan di luar template standar Capacitor.

Opsi 1: Gunakan asisten migrasi Capacitor

Gunakan jalur ini jika proyek iOS Anda memiliki edit native kustom yang tidak ingin Anda hilangkan.

Jalankan asisten dari root proyek Capacitor Anda:

bunx cap spm-migration-assistant

Asisten ini akan menghapus infrastruktur CocoaPods, membuat local CapApp-SPM package, membuat package references dari plugin yang terinstal, dan membuat file konfigurasi SPM.

Setelah selesai, buka proyeknya:

bunx cap open ios

Kemudian ikuti langkah manual Xcode yang ditampilkan oleh asisten. Pada kebanyakan proyek, ini berarti:

Tambahkan CapApp-SPM sebagai dependensi paket lokal.
Tambahkan yang dihasilkan debug.xcconfig ke konfigurasi aplikasi.
Selesaikan semua peringatan tentang plugin yang tidak bisa dikonversi ke SPM.
Build aplikasi dari Xcode satu kali sebelum memperbarui CI.

Setelah proyek Xcode berhasil di-build, lakukan sync kembali:

bunx cap sync ios

Opsi 2: Re-scaffold proyek iOS dengan SPM

Gunakan jalur ini jika ios/ direktori Anda mendekati template default Capacitor dan Anda dapat memulihkan file kustom dengan aman setelahnya.

Pertama, pastikan file yang terdaftar di bagian backup sudah di-commit atau disalin ke tempat aman. Kemudian hapus dan buat ulang proyek iOS dengan SPM:

rm -rf ios
bunx cap add ios --packagemanager SPM
bunx cap sync ios

Pulihkan file native yang dibutuhkan aplikasi Anda, lalu buka project-nya:

bunx cap open ios

Metode ini biasanya lebih bersih daripada migrasi in-place karena memberikan template Capacitor 8 iOS yang baru. Konsekuensinya, Anda harus teliti menerapkan ulang signing, entitlements, file Firebase, perubahan source native, dan pengaturan Xcode kustom lainnya.

Aplikasi Capacitor baru

Untuk aplikasi baru, Capacitor 8 menggunakan SPM secara default saat menambahkan iOS:

bunx cap add ios

Jika ingin lebih spesifik, Anda tetap bisa menyertakan opsi package manager:

bunx cap add ios --packagemanager SPM

Update CI setelah migrasi

Setelah aplikasi berhasil di-build secara lokal, update CI/CD agar tidak lagi mengasumsikan penggunaan CocoaPods.

Hapus langkah-langkah yang menjalankan:

pod install

Hapus juga cache untuk:

ios/App/Pods
ios/App/Podfile.lock
Repositori CocoaPods specs, jika workflow Anda hanya meng-cache-nya untuk aplikasi ini

Tetap gunakan langkah web build dan Capacitor sync reguler Anda. Job iOS pada umumnya harus menginstal dependensi JavaScript, build web assets, sync Capacitor, lalu build dengan Xcode:

bun install --frozen-lockfile
bun run build
bunx cap sync ios

Checklist migrasi

Sebelum migrasi:

Buat branch git baru.
Commit aplikasi yang sedang dikerjakan.
Pastikan semua plugin mendukung SPM.
Catat file iOS custom dan setting signing.
Pastikan app bisa di-build sebelum migrasi.

Saat migrasi:

Jalankan bunx cap spm-migration-assistant atau re-scaffold ios/.
Tambah CapApp-SPM di Xcode jika diperlukan.
Tambah debug.xcconfig di Xcode jika diperlukan.
Pulihkan file native spesifik aplikasi.
Jalankan bunx cap sync ios.

Setelah migrasi:

Build dan jalankan aplikasi di Xcode.
Hapus sisa file CocoaPods.
Hapus pod install dari CI.
Verifikasi signing rilis masih berfungsi.
Jalankan aplikasi di minimal satu simulator dan satu perangkat asli sebelum rilis.

Troubleshooting

Jika Xcode tidak bisa resolve package, reset package cache dari Xcode dan jalankan bunx cap sync ios lagi.

Jika migrasi gagal karena sebuah plugin, cek apakah plugin tersebut sudah punya rilis terbaru dengan dukungan SPM. Untuk plugin yang Anda kelola sendiri, migrasikan package plugin terlebih dahulu sebelum melanjutkan migrasi aplikasi.

Saat aplikasi berhasil build secara lokal tetapi CI gagal, periksa asumsi CocoaPods lama. Penyebab umum biasanya adalah paksaan .xcworkspace jalur build, yang usang pod install perintah yang usang, Pods/ dari build sebelumnya.

Kesimpulan

Migrasi aplikasi Capacitor ke Swift Package Manager pada dasarnya adalah tentang mengganti konfigurasi dependensi iOS. CapApp-SPM mengambil alih referensi dependensi, debug.xcconfig menggantikan konfigurasi build CocoaPods yang dihasilkan, dan CI tidak lagi memerlukan pod install.

Untuk proyek iOS kustom, mulailah dengan bunx cap spm-migration-assistant. Untuk proyek yang mendekati template default, melakukan re-scaffold SPM yang bersih sering kali lebih cepat dan lebih mudah dipahami.

Sumber Daya

Lanjut ke Cara Migrasi App Capacitor ke Swift Package Manager

Jika Anda menggunakan Cara Migrasi App Capacitor ke Swift Package Manager untuk merencanakan migrasi dan operasional enterprise, hubungkan dengan Capgo Enterprise untuk workflow produk di Capgo Enterprise, Alternatif Plugin Ionic Enterprise untuk alur kerja produk di Alternatif Plugin Ionic Enterprise, Alternatif Capgo untuk alur kerja produk di Alternatif Capgo, Capgo Consulting untuk alur kerja produk di Capgo Consulting, dan Capgo Premium Support untuk alur kerja produk di Capgo Premium Support.