Come personalizzare i build script con Capacitor CLI

Capacitor CLI ti permette di personalizzare il processo di build della tua app per iOS, Android e web. Modificando gli script di build, puoi:

• Accelerare gli update: Pubblicare modifiche istantaneamente senza i ritardi degli app store.
• Controllare i deployment: Esegui il rollback degli update o indirizza gruppi specifici di utenti.
• Proteggi la tua app: usa la crittografia per proteggere gli update.
• Ottimizza le build: adatta le impostazioni alle esigenze della piattaforma.

Panoramica delle funzioni principali:

• File di configurazione: Usa capacitor.config.json e package.json per gestire le impostazioni di build.
• Script personalizzati: aggiungi task prebuild e postbuild per l'automazione.
• Build Hooks: Esegui code durante fasi specifiche del processo di build.
• Variabili d'ambienteSemplifica i build per diversi ambienti con .env file.

Capgo, uno strumento di deployment che potenzia questo processo con aggiornamenti automatici, il tracciamento delle versioni e l'ottimizzazione globale delle performance. Continua a leggere per scoprire come configurare e personalizzare i tuoi build script per la massima efficienza.

Ti presentiamo Capacitor Configura

Processo di build predefinito in Capacitor

Capire come Capacitor gestisce il suo processo di build predefinito è fondamentale per personalizzarlo efficacemente. Di seguito analizzeremo il processo di build di Capacitor CLI e i suoi file di configurazione principali.

Step di build standard

Capacitor utilizza un processo sequenziale per trasformare la tua web app in build specifiche per ogni piattaforma. Ecco cosa avviene durante il processo di build predefinito:

File di configurazione principali

Due file di configurazione definiscono come Capacitor gestisce le build:

capacitor.config.json
Questo è il file di configurazione principale del tuo progetto Capacitor. Imposta i parametri chiave per le build:

{
  "appId": "com.example.app",
  "appName": "MyApp",
  "webDir": "dist",
  "bundledWebRuntime": false,
  "plugins": {
    "SplashScreen": {
      "launchShowDuration": 3000
    }
  }
}

• appId: Un identificatore univoco per la tua app.
• appName: Il nome della tua app.
• webDir: Specifica dove Capacitor deve cercare gli asset web (es. dist).
• plugins: Ti permette di configurare impostazioni specifiche dei plugin, come le opzioni di SplashScreen.

package.json
Questo file include gli script di build e le dipendenze che influenzano il processo di build:

{
  "scripts": {
    "build": "npm run build:web && cap sync",
    "build:web": "vite build",
    "cap:build": "cap build"
  }
}

• Il webDir impostazione in capacitor.config.json indica a Capacitor dove trovare gli asset web compilati da includere nelle build native.
• Dopo aver apportato modifiche a capacitor.config.json, devi eseguire cap sync per assicurarti che i tuoi progetti nativi siano aggiornati.

Successivamente, vedremo come modificare queste impostazioni per personalizzare ulteriormente le tue build.

Modifica degli script di build

Puoi ottimizzare il processo di build predefinito di Capacitor per adattarlo meglio alle tue esigenze. Ecco come:

Impostazioni del file di configurazione

Puoi regolare il processo di build modificando il file capacitor.config.json file. Ecco un esempio di configurazione:

{
  "appId": "com.example.app",
  "webDir": "www",
  "server": {
    "hostname": "localhost",
    "androidScheme": "https",
    "iosScheme": "https",
    "allowNavigation": ["*.example.com"]
  },
  "android": {
    "buildOptions": {
      "keystorePath": "release.keystore",
      "keystorePassword": "mypassword",
      "keystoreAlias": "release",
      "keystoreAliasPassword": "mypassword"
    }
  },
  "ios": {
    "scheme": "App",
    "automaticProvisioning": true
  }
}

Ecco alcune impostazioni chiave che puoi modificare:

• webDir: Specifica dove si trovano i tuoi asset web compilati.
• server: Configura il server di sviluppo, inclusi hostname e permessi di navigazione.
• android/ios: Consente impostazioni di build specifiche per piattaforma, come i dettagli del keystore per Android o le opzioni di provisioning per iOS.

Creazione di script NPM

Per ottimizzare il tuo workflow, aggiungi script NPM personalizzati al tuo package.json file. Ecco un esempio:

