Aller au contenu principal
Version : 3.5.2

📦 plugin-pwa

Plugin Docusaurus pour ajouter le support PWA en utilisant Workbox. Ce plugin génère un Service Worker uniquement en production, et vous permet de créer un site de documentation entièrement conforme à la PWA avec support du mode hors ligne et de l'installation.

Installation​

npm install --save @docusaurus/plugin-pwa

Configuration​

Créez un manifeste PWA dans ./static/manifest.json.

Modifiez docusaurus.config.js avec une configuration PWA minimale, tel que :

docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-pwa',
      {
        debug: true,
        offlineModeActivationStrategies: [
          'appInstalled',
          'standalone',
          'queryString',
        ],
        pwaHead: [
          {
            tagName: 'link',
            rel: 'icon',
            href: '/img/docusaurus.png',
          },
          {
            tagName: 'link',
            rel: 'manifest',
            href: '/manifest.json', // votre manifest PWA
          },
          {
            tagName: 'meta',
            name: 'theme-color',
            content: 'rgb(37, 194, 160)',
          },
        ],
      },
    ],
  ],
};

Application Web progressive​

L'installation d'un Service Worker ne suffit pas à faire de votre application une PWA. Vous devez inclure au moins un Manifeste d'Application Web et avoir les tags corrects dans le \<head> (Options > pwaHead).

Après le déploiement, vous pouvez utiliser Lighthouse pour exécuter un audit sur votre site.

Pour une liste plus exhaustive de ce qu'il faut pour que votre site soit un PWA, reportez-vous à la Liste de contrôle PWA

Prise en charge de l'installation de l'application​

Si votre navigateur le supporte, vous devriez pouvoir installer un site Docusaurus en tant qu'application.

Un extrait d&#39;écran du processus d&#39;installation. Un bouton apparaît dans la barre d&#39;adresse du navigateur, qui affiche une boîte de dialogue demandant &quot;install this application?&quot; lorsqu&#39;il est cliqué. Après avoir cliqué sur le bouton &quot;Instal&quot;, une nouvelle application est ouverte dans le système d&#39;exploitation, s&#39;ouvrant sur la page d&#39;accueil de Docusaurus.

remarque

L'installation de l'application nécessite le protocole HTTPS et un manifeste valide.

Mode hors ligne (pré-cache)​

Il est possible de permettre aux utilisateurs de naviguer sur un site Docusaurus hors ligne grâce au pré-cache du service-worker.

La page workbox-precaching explique l'idée :

Une des caractéristiques des services workers est la possibilité d'enregistrer un ensemble de fichiers dans le cache lors de l'installation du service worker. On l'appelle souvent « pré-cache », puisque vous mettez en cache du contenu avant que le service ne soit utilisé.

La principale raison de ce choix est qu'il donne aux développeurs le contrôle du cache, ce qui signifie qu'ils peuvent déterminer quand et combien de temps un fichier est mis en cache et le servir au navigateur sans passer par le réseau, ce qui signifie qu'il peut être utilisé pour créer des applications web qui fonctionnent hors ligne.

Workbox se charge d'une grande partie de la mise en cache en simplifiant l'API et en garantissant un téléchargement efficace des ressources.

Par défaut, le mode hors ligne est activé lorsque le site est installé en tant qu'application. Voir l'option offlineModeActivationStrategies pour plus de détails.

Une fois que le site a été mis en précache, le service worker servira des réponses en cache pour des visites ultérieures. Lorsqu'une nouvelle version est déployée avec un nouveau service worker, le nouveau commence à s'installer et passe ensuite à l'état d'attente. Pendant cet état d'attente, une popup de rechargement s'affichera et demandera à l'utilisateur de recharger la page pour un nouveau contenu. Tant que l'utilisateur n'aura pas vidé le cache de l'application ou cliqué sur le bouton reload de la popup, le service worker continuera à servir l'ancien contenu.

attention

Le mode hors-ligne / pré-cache nécessite de télécharger tous les ressources statiques du site à l'avance, et peut consommer de la bande passante inutilement. Ce n'est peut-être pas une bonne idée de l'activer pour tous les types de sites.

Options​

debug​

  • Type : boolean
  • Par défaut : false

Permet d'activer le mode débogage :

  • Logs de Workbox
  • Logs additionnels de Docusaurus
  • Sortie de fichier SW non optimisé
  • Source maps

offlineModeActivationStrategies​

  • Type : ('appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always')[]
  • Par défaut : ['appInstalled', 'queryString', 'standalone']

Stratégies utilisées pour activer le mode hors ligne :

  • appInstalled : active pour les utilisateurs ayant installé le site comme une application (pas fiable à 100%)
  • standalone : active pour les utilisateurs exécutant l'application comme autonome (souvent le cas une fois qu'une PWA est installé)
  • queryString : active si queryString contient offlineMode=true (pratique pour le débogage PWA)
  • mobile : active pour les utilisateurs mobiles (width = 996px)
  • saveData : active pour les utilisateurs avec navigator.connection.saveData === true
  • always : active pour tous les utilisateurs
attention

Utilisez ceci avec précaution : certains utilisateurs n'aiment pas être forcés d'utiliser le mode hors ligne.

danger

Il n'est pas possible de détecter de manière fiable si une page est rendue comme une PWA.

L'événement appinstalled a été supprimé de la spécification et l'API navigator.getInstalledRelatedApps() n'est prise en charge que dans les versions récentes de Chrome et nécessite related_applications déclarée dans le manifeste.

La stratégie standalone est une belle solution de secours pour activer le mode hors ligne (au moins lors de l'exécution de l'application installée).

injectManifestConfig​

Les options de Workbox à passer à workbox.injectManifest(). Cela vous permet de contrôler les ressources qui seront mises en pré-cache et seront disponibles hors ligne.

  • Type : InjectManifestOptions
  • Par défaut : {}
docusaurus.config.js
export default {
  plugins: [
    [
      '@docusaurus/plugin-pwa',
      {
        injectManifestConfig: {
          manifestTransforms: [
            //...
          ],