Cara Migrasi Aplikasi Capacitor Anda ke Swift Package Manager

Swift Package Manager adalah standar untuk proyek iOS Capacitor. Jika aplikasi Anda masih menggunakan CocoaPods, Anda bisa migrasi aplikasi ke SPM tanpa harus membangun ulang JavaScript code, proyek Android, atau workflow rilis dari awal.

Panduan ini ditujukan untuk tim pengembang aplikasi. Di sini dijelaskan cara migrasi aplikasi iOS Capacitor dari CocoaPods ke SPM, apa saja yang diubah oleh migration assistant, apa yang perlu dicek di Xcode, dan cara membersihkan CI setelah build aplikasi selesai.

Perubahan pada aplikasi

Aplikasi Capacitor berbasis CocoaPods bergantung pada file seperti:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

Aplikasi Capacitor berbasis SPM memindahkan wiring dependensi iOS ke Swift Package Manager. Saat migrasi, Capacitor membuat paket lokal bernama CapApp-SPM dan menggunakannya untuk menghubungkan target aplikasi dengan Capacitor serta dependensi native yang terpasang.

Web build tetap berjalan dengan cara yang sama. Anda tetap menjalankan web build, sync Capacitor, buka Xcode, dan archive aplikasi. Perbedaan utamanya adalah CocoaPods tidak lagi memegang dependency graph iOS.

Sebelum migrasi

Mulailah dari branch yang bersih dan pastikan aplikasi saat ini bisa di-build sebelum mengubah dependency manager:

git status
npm run build
npx cap sync ios

Lalu commit kondisi yang sudah berfungsi. Migrasi ini menyentuh file project iOS hasil generate, jadi punya titik rollback yang bersih itu penting.

Selanjutnya, tinjau kustomisasi aplikasi Anda di bawah ios/App/. File dan pengaturan umum yang perlu dipertahankan meliputi:

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift, jika ada
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 provisioning profiles
app extension, file Swift native, file Objective-C, atau embedded framework

Periksa juga dependensi Capacitor dan Cordova yang terinstal. Migrasi SPM di level app bisa terhambat oleh dependensi native yang belum punya jalur kompatibel SPM. Update package tersebut sebelum migrasi jika memungkinkan.

Gunakan migration assistant

Untuk sebagian besar aplikasi yang sudah ada, mulailah dengan migration assistant resmi Capacitor:

npx cap spm-migration-assistant

Jalankan dari root proyek Capacitor Anda. Asisten akan menghapus integrasi CocoaPods dan membuat local CapApp-SPM package, membuat package reference untuk dependensi native yang terinstal, dan menambahkan konfigurasi yang dibutuhkan project iOS.

Setelah selesai, buka project iOS:

npx cap open ios

Baca output asisten sebelum menutup terminal Anda. Jika diminta untuk menyelesaikan langkah manual Xcode, lakukan hal tersebut sebelum melakukan sinkronisasi kembali.

Selesaikan langkah Xcode

Di Xcode, periksa konfigurasi app project dan target:

Konfirmasi CapApp-SPM ditambahkan sebagai dependensi package lokal.
Pastikan target app sudah menautkan produk package yang dihasilkan.
Tambahkan hasil generate debug.xcconfig ke konfigurasi proyek jika diminta oleh asisten.
Selesaikan semua warning package di Xcode.
Build app sekali dari Xcode.

Jika Xcode tidak bisa resolve package, gunakan File > Packages > Reset Package Caches, lalu resolve package kembali.

Sync dan build ulang

Setelah Xcode dikonfigurasi, kembali ke terminal dan sync Capacitor:

npx cap sync ios

Lalu build lagi dari Xcode. Jangan anggap migrasi selesai sampai clean build berhasil di Xcode, karena release signing, entitlements, app extensions, dan package resolution divalidasi di sana.

Jika aplikasi menggunakan push notifications, associated domains, background modes, app groups, Firebase, atau konfigurasi native SDK apa pun, jalankan flow tersebut di simulator atau device setelah build berhasil.

Alternatif: buat ulang iOS dengan SPM

Jika ios/ Jika folder sudah mendekati template default Capacitor, akan lebih cepat jika Anda membuatnya ulang dengan SPM daripada melakukan migrasi langsung.

Gunakan jalur ini hanya setelah Anda melakukan commit atau backup semua file native dan pengaturan signing yang diperlukan:

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

