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

Sviluppare un'app iOS di solito significa una cosa: serve Xcode, e Xcode richiede macOS. Questo è un limite fastidioso se il tuo team usa Windows o Linux, o se non vuoi gestire una macchina dedicata per il build su Mac.

La combinazione di Capacitor (per generare il progetto iOS nativo) e Build con Capgo (per compilarla e firmarla 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 (così lo stato nativo è riproducibile).
Esegui cap sync localmente (così la tua web build viene copiata nel progetto iOS).
Avvia una build iOS nel cloud con Capgo Build.

What You Actually Build Where

Ci sono due “build” separate in un'app Capacitor:

Build web (il tuo JS/HTML/CSS): lo fai localmente su Windows.
Native Build (archiviazione Xcode, signing, 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 asset web 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 TestFlight/invio all'App Store).
Il tuo account Capgo e il token API (CAPGO_TOKEN).

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

Se hai già un'app web, 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 il contenuto ios/, quindi è fondamentale 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

Il build di Capgo viene attivato tramite Capgo CLI. Con bun, usa bunx:

bunx @capgo/cli@latest login

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

export CAPGO_TOKEN="your_api_key_here"

5) Configura la firma iOS per i Cloud Build

Per buildare iOS hai bisogno dei certificati 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 strada più semplice è: crea/esporta questi file una sola volta (usando un Mac, un collega o un noleggio temporaneo), poi riutilizzali da Windows per ogni build successiva.

Una volta salvati i file localmente, conservali 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"

Tip: in CI, salva i file delle credenziali 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 piccoli tweak alla UI e fix JavaScript quotidiani, di solito conviene usare Live Update (OTA), così non devi ricostruire il binario nativo ogni volta.

Un buon workflow per il team è:

Usa Live Updates per i cambiamenti web frequenti.
Usa Capgo Build occasionalmente 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/.
Non committato ios/: Capgo Build compila il progetto nativo. Se la cartella non è in git (o non è nel tuo build context), la build non potrà riprodurre la tua app.
Modifiche ai plugin senza rebuild nativa: aggiungere un plugin è una modifica nativa; pianifica una Capgo Build (e l'invio agli store) subito dopo.

Riassunto

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

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

Continua la guida: Build an iOS App from Windows con Capacitor e Capgo Build

Se stai usando Build an iOS App from Windows con Capacitor e Capgo Build per pianificare l'automazione CI/CD, connettilo a CI/CD di Capgo per il workflow di 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 Capgo Integrazioni, Integrazione CI/CD per i dettagli implementativi dell'integrazione CI/CD, e Integrazione GitHub Actions per i dettagli implementativi dell'integrazione con GitHub Actions.