Passer au contenu
Capgo - Live Updates for Capacitor Apps Capgo

Commencer

  1. Installez le package

    Fenêtre de terminal
    npm i @capgo/capacitor-live-reload

  2. Synchronisation avec les projets natifs

    Fenêtre de terminal
    npx cap sync

Configuration

Section titled “Configuration”

Configurez votre serveur de développement Vite pour qu’il fonctionne avec le rechargement en direct. Vous devez :

  1. Désactivez le client HMR intégré
  2. Transférer les événements de rechargement sur un point de terminaison WebSocket dédié

Utilisation

Section titled “Utilisation”
import { LiveReload } from '@capgo/capacitor-live-reload';


// Configure the dev server
await LiveReload.configureServer({
  url: 'http://localhost:5173',
  websocketPath: '/capgo-livereload',
  autoReconnect: true,
  reconnectInterval: 2000
});


// Connect to the dev server
await LiveReload.connect();


// Listen for reload events
LiveReload.addListener('reloadEvent', (event) => {
  console.log('Reload event:', event);
  if (event.type === 'full-reload') {
    console.log('Full page reload triggered');
  } else if (event.type === 'file-update') {
    console.log('File updated:', event.file);
  }
});


// Listen for connection status changes
LiveReload.addListener('statusChange', (status) => {
  console.log('Connection status:', status.connected);
  console.log('Server URL:', status.url);
});

API Référence

Section titled “API Référence”

configurer le serveur (options)

Section titled “configurer le serveur (options)”

Stockez les paramètres du serveur de développement distant pour les connexions ultérieures.

const status = await LiveReload.configureServer({
  url: 'http://192.168.1.100:5173',
  websocketPath: '/capgo-livereload',
  headers: {
    'Authorization': 'Bearer token'
  },
  autoReconnect: true,
  reconnectInterval: 2000
});

