Come ho costruito una PWA senza essere uno sviluppatore: il Portale Consulenti

Tempo di lettura: 7 minuti — Livello: principiante/intermedio

Premessa onesta

Non sono uno sviluppatore di formazione. Vengo dal mondo della consulenza energetica, e fino a qualche anno fa il mio rapporto con il codice era da spettatore. Poi è arrivata l'IA, e con lei un modo nuovo di costruire software: descrivi quello che vuoi, l'IA scrive il codice, tu impari a leggerlo, correggerlo e — soprattutto — a fartene responsabile.

Questo è il racconto di come ho messo in produzione una PWA vera, usata ogni giorno da persone vere, partendo da quel livello lì.

Il problema da risolvere

Coordino una rete di consulenti nel settore energia. Il materiale operativo — FAQ, manuali, strumenti di calcolo — era sparso tra documenti, chat e una knowledge base interna. I consulenti lavorano sul campo, dal telefono, e la domanda ricorrente era sempre la stessa: "dove trovo quella cosa?"

Serviva un punto unico: un portale accessibile dal telefono, veloce, che si comportasse come un'app. Ma pubblicare un'app negli store è un percorso lungo e costoso. La risposta si chiama PWA.

Cos'è una PWA, in breve

Una Progressive Web App è un sito web che il telefono tratta come un'app: la installi dalla schermata home, si apre a schermo intero senza barra del browser, può funzionare offline. Niente App Store, niente Google Play, niente attese di approvazione. Aggiorni il sito, tutti hanno la nuova versione.

Per trasformare un sito in PWA servono tecnicamente tre ingredienti:

1. Un manifest (manifest.json) — un file che descrive l'app: nome, icona, colori, come aprirsi
2. Un service worker (sw.js) — uno script che gestisce cache e comportamento offline
3. HTTPS — obbligatorio, senza non funziona niente Sembra poco. Ed è poco — ma i dettagli mordono, come vedremo.

Lo stack che ho scelto

• Next.js per il frontend — perché l'ecosistema è enorme e l'IA lo conosce benissimo (quando fai vibe coding, la popolarità del framework è una feature: più esempi ha visto il modello, meglio ti assiste)
• Firebase per hosting e autenticazione — piano gratuito generoso, deploy semplice, e l'auth pronta senza scrivere logica di sicurezza a mano
• Claude in VS Code come compagno di sviluppo

Come è andata davvero

La parte facile: la struttura dell'app. Descrivi le pagine, l'IA genera i componenti, tu iteri sul design. In un paio di sessioni serali il portale era navigabile.

La parte media: manifest e icone. Il manifest in sé è banale, ma le icone servono in una manciata di formati e dimensioni diversi (192px, 512px, maskable per Android, apple-touch-icon per iOS...). Consiglio: genera l'icona madre a 1024px e fatti fare uno script che produce tutte le varianti. Cinque minuti invece di un pomeriggio.

La parte che mi ha fatto sudare: il dominio personalizzato. E qui la lezione più utile dell'articolo.

L'errore del dominio: l'inoltro non è un collegamento

Il portale era su Firebase, raggiungibile all'indirizzo *.web.app. Volevo il mio dominio, registrato presso un provider italiano. Il pannello del provider offre un comodo "inoltro con frame": punti il dominio e lui mostra il tuo sito dentro un iframe.

Sembra funzionare. Per una PWA è veleno. Dentro un iframe il service worker non si registra correttamente, il manifest non viene letto dal dominio giusto, e il prompt "aggiungi a schermata home" non compare. Risultato: un sito che si vede ma una PWA che non esiste.

La strada giusta è collegare il dominio dentro la console di Firebase: aggiungi il dominio custom, Firebase ti dà i record DNS (un TXT per la verifica, poi gli A record), li imposti nel pannello DNS del provider, e in qualche ora il dominio punta davvero a Firebase, certificato HTTPS incluso. Nessun iframe, nessun trucco.

Regola generale: se il tuo provider parla di "inoltro", "redirect" o "frame", non è un collegamento DNS. Per qualsiasi cosa più seria di una pagina di cortesia, ti serve il controllo dei record DNS veri.

Cosa userebbero i consulenti alla fine

Un'icona sulla home del telefono. La aprono, hanno FAQ, strumenti e materiale sempre aggiornati. Nessuno di loro sa cosa sia un service worker, ed è esattamente il punto: la tecnologia migliore è quella che sparisce.

Le tre lezioni

1. Il vibe coding funziona, ma il debito è tuo. L'IA scrive il codice in minuti; capire perché funziona resta compito tuo, e ti si presenta il conto al primo bug in produzione.
2. I problemi veri sono ai bordi. Il codice dell'app è stata la parte facile; DNS, icone, certificati — l'infrastruttura intorno — è dove ho perso le serate.
3. Parti dal problema, non dalla tecnologia. Non ho deciso "voglio fare una PWA": avevo consulenti che perdevano tempo a cercare documenti. La PWA era solo la risposta più corta.

---

Questo articolo fa parte della serie "Build in Public" su perfetti.tech — dove racconto quello che costruisco davvero, errori compresi.