Aller au contenu principal
Version: 2.0.0-beta.4

📩 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 hors ligne et installation.

Installation#

npm install --save @docusaurus/plugin-pwa

Configuration#

Créer un manifest PWA dans ./static/manifest.json.

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

docusaurus.config.js
module.exports = {  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', // your PWA manifest          },          {            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 Manifest 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.

pwa_install.gif

remarque

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

Mode hors ligne (pré-cache)#

Nous permettons aux utilisateurs de naviguer sur un site Docusaurus hors ligne, en utilisant la mise en cache préalable du service-worker.

Qu'est-ce que le Pré-cache ?#

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 : Array<'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 (largeur <= 940px)
  • 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 si c'est un PWA de maniÚre trÚs fiable.

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
module.exports = {  plugins: [    [      '@docusaurus/plugin-pwa',      {        injectManifestConfig: {          manifestTransforms: [            //...          ],          modifyURLPrefix: {            //...          },          // Nous ajoutons déjà des ressources statiques réguliÚres (html, images...) pour qu'elles soient disponibles hors ligne.          // Vous pouvez ajouter d'autres fichiers en fonction de vos besoins          globPatterns: ['**/*.{pdf,docx,xlsx}'],          // ...        },      },    ],  ],};

reloadPopup#

  • Type : string | false
  • Par dĂ©faut : '@theme/PwaReloadPopup'

Chemin du module pour recharger le composant popup. Ce popup est rendu lorsqu'un nouveau service worker attend d'ĂȘtre installĂ©, et que nous suggĂ©rons un rechargement Ă  l'utilisateur.

Le passage à false désactivera la popup, mais ce n'est pas recommandé : les utilisateurs n'auront pas de moyen d'obtenir un contenu à jour.

Un composant personnalisĂ© peut ĂȘtre utilisĂ©, Ă  condition qu'il accepte onReload en tant que prop. La fonction de rappel onReload doit ĂȘtre appelĂ©e lorsque le bouton reload est cliquĂ©. Cela indiquera au service worker d'installer le service worker en attente et de recharger la page.

interface PwaReloadPopupProps {  onReload: () => void;}

Le thÚme par défaut inclut une implémentation pour la popup de rechargement et utilise Infima Alerts.

pwa_reload.gif

pwaHead#

  • Type : Array<{ tagName: string } & Record<string,string>>
  • Par dĂ©faut : []

Tableau d'objets contenant tagName et des paires clé-valeur pour les attributs à injecter dans la balise <head>. Techniquement, vous pouvez injecter n'importe quelle balise head par ce biais, mais l'idéal est de l'utiliser pour les balises afin de rendre votre site conforme à la norme PWA. Voici une liste de tags pour rendre votre application entiÚrement compatible :

module.exports = {  plugins: [    [      '@docusaurus/plugin-pwa',      {        pwaHead: [          {            tagName: 'link',            rel: 'icon',            href: '/img/docusaurus.png',          },          {            tagName: 'link',            rel: 'manifest',            href: '/manifest.json',          },          {            tagName: 'meta',            name: 'theme-color',            content: 'rgb(37, 194, 160)',          },          {            tagName: 'meta',            name: 'apple-mobile-web-app-capable',            content: 'yes',          },          {            tagName: 'meta',            name: 'apple-mobile-web-app-status-bar-style',            content: '#000',          },          {            tagName: 'link',            rel: 'apple-touch-icon',            href: '/img/docusaurus.png',          },          {            tagName: 'link',            rel: 'mask-icon',            href: '/img/docusaurus.svg',            color: 'rgb(37, 194, 160)',          },          {            tagName: 'meta',            name: 'msapplication-TileImage',            content: '/img/docusaurus.png',          },          {            tagName: 'meta',            name: 'msapplication-TileColor',            content: '#000',          },        ],      },    ],  ],};

swCustom#

  • Type : string | undefined
  • Par dĂ©faut : undefined

Utile pour des rÚgles additionnelles de Workbox. Vous pouvez faire tout ce qu'un service worker peut faire ici, et utiliser toute la puissance des bibliothÚques Workbox. Le code est transpilé, vous pouvez donc utiliser la syntaxe moderne ES6+ ici.

Par exemple, pour mettre en cache des fichiers depuis des chemins externes :

import {registerRoute} from 'workbox-routing';import {StaleWhileRevalidate} from 'workbox-strategies';
// default fn export reçoit quelques paramÚtres utilesexport default function swCustom(params) {  const {    debug, // :boolean    offlineMode, // :boolean  } = params;
  // Mettre en cache les réponses des ressources externes  registerRoute((context) => {    return [      /graph\.facebook\.com\/.*\/picture/,      /netlify\.com\/img/,      /avatars1\.githubusercontent/,    ].some((regex) => context.url.href.match(regex));  }, new StaleWhileRevalidate());}

Le module doit avoir une fonction d'exportation default, et reçoit quelques paramÚtres.

swRegister#

  • Type : string | false
  • Par dĂ©faut : 'docusaurus-plugin-pwa/src/registerSW.js'

Ajoute une entrée avant l'application Docusaurus pour que l'enregistrement puisse se faire avant l'exécution de l'application. Le fichier registerSW.js par défaut est suffisant pour un simple enregistrement.

Passer false désactivera complÚtement l'inscription.

Exemple de manifeste#

Le manifeste du site Docusaurus peut servir d'inspiration :

{  "name": "Docusaurus v2",  "short_name": "Docusaurus",  "theme_color": "#2196f3",  "background_color": "#424242",  "display": "standalone",  "scope": "./",  "start_url": "./index.html",  "related_applications": [    {      "platform": "webapp",      "url": "https://docusaurus.io/manifest.json"    }  ],  "icons": [    {      "src": "img/icons/icon-72x72.png",      "sizes": "72x72",      "type": "image/png"    },    {      "src": "img/icons/icon-96x96.png",      "sizes": "96x96",      "type": "image/png"    },    {      "src": "img/icons/icon-128x128.png",      "sizes": "128x128",      "type": "image/png"    },    {      "src": "img/icons/icon-144x144.png",      "sizes": "144x144",      "type": "image/png"    },    {      "src": "img/icons/icon-152x152.png",      "sizes": "152x152",      "type": "image/png"    },    {      "src": "img/icons/icon-192x192.png",      "sizes": "192x192",      "type": "image/png"    },    {      "src": "img/icons/icon-384x384.png",      "sizes": "384x384",      "type": "image/png"    },    {      "src": "img/icons/icon-512x512.png",      "sizes": "512x512",      "type": "image/png"    }  ]}