Transformez votre PWA en application mobile native avec Capacitor

Introduction

Vous avez déjà une application web progressive. Elle fonctionne dans les navigateurs, possède un manifest et utilise peut-être un service worker pour le support hors ligne. Si vous avez maintenant besoin de la distribution dans les magasins d'applications, des API de dispositif natif ou d'un meilleur canal d'abord, la migration vers une application Capacitor est généralement plus rapide que la refonte de votre interface de front-end.

L'avantage le plus important est que vous conservez presque tout votre code web existant de code. Dans la plupart des cas, vous n'avez besoin que de :

produire des actifs web de production,
initialisez Capacitor avec les bonnes webDir,
ajoutez des projets iOS et Android,
et connectez les plugins natives uniquement là où cela est nécessaire.

Si votre PWA a des routes propres et une logique de composant, cela peut prendre seulement quelques heures.

Prérequis

Temps estimé: 2-5 heures, en fonction des fonctionnalités spécifiques au plateau.

Node.js 18+ avec Bun
Votre source PWA existante code (React, Vue, Angular, Svelte, etc.)
Xcode (pour iOS, macOS uniquement)
Android Studio (pour Android)
Si vous prévoyez de publier sur iOS, vous aurez besoin d'un compte développeur Apple.
Si vous prévoyez de distribuer votre application Android sur Google Play, vous aurez besoin d'un compte développeur Google Play.

Étape 1 : Vérifiez votre PWA avant de l'entourer de native :

Avant de lancer votre application, bunx cap initVérifiez que votre application web est prête pour la production :

Assurez-vous que votre PWA a un script de build de production (par exemple, bun run build).
Confirmez que votre dossier de sortie web est déterministe (souvent dist, buildSupprimez les redirigements absolus codés en dur qui supposent un contexte de navigateur uniquement. out).
Supprimez les redirigements absolus codés en dur qui supposent un contexte de navigateur uniquement.
Vérifiez que le comportement du worker de service est compatible avec les vues Web mobiles :
- Conservez le support hors ligne si cela aide vos utilisateurs.
- Évitez les API de navigateur uniquement qui sont inaccessibles dans la vue web intégrée.
Confirmez les invites d'installation de PWA et les UX spécifiques au navigateur qui ont toujours du sens. Dans une application Capacitor, les invites d'installation d'applications sont généralement inutiles.

Étape 2 : Adapter les comportements spécifiques au navigateur

Conservez votre interface utilisateur mais bloquez la logique spécifique au navigateur.

Utilisez une vérification de plateforme simple autour des invites d'installation et des invites de push :

import { Capacitor } from '@capacitor/core'

const isNative = Capacitor.isNativePlatform()

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

Cela évite la logique spécifique au navigateur qui se déclenche à l'intérieur du conteneur natif.

Étape 3 : Initialiser Capacitor dans votre dossier PWA

À partir de votre dossier PWA existant :

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

Exécutez Capacitor init avec votre nom d'application, votre ID de bundle et votre répertoire de sortie web :

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

Si votre dossier de build est build (Créer une application React) ou out (export statique de Next.js), remplacez dist.

Ajoutez une configuration de 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

Étape 4 : Ajoutez les plateformes natives

Installez les packages natives de base et générez les dossiers du projet :

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

À ce stade, Capacitor a créé ios/ et android/ dossiers. La synchronisation copiera vos actifs web construits dans les deux plateformes.

Étape 5 : Construisez votre application web et synchronisez

Construirez la PWA et synchronisez les actifs web :

bun run build
bunx cap sync

Ouvrez maintenant les projets natives :

bunx cap open ios
bunx cap open android

À partir de Xcode ou d'Android Studio, connectez un appareil ou un émulateur et exécutez.

Étape 6 : Améliorations natives après migration

C'est ici que vous remplacez les fonctionnalités web uniquement par des API natives là où cela est nécessaire :

Notifications push -> @capacitor/push-notifications
Stockage clé/valeur sécurisé -> @capacitor/preferences
Caméra / médias -> @capacitor/camera
Authentification biométrique -> @capacitor-community/native-biometric (ou plugin de votre choix)

Pour chaque nouveau plugin natif :

Installez le package du plugin
Configurez les paramètres spécifiques au plugin
Exécutez :

bunx cap sync

Rebâtissez et exécutez à nouveau.

Étape 7 : Vérification de la parité des magasins d'applications

Avant la soumission :

Testez les liens profonds et la navigation (/ et les routes profondes) sur les deux plateformes.
Vérifiez que la barre d'état, les zones de sécurité et l'orientation sont corrects.
Supprimez les métadonnées web non utilisées qui entrent en conflit avec le comportement de l'application (par exemple, les invites d'installation).
Conservez les paramètres de sécurité et de confidentialité de l'application cohérents avec votre politique.
Ajoutez les icônes et les atouts de splash pour chaque plateforme.

Si votre application utilise des mises à jour OTA, associez votre pipeline de publication à une stratégie d'update native et considérez Capgo pour un lancement contrôlé et un roulage de retour.

Vérification finale

Les builds d'applications web se déroulent proprement (bun run build)
Capacitor initialisé avec les bonnes webDir
bunx cap add ios et bunx cap add android les applications natives fonctionnent sur des appareils réels
Les chemins __CAPGO_KEEP_0__ uniques pour les navigateurs sont bloqués pour le comportement natif
Browser-only code paths are gated for native behavior
Vous avez déjà fait la majeure partie du travail dur lors de la création de votre PWA. L'ajout de __CAPGO_KEEP_0__ donne :

You already did most of the hard work when building your PWA. Wrapping it with Capacitor gives you: