Crea un'app iOS da Windows con Capacitor e Capgo Build

Creare un'app iOS tradizionalmente significa una cosa sola: serve Xcode, e Xcode significa macOS. Questo vincolo è fastidioso se l'intero team usa Windows o Linux, o se semplicemente non si vuole mantenere una macchina di build Mac.

La combinazione di Capacitor (per generare il progetto iOS nativo) e Build Capgo (per compilare e firmare nel cloud) ti permette di fare build iOS e invii a TestFlight da una workstation Windows.

Questa guida mostra un workflow pragmatico che funziona bene nei team:

Sviluppa su Windows come un normale progetto web.
Mantieni ios/ nel tuo repo (per rendere riproducibile lo stato nativo).
Esegui cap sync localmente (così la tua web build viene copiata nel progetto iOS).
Avvia una build iOS nel cloud con Capgo Build.

Cosa buildi davvero e dove

Ci sono due "build" separate in un'app Capacitor:

Build web (il tuo JS/HTML/CSS): lo fai in locale su Windows.
Native Build (archivio Xcode, firma, upload): Capgo Build lo fa su hardware Mac nel cloud.

Questa separazione è la chiave: Capgo Build compila il progetto nativo, ma si aspetta che i tuoi web asset siano già sincronizzati in ios/.

Prerequisiti

Un'app Capacitor funzionante (qualsiasi framework va bene).
Un account Apple Developer.
Accesso ad App Store Connect per l'app che vuoi caricare (per l'invio a TestFlight/App Store).
Il tuo account Capgo e il token API (CAPGO_TOKEN).

1) Crea o prepara la tua app Capacitor (Windows)

Se hai già una web app, passa direttamente ai passaggi Capacitor.

Esempio con Vite:

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

La build deve produrre asset statici (per Vite si tratta di dist/ di default):

bun run build

2) Aggiungi Capacitor e la piattaforma iOS

Installa Capacitor:

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

Inizializza e crea la cartella della piattaforma iOS:

bunx cap init
bunx cap add ios

A questo punto avrai una ios/ directory. Effettua il commit su git. Capgo Build compila ciò che contiene ios/, quindi è importante che sia versionato e riproducibile.

3) Sincronizza sempre gli asset web in iOS prima della build

Ogni volta che modifichi la tua web app, esegui questa sequenza su Windows:

bun run build
bunx cap sync ios

cap sync è ciò che copia i tuoi asset web compilati nel progetto iOS nativo (i file che Capgo Build compilerà effettivamente).

4) Installa e autentica la Capgo CLI

Capgo si attiva tramite Capgo CLI. Con bun, usa bunx:

bunx @capgo/cli@latest login

Oppure imposta il token tramite variabile d'ambiente nel tuo shell/CI:

export CAPGO_TOKEN="your_api_key_here"

5) Configura la firma iOS per i Cloud Build

Per fare il build iOS ti serve il materiale di firma:

Certificato Apple Distribution (.p12) e la relativa password
Profilo di provisioning (.mobileprovision)
Chiave API di App Store Connect (AuthKey_XXXXXX.p8) e i metadati (Key ID, Issuer ID, Team ID)

Se devi ancora generare questi file, segui la documentazione Capgo:

Gestione credenziali (cosa salvare e come)
Come ottenere certificati e provisioning profile iOS

La via più semplice è: crearli/esportarli una volta (spesso usando qualsiasi Mac disponibile, un collega o un noleggio una tantum), poi riutilizzarli da Windows per ogni build successiva.

Una volta ottenuti i file localmente, salvali per 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"

Suggerimento: in CI, salva i file delle credenziali codificati in base64 come secret, decodificali a runtime e poi esegui lo stesso build credentials save comando.

6) Avvia una build iOS da Windows

Dalla cartella della tua app:

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

Vedrai i log in tempo reale nel terminale. Se la tua chiave App Store Connect è configurata, Capgo Build può inviare automaticamente la build risultante su TestFlight.

7) Iterazione rapida: Live Updates per modifiche solo web

Capgo Build serve per le modifiche native:

aggiungere/rimuovere plugin Capacitor
modificare i permessi nativi
cambiare icone/splash
aggiornare Capacitor
modifiche a Swift/Objective-C

Per i tweak quotidiani alla UI e i fix JavaScript, in genere conviene Live Update (OTA), così da non dover ricostruire il binario nativo ogni volta.

Un buon workflow di team è:

Usa Live Updates per le modifiche web frequenti.
Usa Capgo Build ogni tanto, quando servono modifiche native.

Errori comuni su Windows (e come risolverli)

Dimenticare cap sync: se le modifiche alla UI non appaiono nella build iOS, probabilmente hai buildato la web app ma non l'hai sincronizzata in ios/.
Commit mancante ios/: Capgo Build compila il progetto nativo. Se la cartella non è in git (o non è nel contesto di build), la build non può riprodurre la tua app.
Modifiche ai plugin senza rebuild nativo: aggiungere un plugin è una modifica nativa; pianifica un run di Capgo Build (e un invio allo store) successivamente.

Riassunto

Non puoi eseguire Xcode su Windows, ma può pubblica app iOS da Windows:

Avvolgi la tua web app con Capacitor (ios/ nel tuo repo).
Compila gli asset web localmente, poi cap sync.
Usa Capgo Build per compilare, firmare e inviare il tuo binario iOS da CLI.

Continua a leggere: Creare un'app iOS da Windows con Capacitor e Capgo Build

Se stai usando Crea un'app iOS da Windows con Capacitor e Capgo Build per pianificare l'automazione CI/CD e connetterla a CI/CD con Capgo per il workflow del prodotto in Capgo CI/CD, Capgo Native Build per il workflow di prodotto in Capgo Native Builds, Integrazioni Capgo per il workflow di prodotto in Integrazioni Capgo, Integrazione CI/CD per i dettagli implementativi in CI/CD Integration, e Integrazione GitHub Actions per i dettagli implementativi in GitHub Actions Integration.