Trasforma la tua PW in un'applicazione nativa con Capacitor

Introduzione

Hai già un'app PWA. Funziona nei browser, ha un manifesto e forse utilizza un worker di servizio per il supporto offline. Se ora hai bisogno di distribuzione negli store, API di dispositivo nativo o un funnel di onboarding migliore, migrare a un'app Capacitor è spesso più veloce che ricreare il front-end.

Il maggior vantaggio è che conservi quasi tutto il tuo web code esistente. In molti casi, hai bisogno solo di:

costruisci asset web di produzione,
inizia Capacitor con le impostazioni giuste webDir,
aggiungi progetti iOS e Android,
Esegui plugin nativi solo dove necessario.

Se il tuo PWA ha percorsi puliti e logica di componente, ciò può richiedere solo poche ore.

Prerequisiti

Tempo stimato: 2-5 ore, a seconda delle funzionalità specifiche della piattaforma.

Node.js 18+ con Bun
La tua sorgente PWA esistente code (React, Vue, Angular, Svelte, ecc.)
Xcode (solo per iOS, macOS)
Android Studio per Android
se hai intenzione di pubblicare iOS, necessiti di un account di sviluppatore Apple
se intendi distribuire Android, necessiti di un account di sviluppatore Google Play

Passo 1: Controlla la tua PWA prima di avvolgerla in nativo

Prima di eseguire bunx cap init, verifica che la tua app web sia pronta per la produzione:

Assicurati che la tua PWA abbia uno script di build di produzione (ad esempio bun run build).
Conferma che il tuo cartello di output web sia deterministico (spesso dist, buildo out).
Elimina i redirect assoluti hardcodati che assumono un contesto browser-only.
Verifica il comportamento del worker di servizio per assicurarti che sia compatibile con i WebViews mobili:
- Mantieni il supporto offline se aiuta i tuoi utenti.
- Evita le API del browser che non sono disponibili nella vista web incorporata.
Conferma le sollecitazioni di installazione PWA e l'interfaccia utente specifica del browser sono ancora pertinenti. In un'app Capacitor, le sollecitazioni di installazione dell'app sono di solito non necessarie.

Passo 2: Adatta i comportamenti del browser solo

Mantieni la tua interfaccia utente dell'app ma blocca la logica del browser solo.

Utilizza un controllo di piattaforma semplice intorno alle sollecitazioni di installazione e push:

import { Capacitor } from '@capacitor/core'

const isNative = Capacitor.isNativePlatform()

function registerInstallPrompt() {
  if (isNative) return
  // existing browser-only install or Web Push code
}

Ciò evita la logica del browser solo che si attiva all'interno del contenitore nativo.

Passo 3: Inizializza Capacitor nella cartella PWA

Dalla tua cartella PWA esistente:

bun add @capacitor/core
bun add -D @capacitor/cli

Esegui Capacitor init con il nome dell'app, l'ID bundle e il percorso di output web:

bunx cap init MyPWAApp com.example.my-pwa-app --web-dir dist

Se il tuo cartella di build è build (Create React App) o out (Next.js static export), sostituisci dist.

Aggiungi una configurazione di base Capacitor:

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

const config: CapacitorConfig = {
  appId: 'com.example.my-pwa-app',
  appName: 'MyPWAApp',
  webDir: 'dist',
  server: {
    iosScheme: 'https',
  },
}

export default config

Passo 4: Aggiungi piattaforme native

Installa pacchetti nativi di base e genera cartelle del progetto:

bun add @capacitor/ios @capacitor/android
bunx cap add ios
bunx cap add android

In questo punto Capacitor ha creato ios/ e android/ cartelle. La sincronizzazione copierà i tuoi asset web costruiti in entrambe le piattaforme.

Passo 5: Costruisci il tuo'app web e sincronizza

Costruisci la PWA e sincronizza gli asset web:

bun run build
bunx cap sync

Ora apri i progetti nativi:

bunx cap open ios
bunx cap open android

Da Xcode o Android Studio, collega un dispositivo o un emulatore e esegui.

Passo 6: Miglioramenti nativi dopo la migrazione

Questo è dove sostituisci le funzionalità esclusivamente web con API native dove necessario:

Notifiche push -> @capacitor/push-notifications
Archiviazione chiave/valore sicura -> @capacitor/preferences
Camera / media -> @capacitor/camera
Autenticazione biometrica -> @capacitor-community/native-biometric (o plugin di scelta)

Per ogni nuovo plugin nativo:

Installa il pacchetto del plugin
Configura le impostazioni specifiche del plugin
Esegui:

bunx cap sync

Riavvia e esegui nuovamente.

Passo 7: Verifica della parità con l'app store

Prima della sottoscrizione:

Verifica collegamenti profondi e routing (/ e percorsi profondi) su entrambe le piattaforme.
Verifica che la barra dello stato, le aree sicure e l'orientamento siano corretti.
Elimina i metadati web non utilizzati che confliggono con il comportamento dell'app (ad esempio, le richieste di installazione).
Mantieni le impostazioni di sicurezza e privacy dell'app coerenti con la tua politica.
Aggiungi icone/splash per ogni piattaforma.

Se la tua app utilizza aggiornamenti OTA, sincronizza il tuo pipeline di rilascio con una strategia di aggiornamento sicura per le piattaforme native e considera Capgo per un rollout controllato e rollback.

Elenco di controllo finale

Il build dell'app web è pulito (bun run build)
Capacitor inizializzato con le impostazioni corrette webDir
bunx cap add ios Ecco i vantaggi di __CAPGO_KEEP_0__: bunx cap add android Ecco i vantaggi di __CAPGO_KEEP_0__:
Le app native funzionano su dispositivi reali
I percorsi browser-only di code sono limitati per comportamento nativo
I canali di aggiornamento e gli asset di negozio sono configurati

Hai già fatto la maggior parte del lavoro duro quando hai costruito la tua PWA. Avvolgendola con Capacitor ti dà:

La distribuzione nel negozio
Accesso agli API nativi
Una iterazione più veloce senza una completa riscrittura di code
Un unico percorso di distribuzione per team web e mobili

Inizia da questo flusso, poi iterare native-by-native in base alle analisi e ai feedback degli utenti

Continua da Transform Your PWA to a Native App con Capacitor

If sei stai utilizzando Trasforma la tua PWA in un'app nativa con Capacitor per pianificare la migrazione e le operazioni aziendali, connettilo con Capgo Enterprise per il workflow del prodotto in Capgo Enterprise, Alternative per plugin di Ionic Enterprise per il workflow del prodotto in Alternative per plugin di Ionic Enterprise, Capgo Alternatives per il workflow del prodotto in Capgo Alternatives, Consulenza Capgo per il workflow del prodotto in Consulenza Capgo, e Sostegno Premium Capgo For il flusso di lavoro del prodotto in Capgo Supporto Premium.

Trasforma la tua App PWA in un'app nativa con Capacitor