Kemudian restore file native dan pengaturan spesifik aplikasi Anda. Jalur ini memberi Anda proyek SPM yang bersih, tetapi perubahan custom di Xcode lebih mudah hilang jika Anda tidak mencatatnya terlebih dahulu.

Untuk aplikasi Capacitor baru, Capacitor 8 membuat proyek iOS dengan SPM secara default:

npx cap add ios

Anda tetap bisa menentukannya secara eksplisit:

npx cap add ios --packagemanager SPM

Bersihkan sisa CocoaPods

Setelah build aplikasi SPM selesai, hapus sisa-sisa asumsi CocoaPods dari script lokal dan CI.

Hapus langkah-langkah seperti:

pod install

Hapus juga cache yang hanya ada untuk CocoaPods:

ios/App/Pods
ios/App/Podfile.lock
Repositori spesifikasi CocoaPods
Key cache CI berdasarkan Podfile

Alur CI dasar setelah migrasi harus menginstal dependensi JavaScript, build web app, sync Capacitor, dan build dengan Xcode:

npm ci
npm run build
npx cap sync ios

Jika CI Anda masih melakukan build App.xcworkspace, perbarui ke path project atau workspace yang ada setelah migrasi. Jangan biarkan path CocoaPods lama tetap ada hanya karena job lama menggunakannya.

Pemecahan Masalah

Assistant memperingatkan adanya dependensi yang tidak kompatibel

Update dependensinya terlebih dahulu dan jalankan kembali assistant. Jika belum ada versi yang kompatibel dengan SPM, tetap gunakan CocoaPods sampai dependensi tersebut diganti atau maintainer menambahkan dukungan SPM.

Xcode tidak dapat resolve package

Reset package cache di Xcode, pastikan CapApp-SPM tersedia sebagai local package, lalu jalankan npx cap sync ios lagi.

App build lokal berhasil tapi CI gagal

Cek asumsi CocoaPods lama: pod install, Pods/ cache, Podfile.lock cache keys, atau perintah build yang mengarah ke file yang sudah dihapus .xcworkspace.

Signing atau entitlements berubah

Bandingkan target Xcode hasil migrasi dengan proyek sebelum migrasi. Kembalikan bundle identifier, team, provisioning profile, file entitlements, capabilities, dan pengaturan extension.

Checklist migrasi

Sebelum migrasi:

Buat branch baru.
Pastikan app iOS saat ini bisa di-build.
Commit state yang sedang berjalan.
Inventarisasi file native kustom dan pengaturan signing.
Perbarui dependensi native yang sudah memiliki rilis terbaru yang kompatibel dengan SPM.

Selama migrasi:

Jalankan npx cap spm-migration-assistant.
Buka proyek dengan npx cap open ios.
Tambah CapApp-SPM di Xcode jika diperlukan.
Tambah debug.xcconfig di Xcode jika diperlukan.
Atasi peringatan package.
Jalankan npx cap sync ios.

Setelah migrasi:

Build aplikasi dari Xcode.
Uji kemampuan native di simulator atau perangkat.
Hapus perintah CocoaPods dari CI.
Hapus cache khusus CocoaPods.
Verifikasi archive dan signing release.

Gunakan Capgo Skills untuk migrasi

Jika Anda menggunakan AI agent untuk migrasi, mulailah dari Skill Capgo yang open daripada prompt kosong. Skill paling berguna untuk tugas ini adalah:

capacitor-best-practices meninjau struktur app sebelum melakukan perubahan ios/.
cocoapods-to-spm merencanakan migrasi SPM dan langkah lanjutan Xcode.
capacitor-ci-cd menghapus asumsi CocoaPods dari build pipeline.
debugging-capacitor dan ios-android-logs untuk menyelidiki masalah yang hanya muncul di perangkat setelah migrasi.

Gunakan fitur ini sebelum mengubah proyek iOS agar agent dapat mengaudit file native, CI, dan kompatibilitas dependency, bukan sekadar menjalankan perintah migrasi.

Kesimpulan

Migrasi aplikasi Capacitor ke Swift Package Manager sebagian besar adalah perubahan manajemen dependency iOS. Cara paling aman adalah mulai dari branch baru, lalu jalankan npx cap spm-migration-assistant, selesaikan langkah manual di Xcode, sync kembali, dan hapus CocoaPods dari CI hanya setelah aplikasi berhasil di-build.

Jika proyek iOS Anda banyak kustomisasi, lakukan migrasi di tempat. Jika sudah mendekati template default Capacitor, membuat ulang ios/ dengan npx cap add ios --packagemanager SPM bisa jadi lebih bersih.