{
  "scripts": {
    "prebuild": "node ./scripts/prepare-env.js",
    "build": "npm run build:web && cap sync",
    "build:web": "vite build",
    "build:ios": "cap build ios --release",
    "build:android": "cap build android --release",
    "postbuild": "node ./scripts/notify-completion.js"
  }
}

• prebuild e postbuild: Usali per task come configurare l'ambiente o inviare notifiche al termine del build.
• build:platform: Comandi specifici per la build di app Android o iOS.

Puoi spingere l'automazione ancora oltre aggiungendo i build hooks.

Configurazione build hooks

Per un controllo più avanzato, usa i build hooks per eseguire code personalizzati in punti specifici del processo di build. Ecco un esempio in capacitor.config.ts:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  plugins: {
    CapacitorHooks: {
      beforeBuild: async () => {
        console.log('Running pre-build tasks...');
        // Add your pre-build tasks here
      },
      afterBuild: async () => {
        console.log('Running post-build tasks...');
        // Add your post-build tasks here
      }
    }
  }
};

export default config;

Con i build hooks puoi:

• Validare i requisiti prima dell'inizio del build
• Trasformare gli asset durante il processo
• Inviare notifiche in punti chiave
• Aggiornare automaticamente i numeri di versione
• Esegui test automatici senza interruzioni

Questo approccio ti offre maggiore flessibilità e controllo sull'intero ciclo di vita del build.

Personalizzazione avanzata del build

Nei progetti più grandi, ottimizzare il processo di build fa una grande differenza. Ecco come gestire efficacemente le build specifiche per ambiente e le personalizzazioni per piattaforma.

Variabili d'ambiente

Configura le variabili d'ambiente creando file separati .env file per ogni ambiente:

• .env.development
• .env.staging
• .env.production

Quindi, configura lo script di build per caricare il file appropriato in base all'ambiente:

import { defineConfig } from '@capacitor/cli';

export default defineConfig({
  ios: {
    buildConfig: {
      environment: process.env.BUILD_ENV || 'development',
      configurations: {
        development: {
          signing: {
            debug: true,
            automaticProvisioning: true
          }
        },
        production: {
          signing: {
            release: true,
            provisioningProfile: 'dist/profile.mobileprovision'
          }
        }
      }
    }
  }
});

Puoi ulteriormente regolare queste impostazioni per soddisfare i requisiti specifici della piattaforma.

Build specifiche per piattaforma

Per personalizzare le build per Android e iOS, usa la seguente struttura:

const platformConfig = {
  android: {
    buildType: process.env.BUILD_TYPE || 'debug',
    keystoreConfig: {
      path: process.env.KEYSTORE_PATH,
      password: process.env.KEYSTORE_PASSWORD,
      alias: process.env.KEYSTORE_ALIAS
    }
  },
  ios: {
    scheme: process.env.APP_SCHEME || 'App',
    xcodePreferences: {
      automaticSigning: false,
      developmentTeam: process.env.DEVELOPMENT_TEAM
    }
  }
};

Queste configurazioni ti permettono di adattare le build a ciascuna piattaforma, garantendo deploy più fluidi.

Altri suggerimenti per ottimizzare le tue build:

• Usare gli update parziali per risparmiare tempo nei deployment
• Configurare l'error tracking per identificare subito i problemi
• Creare sistemi di channel per le versioni beta
• Abilitare la crittografia end-to-end per una distribuzione sicura

Se abbinate a strumenti come Capgo per analytics e update sicuri, queste tecniche ti danno più controllo sul processo di deployment [1].

Problemi e soluzioni con i build script

Quando lavori con configurazioni di build personalizzate, risolvere gli errori rapidamente è fondamentale per mantenere fluido il processo di build.

Risolvi gli errori comuni

Molti problemi negli script di build derivano dalla configurazione dell'ambiente o dalle dipendenze. Ecco come risolvere i casi più comuni:

Variabili d'ambiente mancanti

Se riscontri un errore di questo tipo:

error: Cannot find environment configuration for BUILD_ENV

Puoi risolverlo creando un file .env.local nella directory root del progetto. Ecco un esempio:

BUILD_ENV=development
CAPACITOR_PLATFORM=ios
BUILD_TYPE=debug

Errori di build specifici per piattaforma

Per errori di firma Android, usa questo comando:

