Come trasformare il tuo sito in una Progressive Web App

Come trasformare il tuo sito in una PWA (codice testato) | We.Inc

Rendi installabile e pronto all'offline qualsiasi sito: un generatore di manifest, un service worker testato, un pulsante di installazione, i limiti su iPhone e la configurazione per Vite o Next.js.

Come trasformare il tuo sito in una Progressive Web App

Per trasformare un sito in una progressive web app, servilo in HTTPS, aggiungi un manifest.webmanifest con nome, start_url, modalità di visualizzazione e icone da 192 e 512 pixel, collegalo da ogni pagina e registra un service worker che metta in cache i file per l'uso offline. I browser Chromium a quel punto propongono l'installazione; gli utenti Safari la aggiungono da Condividi.

Le tre parti di una PWA

Parte
Cosa fa

Nome, icone, colori e come si apre l'app

Service worker (sw.js)
Mette in cache i file così le pagine si caricano offline

HTTPS
Obbligatorio per i service worker e l'installazione

Compila il modulo per ottenere un manifest e i tag head da incollare, poi copia il service worker e lo script di installazione. Il worker di questa pagina è stato eseguito in un browser reale con la rete scollegata prima della pubblicazione.

Crea le icone a 192 e 512 pixel, più una versione maskable con il logo nell'80 percento centrale.
Genera il manifest con il modulo, salvalo come manifest.webmanifest nella root del sito e incolla i tag head in ogni pagina.
Salva sw.js, offline.html e lo script di registrazione, ed elenca i tuoi file principali in PRECACHE.
Apri Chrome DevTools, pannello Application: controlla Manifest per i problemi di installazione e Service workers per il worker in esecuzione. Spunta Offline e ricarica per testare.
Quando modifichi i file in cache, incrementa VERSION così chi torna sul sito riceve quelli nuovi.

Servi sw.js dalla root del sito. Un worker controlla solo le pagine nella sua cartella o al di sotto.
Non mettere in cache sw.js stesso con header di cache HTTP lunghi; i browser lo controllano per gli aggiornamenti.
Tieni corto l'elenco di precache. Tutto ciò che contiene viene scaricato alla prima visita.
Su iPhone, spiega alle persone come installare: Condividi, poi Aggiungi alla schermata Home. Non c'è nessun prompt da attivare.
Testa l'offline fermando anche il tuo server locale oltre a usare la casella Offline, così falliscono anche le richieste del worker stesso.

Domande frequenti

Una PWA ha bisogno di un service worker per essere installabile?

Nell'attuale Chrome no: un manifest valido, HTTPS e un minimo di interazione dell'utente bastano per l'opzione di installazione. Il worker ti serve comunque, perché senza l'app installata mostra la pagina di errore del browser quando sei offline.

Le PWA funzionano su iPhone?

Sì, con dei limiti. Gli utenti Safari installano dal menu Condividi, non esiste l'evento del prompt di installazione e le notifiche push funzionano solo per un sito aggiunto alla schermata Home su iOS 16.4 o successivo. La cache offline funziona.

Perché il mio pulsante di installazione non compare mai?

beforeinstallprompt si attiva solo nei browser Chromium, solo quando i criteri di installazione sono soddisfatti e non quando l'app è già installata. Controlla la sezione Manifest del pannello Application di DevTools per conoscere il motivo.

Come verifico una PWA ora che Lighthouse non ha più un punteggio PWA?

Lighthouse 12 ha eliminato la categoria PWA. Usa il pannello Application di Chrome DevTools: la vista Manifest elenca gli errori di installabilità e i problemi delle icone, e la vista Service workers mostra registrazione, aggiornamenti e un interruttore Offline.

Come aggiorno una PWA dopo un rilascio?

Cambia il VERSION della cache in sw.js. Il browser rileva il worker modificato, lo installa e la fase di activate rimuove le vecchie cache. Con skipWaiting e clients.claim il nuovo worker prende il controllo al caricamento successivo.

Cache-first o network-first

Cache-first risponde dalla cache e va in rete solo per ciò che non ha salvato. È veloce e adatto ai file il cui contenuto non cambia mai a parità di nome, come script con hash, font e icone.
Network-first interroga il server e usa la cache solo quando la richiesta fallisce. È adatto alle pagine HTML, dove mostrare una copia vecchia dopo un aggiornamento confonderebbe le persone. Il worker qui sopra li usa entrambi: network-first per il caricamento delle pagine, cache-first per tutto il resto.

Errori comuni

