Cara Migrasi App Capacitor ke Swift Package Manager

Capacitor 8 membuat proyek iOS baru dengan Swift Package Manager (SPM) secara default. Aplikasi yang masih menggunakan CocoaPods juga bisa bermigrasi, tetapi jalur paling aman bergantung pada seberapa banyak kustomisasi native iOS yang dimiliki aplikasi Anda.

Panduan ini membahas apa yang berubah, apa yang harus di-backup, dan dua jalur migrasi praktis: menggunakan asisten migrasi Capacitor atau membuat ulang kerangka proyek iOS dengan SPM.

Mengapa migrasi sekarang

CocoaPods sedang beralih ke trunk read-only. Rencana saat ini adalah CocoaPods trunk akan berhenti menerima podspec baru pada 2 Desember 2026. Build yang sudah ada seharusnya tetap berfungsi, tetapi rilis baru dan pembaruan dependensi yang bergantung pada trunk tidak akan dipublikasikan di sana setelah perpindahan.

SPM juga merupakan arah yang dituju 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 di proyek Capacitor SPM

Migrasi dari CocoaPods ke SPM mengganti lapisan dependensi iOS. Aplikasi web, proyek Android, dan sebagian besar perintah workflow Capacitor tetap sama.

CapApp-SPM menggantikan Podfile

Pada aplikasi CocoaPods, dependensi iOS dihubungkan melalui ios/App/Podfile, Podfile.lock, Pods/, dan yang dihasilkan .xcworkspace.

Pada aplikasi SPM, Capacitor membuat paket lokal bernama CapApp-SPM. Paket ini menjadi tempat sentral di mana Capacitor merujuk dependensi plugin iOS native Anda. Capacitor CLI memperbarui CapApp-SPM saat Anda mensinkronkan plugin, jadi perlakukan sebagai output yang dihasilkan dan hindari mengeditnya secara manual.

debug.xcconfig menggantikan konfigurasi Pods

Asisten migrasi juga membuat file yang dihasilkan debug.xcconfig. File ini membawa pengaturan build yang sebelumnya disediakan CocoaPods melalui file xcconfig yang dihasilkannya.

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

Setiap plugin harus mendukung SPM

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

Jika plugin belum mendukung SPM, perbarui, ganti, atau migrasikan plugin tersebut terlebih dahulu. Plugin Swift sederhana sering kali bisa dikonversi dengan capacitor-plugin-converterdari Ionic, tetapi plugin dengan struktur Objective-C dan Swift yang lebih kompleks mungkin memerlukan pekerjaan manual.

Yang harus di-backup terlebih dahulu

Mulai dari branch git yang bersih dan commit status saat ini sebelum menyentuh proyek iOS. Kemudian, daftarkan file native yang dibutuhkan aplikasi Anda.

File umum yang harus dipertahankan dari ios/App/ antara lain:

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

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

Opsi 1: Gunakan asisten migrasi Capacitor

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

Jalankan assistant dari root proyek Capacitor Anda:

bunx cap spm-migration-assistant

Assistant menghapus infrastruktur CocoaPods, membuat package lokal, CapApp-SPM menghasilkan package references dari plugin yang terinstal, dan membuat file konfigurasi SPM yang dihasilkan.

Setelah selesai, buka proyeknya:

bunx cap open ios

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

Tambah CapApp-SPM sebagai dependensi package lokal.
Tambahkan hasil generate debug.xcconfig ke konfigurasi aplikasi.
Atasi semua warning terkait plugin yang tidak bisa dikonversi ke SPM.
Build aplikasi dari Xcode sekali sebelum memperbarui CI.

Setelah proyek Xcode selesai di-build, sync lagi:

bunx cap sync ios

Opsi 2: Re-scaffold proyek iOS dengan SPM

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

Pertama, pastikan file yang tercantum di bagian backup sudah di-commit atau disalin ke tempat aman. Lalu 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

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

Aplikasi Capacitor baru

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

bunx cap add ios

Jika perlu lebih eksplisit, 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 yang menjalankan:

pod install

Hapus juga cache untuk:

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

Pertahankan langkah web build dan Capacitor sync reguler Anda. Job iOS biasanya 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 kerja saat ini.
Verifikasi semua plugin yang terinstal mendukung SPM.
Catat file iOS kustom dan pengaturan signing.
Pastikan aplikasi berhasil di-build sebelum migrasi.

Selama 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 penandatanganan rilis masih berfungsi.
Jalankan aplikasi di setidaknya satu simulator dan satu perangkat fisik sebelum rilis.

Pemecahan Masalah

Jika Xcode tidak dapat menyelesaikan paket, reset cache paket dari Xcode dan jalankan bunx cap sync ios lagi.

Jika migrasi gagal karena sebuah plugin, cek apakah plugin itu punya rilis lebih baru dengan dukungan SPM. Untuk plugin yang Anda kelola sendiri, migrasikan package plugin-nya dulu, baru kembali ke migrasi aplikasi.

Saat aplikasi berhasil di-build secara lokal tapi CI gagal, periksa asumsi CocoaPods lama. Penyebab umumnya adalah pemaksaan .xcworkspace build path, yang sudah usang pod install perintah yang usang, atau caching Pods/ dari build sebelumnya.

Kesimpulan

Migrasi aplikasi Capacitor ke Swift Package Manager pada dasarnya soal mengganti wiring dependency iOS. CapApp-SPM mengambil alih referensi dependency, debug.xcconfig menggantikan konfigurasi build CocoaPods yang di-generate, dan CI tidak lagi butuh pod install.

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

Sumber Daya

Lanjutkan dari 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 workflow produk di Alternatif Plugin Ionic Enterprise, Alternatif Capgo untuk alur kerja produk di Alternatif Capgo, Konsultasi Capgo untuk alur kerja produk di Capgo Consulting, dan Dukungan Premium Capgo untuk alur kerja produk di Capgo Premium Support.