npx cap build android --keystorePassword=$KEYSTORE_PASSWORD --keystoreAlias=$KEYSTORE_ALIAS

Per problemi ai provisioning profile iOS, prova così:

npx cap build ios --configuration=release --type=development

Dopo aver applicato le correzioni, assicurati che le modifiche siano stabili eseguendo test di build approfonditi.

Testa gli script di build

Una volta risolti gli errori, valida i tuoi build script con questi passaggi:

• Verifica automatica: Esegui i comandi principali per confermare che il processo di build funzioni come previsto.

npm run build
npx cap sync
npx cap copy

• Validazione ambiente: Controlla che non manchino variabili d'ambiente prima di avviare la build.

const requiredVars = ['BUILD_ENV', 'KEYSTORE_PATH'];
requiredVars.forEach(varName => {
  if (!process.env[varName]) {
    throw new Error(`Missing required env var: ${varName}`);
  }
});

• Debug dei build script: Aggiungi script dettagliati per intercettare potenziali problemi durante la build.

{
  "scripts": {
    "build:debug": "NODE_ENV=development npx cap build --verbose",
    "build:release": "NODE_ENV=production npx cap build --verbose"
  }
}

Altri consigli per i test:

• Usa Docker container per isolare le build.
• Valida i file di configurazione prima di avviare il processo.
• Testa con diverse Node.js versioni.
• Confirm platform-specific requirements are met.
• Monitora le performance di build per possibili miglioramenti.

Capgo Funzionalità di build

Capgo porta gli script di build al livello successivo con il deployment automatizzato, migliorando l'efficienza e semplificando il processo.

Update rapidi dell'app

Le prestazioni di aggiornamento di Capgo sono impressionanti:

• 95% degli utenti attivi ricevi aggiornamenti entro 24 ore.
• 82% di tasso di successo per la distribuzione degli aggiornamenti a livello globale.
• Un tempo di risposta medio di API di 434ms a livello globale.

La piattaforma utilizza aggiornamenti parziali, il che significa che vengono scaricati solo i cambiamenti. Questo approccio riduce l'utilizzo della banda e accelera il processo di aggiornamento. Inoltre, l'intero processo di build è completamente automatizzato, risparmiando tempo e fatica.

Automazione delle build

Capgo funziona perfettamente con le principali piattaforme CI/CD, offrendo una varietà di integrazioni:

Configurare una build automatizzata costa in genere circa 300 $ al mese, molto più economico rispetto alle soluzioni tradizionali che possono arrivare a $6.000 all'anno.

Standard di sicurezza

Capgo punta sulla sicurezza con un framework robusto che include:

• Crittografia end-to-end per i pacchetti di update.
• Gestione sicura delle chiavi.
• Conformità alle linee guida di Apple e Google.

Funzionalità di Version Control

• Opzioni di rollback istantaneo.
• Tracciamento delle versioni di deployment.
• Gestione dei canali di update per rilasci graduali.

Questo framework di sicurezza è stato testato rigorosamente su centinaia di applicazioni enterprise. Per i team che richiedono sicurezza extra, Capgo offre anche soluzioni self-hosted con configurazioni personalizzabili.

Il sistema di canali di Capgo rende la distribuzione degli aggiornamenti flessibile. Gli sviluppatori possono indirizzare gruppi specifici di utenti con versioni diverse, ideale per test beta o rollouts graduali.

Riassunto

Panoramica dei passaggi di build

Gli script di build personalizzati consentono deploy automatizzati e coerenti sfruttando build hooks, variabili d'ambiente e comandi specifici per piattaforma. Questi processi creano una solida base per i miglioramenti del deploy resi possibili da Capgo.

Vantaggi di Capgo

Capgo semplifica il deployment, avendo già consegnato oltre 23,5 milioni di aggiornamenti su 750 app in produzione [1]. Il suo sistema di aggiornamenti parziali riduce sia l'uso della banda che i tempi di deployment.

La piattaforma offre aggiornamenti rapidi, ottimizzazione delle prestazioni globale, crittografia end-to-end per la sicurezza e un sistema di distribuzione flessibile basato su canali. Questa configurazione supporta aggiornamenti mirati, test beta e conformità alle linee guida degli app store, mantenendo al contempo un solido framework di sicurezza.

Continua da Come personalizzare gli script di build con Capacitor CLI

Se stai usando Come personalizzare i build script con Capacitor CLI 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.