Registrare il worker da un percorso in una sottocartella come /js/sw.js, che lo limita alle pagine sotto /js/.
Dimenticare di cambiare VERSION, così chi torna sul sito si tiene CSS e script vecchi per settimane.
Mettere in cache risposte di altri siti o risposte di errore. Il worker qui sopra salta le richieste cross-origin e salva solo le risposte riuscite degli asset.
Testare solo in Chrome. Apri il sito su un iPhone per vedere cosa ottengono davvero gli utenti Safari.

Cosa ottieni, e i limiti su iPhone

L'installazione dà al tuo sito una sua icona e una finestra senza barra degli indirizzi. Un service worker aggiunge le pagine offline. Le notifiche push richiedono entrambi, e Apple le consente solo per i siti che l'utente ha aggiunto alla schermata Home.

Cosa può fare una PWA, per piattaforma

Funzionalità
Chrome / Edge (desktop, Android)
Safari su iPhone e iPad
Firefox

Installazione su schermata Home o desktop
Sì, con un prompt di installazione
Sì, a mano: Condividi, poi Aggiungi alla schermata Home
Android: sì. Desktop: limitata, verifica la tua versione

Pulsante di installazione personalizzato (beforeinstallprompt)
Sì
No
No

Offline con un service worker
Sì
Sì
Sì

Notifiche web push
Sì
Solo per un sito aggiunto alla schermata Home, iOS 16.4 o successivo
Sì

Archiviazione persistente
Sì, può essere rimossa in caso di pressione sullo spazio
Nelle schede Safari, i dati scritti dagli script possono essere cancellati dopo 7 giorni di uso del browser senza visite; le app sulla schermata Home hanno un conteggio proprio
Sì, può essere rimossa in caso di pressione sullo spazio

Sincronizzazione in background
Sì
No
No

Un service worker funzionante

Tre file fanno funzionare un sito offline: il worker, una pagina di fallback e poche righe per registrarlo. Abbiamo eseguito esattamente questi file su localhost in Chromium: il worker si è installato, la cache si è riempita e, con il server fermo, la home page si è caricata dalla cache mentre una pagina mai visitata ha mostrato offline.html.

sw.js: un service worker minimo che funziona offline

Le pagine provano prima la rete, così le persone vedono contenuti aggiornati, poi ripiegano su una copia in cache, poi su offline.html. File come CSS, script e icone arrivano prima dalla cache. Cambiare VERSION fa sì che la successiva fase di activate elimini le vecchie cache.

offline.html: la pagina di fallback

Rendila autosufficiente: stili inline e nessun file esterno, perché quando compare potrebbe non essere raggiungibile nient'altro.

Un pulsante di installazione

app.js: registra il worker e mostra un pulsante di installazione

L'evento beforeinstallprompt si attiva solo nei browser Chromium (Chrome, Edge, Samsung Internet, Opera). Safari e Firefox non lo inviano mai, quindi lì il pulsante resta nascosto e le persone usano il menu del browser.

I criteri di installazione oggi

Chrome non pretende più un service worker prima di proporre l'installazione; controlla il manifest e le voci qui sotto. Lighthouse 12 ha rimosso la categoria PWA, quindi verifica l'installabilità in Chrome DevTools: pannello Application, poi Manifest, che elenca eventuali problemi sotto Installability.

I requisiti di installazione di Chrome

Requisito
Dettaglio

HTTPS
Servito in modo sicuro. localhost conta come sicuro per i test.

Nome nel manifest
name o short_name

Icone nel manifest
Almeno un'icona da 192 px e una da 512 px

Presente nel manifest

fullscreen, standalone, minimal-ui o window-controls-overlay

Assente o false

Interazione
Il visitatore ha cliccato o toccato la pagina almeno una volta e ci ha passato un po' di tempo

Configurazioni per Vite e Next.js

Vite: vite-plugin-pwa

Installa con npm i -D vite-plugin-pwa. Il plugin scrive il manifest e genera un service worker Workbox in fase di build, quindi non devi scrivere sw.js a mano. Metti le icone in public/.

Next.js App Router: app/manifest.ts

Next.js serve questo file su /manifest.webmanifest e aggiunge il tag link al posto tuo. Per il supporto offline, metti lo sw.js qui sopra in public/ e registralo da un piccolo client component.

Next.js: registra public/sw.js da un client component

Renderizzalo una sola volta in app/layout.tsx. Salta la registrazione in sviluppo, così una build in cache non nasconde le tue modifiche.

Nome dell'app

Nome breve (sotto l'icona)

URL di avvio

Cartella delle icone

Colore del tema

Colore di sfondo

Copia

Generatore di manifest

Visualizzazione

Includi un'icona maskable

Salva le tue icone come icon-192.png e icon-512.png (e icon-512-maskable.png) nella cartella delle icone.

Come trasformare il tuo sito in una Progressive Web App

Come trasformare il tuo sito in una PWA (codice testato) | We.Inc