Paramètres :

  • url (string) : URL de base du serveur de développement (par exemple, http://dev.local:5173)
  • websocketPath (chaîne, facultatif) : remplacement du chemin WebSocket (par défaut : /ws)
  • headers (Record<string, string>, facultatif) : en-têtes supplémentaires pour la connexion WebSocket
  • autoReconnect (booléen, facultatif) : Reconnexion automatique en cas de déconnexion (par défaut : true)
  • reconnectInterval (numéro, facultatif) : délai entre les tentatives de reconnexion en ms (par défaut : 2000)

Renvoie : LiveReloadStatus avec informations de connexion

connecter()

Section titled “connecter()”

Établissez une connexion WebSocket si elle n’est pas déjà active.

const status = await LiveReload.connect();
console.log('Connected:', status.connected);

Renvoie : État actuel de la connexion

déconnexion()

Section titled “déconnexion()”

Fermez la connexion WebSocket actuelle et désactivez la reconnexion automatique.

await LiveReload.disconnect();

getStatus()

Section titled “getStatus()”

Obtenez l’état actuel de la connexion.

const status = await LiveReload.getStatus();
console.log('Connected:', status.connected);
console.log('URL:', status.url);

recharger()

Section titled “recharger()”

Déclenchez manuellement un rechargement complet de Capacitor WebView.

await LiveReload.reload();

reloadFichier (options)

Section titled “reloadFichier (options)”

Rechargez un seul fichier/module (revient au rechargement complet s’il n’est pas pris en charge).

await LiveReload.reloadFile({
  path: '/src/components/MyComponent.tsx',
  hash: 'abc123'
});

addListener(‘reloadEvent’, rappel)

Section titled “addListener(‘reloadEvent’, rappel)”

Écoutez les événements de rechargement entrants du serveur.

const handle = await LiveReload.addListener('reloadEvent', (event) => {
  switch (event.type) {
    case 'full-reload':
      console.log('Full reload requested');
      break;
    case 'file-update':
      console.log('File updated:', event.file?.path);
      break;
    case 'error':
      console.error('Error:', event.message);
      break;
  }
});


// Remove listener when done
await handle.remove();

addListener(‘statusChange’, rappel)

Section titled “addListener(‘statusChange’, rappel)”

Écoutez les changements d’état des sockets.

await LiveReload.addListener('statusChange', (status) => {
  console.log(status.connected ? 'Connected' : 'Disconnected');
});

supprimerAllListeners()

Section titled “supprimerAllListeners()”

Supprimez tous les auditeurs enregistrés.

await LiveReload.removeAllListeners();

Exemple complet

Section titled “Exemple complet”
import { LiveReload } from '@capgo/capacitor-live-reload';


export class DevServer {
  private connected = false;


  async initialize() {
    // Only enable in development
    if (process.env.NODE_ENV !== 'development') {
      return;
    }


    try {
      // Configure server
      await LiveReload.configureServer({
        url: 'http://192.168.1.100:5173',
        websocketPath: '/capgo-livereload',
        autoReconnect: true,
        reconnectInterval: 3000
      });


      // Set up listeners before connecting
      await LiveReload.addListener('reloadEvent', this.handleReloadEvent.bind(this));
      await LiveReload.addListener('statusChange', this.handleStatusChange.bind(this));


      // Connect
      await LiveReload.connect();
    } catch (error) {
      console.error('Failed to initialize live reload:', error);
    }
  }


  private handleReloadEvent(event: any) {
    console.log('Reload event received:', event.type);


    switch (event.type) {
      case 'full-reload':
        this.performFullReload();
        break;
      case 'file-update':
        this.handleFileUpdate(event.file);
        break;
      case 'error':
        console.error('Server error:', event.message);
        break;
      case 'connected':
        console.log('Server connected');
        break;
      case 'disconnected':
        console.log('Server disconnected');
        break;
    }
  }


  private handleStatusChange(status: any) {
    this.connected = status.connected;
    console.log(`Live reload ${status.connected ? 'connected' : 'disconnected'}`);
  }


  private performFullReload() {
    console.log('Performing full page reload...');
    window.location.reload();
  }


  private handleFileUpdate(file: any) {
    console.log('File updated:', file?.path);
    // HMR will handle this automatically in most cases
  }


  async disconnect() {
    await LiveReload.disconnect();
    await LiveReload.removeAllListeners();
    this.connected = false;
  }


  isConnected(): boolean {
    return this.connected;
  }
}

Exemple de configuration Vite

Section titled “Exemple de configuration Vite”

Configurez votre serveur Vite pour qu’il fonctionne avec le plugin live reload :

vite.config.ts
import { defineConfig } from 'vite';


export default defineConfig({
  server: {
    host: '0.0.0.0', // Allow connections from network
    port: 5173,
    hmr: {
      // Custom WebSocket path for live reload
      path: '/capgo-livereload',
    }
  }
});

## meilleures pratiques

  1. Utiliser uniquement en développement

    if (import.meta.env.DEV) {
      await LiveReload.configureServer({
        url: 'http://localhost:5173',
        websocketPath: '/capgo-livereload'
      });
      await LiveReload.connect();
    }

  2. Utilisez votre adresse IP locale pour les tests mobiles

    const devServerUrl = process.env.VITE_DEV_SERVER_URL || 'http://192.168.1.100:5173';
    await LiveReload.configureServer({ url: devServerUrl });

  3. Gérez les erreurs de connexion avec élégance

    try {
      await LiveReload.connect();
    } catch (error) {
      console.warn('Could not connect to dev server, using production build');
    }

  4. Nettoyer à la sortie de l’application

    window.addEventListener('beforeunload', async () => {
      await LiveReload.disconnect();
    });

  5. Afficher l’état de la connexion dans l’interface utilisateur

    LiveReload.addListener('statusChange', (status) => {
      // Show indicator in dev builds
      updateDevIndicator(status.connected);
    });

## Remarques sur la plate-forme

iOS

Section titled “iOS”
  • Fonctionne avec iOS 11.0+
  • Assurez-vous que le serveur de développement est accessible depuis le réseau de votre appareil
  • Il faudra peut-être configurer un pare-feu pour autoriser les connexions

Android

Section titled “Android”
  • Fonctionne avec Android 5.0 (API 21)+
  • Utilisez adb reverse pour les connexions localhost :
    Terminal window
    adb reverse tcp:5173 tcp:5173

###Web

  • Prise en charge complète de la plateforme Web
  • Connexion WebSocket directe au serveur de développement Vite

Dépannage

Section titled “Dépannage”

La connexion échoue :

  • Vérifiez que le serveur de développement est en cours d’exécution
  • Vérifiez que l’appareil et l’ordinateur sont sur le même réseau
  • Assurez-vous que le pare-feu autorise les connexions sur le port
  • Utilisez l’adresse IP au lieu de localhost pour les appareils mobiles

Rechargement lent :

  • Vérifier la vitesse du réseau
  • Réduire l’intervalle de reconnexion
  • Optimiser la configuration de la build Vite

Erreurs WebSocket :

  • Vérifiez que websocketPath correspond à la configuration de Vite
  • Vérifier les conflits de ports
  • Assurez-vous que les en-têtes sont corrects si vous utilisez l’authentification