Transformer votre site web en PWA (code testé) | We.Inc
Rendez n'importe quel site installable et utilisable hors ligne : un générateur de manifest, un service worker testé, un bouton d'installation, les limites sur iPhone et la configuration Vite ou Next.js.
Transformer votre site web en progressive web app
Pour transformer un site web en progressive web app, servez-le en HTTPS, ajoutez un manifest.webmanifest avec un nom, un start_url, un mode d'affichage et des icônes de 192 et 512 pixels, liez-le depuis chaque page, et enregistrez un service worker qui met les fichiers en cache pour l'usage hors ligne. Les navigateurs Chromium proposent alors l'installation ; les utilisateurs de Safari l'ajoutent depuis Partager.
Les trois éléments d'une PWA
Élément
Ce qu'il fait
Nom, icônes, couleurs et façon dont l'app s'ouvre
Service worker (sw.js)
Met les fichiers en cache pour que les pages se chargent hors ligne
HTTPS
Obligatoire pour les service workers et l'installation
Remplissez le formulaire pour obtenir un manifest et les balises head à coller, puis copiez le service worker et le script d'installation. Le worker de cette page a été exécuté dans un vrai navigateur avec le réseau coupé avant sa publication.
Créez des icônes de 192 et 512 pixels, plus une version maskable avec le logo dans les 80 pour cent centraux.
Générez le manifest avec le formulaire, enregistrez-le sous manifest.webmanifest à la racine du site et collez les balises head dans chaque page.
Enregistrez sw.js, offline.html et le script d'enregistrement, et listez vos fichiers essentiels dans PRECACHE.
Ouvrez Chrome DevTools, panneau Application : consultez Manifest pour les problèmes d'installation et Service workers pour le worker en cours. Cochez Offline et rechargez pour tester.
Quand vous modifiez des fichiers en cache, incrémentez VERSION pour que les visiteurs qui reviennent reçoivent les nouveaux.
Servez sw.js depuis la racine du site. Un worker ne contrôle que les pages situées dans son propre dossier ou en dessous.
Ne mettez pas sw.js lui-même en cache avec des en-têtes HTTP de longue durée ; les navigateurs le vérifient pour détecter les mises à jour.
Gardez la liste de précache courte. Tout ce qu'elle contient est téléchargé dès la première visite.
Sur iPhone, expliquez aux gens comment installer : Partager, puis Sur l'écran d'accueil. Il n'y a aucune invite à déclencher.
Testez le mode hors ligne en arrêtant aussi votre serveur local en plus de la case Offline, pour que les requêtes du worker lui-même échouent également.
Questions fréquentes
Une PWA a-t-elle besoin d'un service worker pour être installable ?
Dans Chrome actuel, non : un manifest valide, le HTTPS et un minimum d'interaction de l'utilisateur suffisent pour proposer l'installation. Un worker reste souhaitable, car sans lui l'app installée affiche la page d'erreur du navigateur hors ligne.
Les PWA fonctionnent-elles sur iPhone ?
Oui, avec des limites. Les utilisateurs de Safari installent depuis le menu Partager, il n'existe pas d'événement d'invite d'installation, et les notifications push ne fonctionnent que pour un site ajouté à l'écran d'accueil sur iOS 16.4 ou ultérieur. La mise en cache hors ligne fonctionne.
Pourquoi mon bouton d'installation n'apparaît-il jamais ?
beforeinstallprompt ne se déclenche que dans les navigateurs Chromium, uniquement lorsque les critères d'installation sont remplis, et pas quand l'app est déjà installée. Consultez la section Manifest du panneau Application des DevTools pour connaître la raison.
Comment vérifier une PWA maintenant que Lighthouse n'a plus de score PWA ?
Lighthouse 12 a supprimé la catégorie PWA. Utilisez le panneau Application de Chrome DevTools : la vue Manifest liste les erreurs d'installabilité et les problèmes d'icônes, et la vue Service workers affiche l'enregistrement, les mises à jour et un interrupteur Offline.
Comment mettre à jour une PWA après une nouvelle version ?
Changez la VERSION du cache dans sw.js. Le navigateur détecte le worker modifié, l'installe, et l'étape activate supprime les anciens caches. Avec skipWaiting et clients.claim, le nouveau worker prend le relais au chargement suivant.
Cache d'abord ou réseau d'abord
La stratégie cache d'abord répond depuis le cache et ne va sur le réseau que pour ce qu'elle n'a pas stocké. Elle est rapide et adaptée aux fichiers dont le contenu ne change jamais sous le même nom, comme les scripts hachés, les polices et les icônes.
La stratégie réseau d'abord interroge le serveur et n'utilise le cache qu'en cas d'échec. Elle convient aux pages HTML, où afficher une ancienne copie après une mise à jour dérouterait les gens. Le worker ci-dessus utilise les deux : réseau d'abord pour le chargement des pages, cache d'abord pour tout le reste.
Erreurs courantes
Enregistrer le worker depuis un sous-dossier comme /js/sw.js, ce qui le limite aux pages de /js/.
Oublier de changer VERSION, si bien que les visiteurs qui reviennent gardent l'ancien CSS et les anciens scripts pendant des semaines.
Mettre en cache des réponses d'autres sites ou des réponses d'erreur. Le worker ci-dessus ignore les requêtes cross-origin et ne stocke que les réponses réussies pour les ressources.
Ne tester que dans Chrome. Ouvrez le site sur un iPhone pour voir ce qu'obtiennent réellement les utilisateurs de Safari.
Ce que vous obtenez, et les limites sur iPhone
L'installation donne à votre site sa propre icône et une fenêtre sans barre d'adresse. Un service worker ajoute les pages hors ligne. Le push a besoin des deux, et Apple ne l'autorise que pour les sites que l'utilisateur a ajoutés à l'écran d'accueil.
Ce qu'une PWA peut faire, selon la plateforme
Fonctionnalité
Chrome / Edge (ordinateur, Android)
Safari sur iPhone et iPad
Firefox
Installation sur l'écran d'accueil ou le bureau
Oui, avec une invite d'installation
Oui, à la main : Partager, puis Sur l'écran d'accueil
Android : oui. Ordinateur : limité, vérifiez votre version
Uniquement pour un site ajouté à l'écran d'accueil, iOS 16.4 ou ultérieur
Oui
Stockage durable
Oui, peut être évincé en cas de manque d'espace
Dans les onglets Safari, le stockage écrit par script peut être effacé après 7 jours d'utilisation du navigateur sans visite ; les apps de l'écran d'accueil ont leur propre compteur
Oui, peut être évincé en cas de manque d'espace
Synchronisation en arrière-plan
Oui
Non
Non
Un service worker fonctionnel
Trois fichiers suffisent pour qu'un site fonctionne hors ligne : le worker, une page de secours et quelques lignes pour l'enregistrer. Nous avons exécuté exactement ces fichiers sur localhost dans Chromium : le worker s'est installé, le cache s'est rempli, et serveur arrêté, la page d'accueil s'est chargée depuis le cache tandis qu'une page jamais visitée affichait offline.html.
sw.js : un service worker minimal qui fonctionne hors ligne
Les pages essaient d'abord le réseau pour afficher un contenu à jour, puis se rabattent sur une copie en cache, puis sur offline.html. Les fichiers comme le CSS, les scripts et les icônes viennent d'abord du cache. Changer VERSION fait supprimer les anciens caches à l'étape activate suivante.
offline.html : la page de secours
Rendez-la autonome : styles en ligne et aucun fichier externe, car rien d'autre n'est peut-être accessible lorsqu'elle s'affiche.
Un bouton d'installation
app.js : enregistrer le worker et afficher un bouton d'installation
L'événement beforeinstallprompt ne se déclenche que dans les navigateurs Chromium (Chrome, Edge, Samsung Internet, Opera). Safari et Firefox ne l'envoient jamais, donc le bouton y reste masqué et les gens passent par le menu du navigateur.
Les critères d'installation aujourd'hui
Chrome n'exige plus de service worker avant de proposer l'installation ; il vérifie le manifest et les éléments ci-dessous. Lighthouse 12 a supprimé sa catégorie PWA, vérifiez donc l'installabilité dans Chrome DevTools : panneau Application, puis Manifest, qui liste les problèmes éventuels sous Installability.
Les conditions d'installation de Chrome
Condition
Détail
HTTPS
Servi de manière sécurisée. localhost compte comme sécurisé pour les tests.
Nom dans le manifest
name ou short_name
Icônes dans le manifest
Au moins une icône de 192 px et une de 512 px
Présent dans le manifest
fullscreen, standalone, minimal-ui ou window-controls-overlay
Absent ou false
Interaction
Le visiteur a cliqué ou appuyé sur la page au moins une fois et y a passé un peu de temps
Configurations Vite et Next.js
Vite : vite-plugin-pwa
Installez-le avec npm i -D vite-plugin-pwa. Le plugin écrit le manifest et génère un service worker Workbox au moment du build, vous n'avez donc pas à écrire sw.js à la main. Placez les icônes dans public/.
Next.js App Router : app/manifest.ts
Next.js sert ce fichier à /manifest.webmanifest et ajoute la balise link pour vous. Pour le hors ligne, placez le sw.js ci-dessus dans public/ et enregistrez-le depuis un petit composant client.
Next.js : enregistrer public/sw.js depuis un composant client
Affichez-le une seule fois dans app/layout.tsx. Ignorez l'enregistrement en développement pour qu'un build en cache ne masque pas vos modifications.
Nom de l'app
Nom court (sous l'icône)
URL de démarrage
Dossier des icônes
Couleur du thème
Couleur d'arrière-plan
Copier
Générateur de manifest
Affichage
Inclure une icône maskable
Enregistrez vos icônes sous icon-192.png et icon-512.png (et icon-512-maskable.png) dans le dossier des icônes.