Build App iOS dari Windows dengan Capacitor dan Capgo Build

Membangun iOS app secara tradisional hanya punya satu cara: butuh Xcode, dan Xcode butuh macOS. Kendala ini sangat mengganggu jika seluruh tim Anda menggunakan Windows atau Linux, atau jika Anda tidak ingin repot mengelola mesin build Mac.

Kombinasi dari Capacitor (untuk membuat native iOS project) dan Build Capgo (untuk compile dan sign di cloud) memungkinkan Anda melakukan iOS build dan submit TestFlight dari workstation Windows.

Panduan ini menunjukkan workflow pragmatis yang efektif untuk tim:

Develop di Windows layaknya proyek web biasa.
Pertahankan ios/ di repo Anda (agar native state dapat direproduksi).
Jalankan cap sync secara lokal (agar web build Anda tersalin ke proyek iOS).
Trigger iOS cloud build dengan Capgo Build.

Apa yang Anda Build dan di Mana

Ada dua jenis “build” terpisah dalam aplikasi Capacitor:

Build web (JS/HTML/CSS Anda): ini dilakukan secara lokal di Windows.
Native Build (Xcode archive, signing, upload): Capgo Build melakukannya di hardware Mac via cloud.

Pemisahan ini adalah kuncinya: Capgo Build mengompilasi proyek native, tetapi ia mengharapkan aset web Anda sudah tersinkronisasi ke dalam ios/.

Prerequisites

Aplikasi Capacitor yang sudah berjalan (framework apa pun boleh).
Akun Apple Developer.
Akses App Store Connect untuk aplikasi yang ingin di-upload (untuk submisi TestFlight/App Store).
Akun Capgo dan API token Anda (CAPGO_TOKEN).

1) Buat atau Siapkan Aplikasi Capacitor Anda (Windows)

Jika Anda sudah punya web app, langsung saja ke langkah Capacitor.

Contoh dengan Vite:

bun create vite@latest my-app
cd my-app
bun install

Build harus menghasilkan static assets (untuk Vite ini dist/ secara default):

bun run build

2) Tambahkan Capacitor dan platform iOS

Instal Capacitor:

bun add @capacitor/core @capacitor/ios
bun add -d @capacitor/cli

Inisialisasi dan buat folder platform iOS:

bunx cap init
bunx cap add ios

Pada tahap ini Anda akan memiliki sebuah ios/ direktori. Commit ke git. Capgo Build mengompilasi isi ios/, jadi Anda perlu melakukan versioning agar dapat direproduksi.

3) Selalu Sync Web Assets ke iOS Sebelum Build

Setiap kali Anda mengubah web app, jalankan urutan ini di Windows:

bun run build
bunx cap sync ios

cap sync adalah yang menyalin web assets hasil build ke proyek iOS native (file yang akan dikompilasi oleh Capgo Build).

4) Instal dan Autentikasi Capgo CLI

Capgo Build dipicu melalui Capgo CLI. Dengan bun, gunakan bunx:

bunx @capgo/cli@latest login

Atau atur token Anda via env var di shell/CI:

export CAPGO_TOKEN="your_api_key_here"

5) Konfigurasi iOS Signing untuk Cloud Build

Untuk build iOS, Anda memerlukan material signing:

Sertifikat Apple Distribution (".p12) dan password-nya
Profil provisioning (.mobileprovision)
Kunci API App Store Connect (AuthKey_XXXXXX.p8) dan metadata (Key ID, Issuer ID, Team ID)

Jika Anda masih perlu membuat file ini, ikuti dokumentasi Capgo:

Kelola Kredensial (apa yang harus disimpan dan caranya)
Cara Mendapatkan Sertifikat iOS dan Provisioning Profile

Cara termudah: buat/ekspor file ini sekali saja (biasanya pakai Mac yang tersedia, rekan tim, atau sewa sekali), lalu gunakan kembali dari Windows untuk setiap build berikutnya.

Setelah file tersedia secara lokal, simpan untuk Capgo Build:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "password" \
  --provisioning-profile ./profile.mobileprovision \
  --apple-key ./AuthKey.p8 \
  --apple-key-id "KEY123" \
  --apple-issuer-id "issuer-uuid" \
  --apple-team-id "team-id"

Tips: di CI, simpan file kredensial dalam format base64 sebagai secrets, decode saat runtime, lalu jalankan build credentials save perintah.

6) Trigger iOS Build dari Windows

Dari folder aplikasi Anda:

bun run build
bunx cap sync ios
bunx @capgo/cli@latest build com.example.app --platform ios --build-mode release

Anda akan melihat log real-time di terminal. Jika key App Store Connect sudah dikonfigurasi, Capgo Build dapat mengirimkan hasil build ke TestFlight secara otomatis.

7) Iterasi Cepat: Live Updates untuk Perubahan Khusus Web

Capgo Build digunakan untuk perubahan native:

menambah/menghapus plugin Capacitor
mengubah permission native
mengubah ikon/splash
memperbarui Capacitor
perubahan Swift/Objective-C apa pun

Untuk tweak UI harian dan perbaikan JavaScript, biasanya Anda ingin Live Update (OTA), jadi Anda tidak perlu rebuild binary native setiap saat.

Workflow tim yang baik adalah:

Gunakan Live Updates untuk perubahan web yang sering.
Gunakan Capgo Build sesekali saat butuh perubahan native.

Masalah Umum di Windows (dan Solusinya)

Lupa cap sync: jika perubahan UI Anda tidak muncul di build iOS, kemungkinan Anda sudah mem-build web app tetapi belum melakukan sync ke dalam ios/.
Tidak di-commit ios/: Capgo Build mengompilasi proyek native. Jika folder tidak ada di git (atau tidak ada dalam build context), build tidak dapat mereproduksi app Anda.
Perubahan plugin tanpa rebuild native: menambah plugin adalah perubahan native; rencanakan Capgo Build setelahnya (dan pengajuan ke store).

Ringkasan

Anda tidak bisa menjalankan Xcode di Windows, tapi Anda bisa merilis app iOS dari Windows:

Bungkus web app Anda dengan Capacitor (ios/ di repo Anda).
Build aset web secara lokal, lalu cap sync.
Gunakan Capgo Build untuk kompilasi, signing, dan submit binary iOS Anda dari CLI.

Lanjutkan dari Build an iOS App from Windows dengan Capacitor dan Capgo Build

Jika Anda menggunakan Build App iOS dari Windows dengan Capacitor dan Capgo Build untuk merencanakan otomatisasi CI/CD, hubungkan dengan CI/CD Capgo untuk workflow produk di Capgo CI/CD, Capgo Native Build untuk workflow produk di Capgo Native Builds, Integrasi Capgo untuk alur kerja produk di Integrasi Capgo, Integrasi CI/CD untuk detail implementasi di Integrasi CI/CD, dan Integrasi GitHub Actions untuk detail implementasi di Integrasi GitHub Actions.