Il file manifest.json
è un componente chiave nelle applicazioni web moderne, specialmente per le Progressive Web App (PWA).
Questo file, infatti, fornisce una serie di importanti informazioni sull’applicazione web che ne descrivono il comportamento e l’aspetto.
In questo articolo, esploreremo cos’è il file manifest.json
, a cosa serve, come configurarlo e alcuni esempi pratici per aiutarti a integrarlo correttamente nella tua web application.
Indice
Cos’è il file manifest.json?
Il file manifest.json
è un file di configurazione in formato JSON (JavaScript Object Notation) utilizzato principalmente nelle applicazioni web, in particolare nelle Progressive Web App.
Esso contiene metadati che descrivono l’applicazione, come il nome, le icone, i colori e altre informazioni che permettono al browser di trattare correttamente la PWA.
L’obiettivo principale del manifest.json
è quello di migliorare l’esperienza utente, facilitando l’aggiunta dell’applicazione alla schermata principale di un dispositivo al fine di fornire un’esperienza d’uso simile a quella di un’app nativa.
Struttura del file manifest.json
Un file manifest.json
è una semplice file di testo che contiene una serie di dati in formato JSON. Affinché il file sia valido deve essere formattato seguendo delle linee guida ben precise definite nelle specifiche.
Ogni proprietà inclusa nel file è opzionale, ma è consigliabile configurare almeno le proprietà essenziali per garantire un corretto funzionamento dell’applicazione. Ecco un esempio di base della struttura del file:
{
"name": "Nome Completo della tua App",
"short_name": "Nome Breve della tua App",
"description": "Una breve descrizione della tua applicazione",
"start_url": "/index.html",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#000000",
"icons": [
{
"src": "/img/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/img/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
]
}
Le proprietà principali che è possibile includere in un file manifest.json
sono le seguenti:
- name: Il nome completo dell’applicazione, che apparirà quando l’utente installerà l’app.
- short_name: Una versione abbreviata del nome che verrà utilizzata quando lo spazio è limitato, come nella schermata home di un dispositivo mobile.
- description: Una breve descrizione dell’app che aiuta l’utente a capire lo scopo dell’applicazione che sta installando.
- start_url: L’URL iniziale da caricare quando l’app viene aperta. Di solito è la homepage dell’applicazione. Può essere sia una URL assoluta che relativa.
- display: Definisce come l’applicazione viene visualizzata. Le opzioni principali sono:
fullscreen
: L’applicazione si apre a schermo intero senza barra del browser.standalone
: L’app si comporta come una normale app mobile, senza barra degli indirizzi.minimal-ui
: Mostra una barra con pulsanti di navigazione base.browser
: L’app si apre come una pagina web standard nel browser.
- background_color: Il colore di sfondo della schermata di avvio dell’app.
- theme_color: Il colore del tema dell’app, che influenzerà la barra superiore del browser sui dispositivi mobili.
- icons: Un array di oggetti che specificano le icone utilizzate dall’app. Ogni oggetto include le seguenti proprietà:
src
: Il percorso dell’icona.sizes
: Le dimensioni dell’icona, espresse come stringa (es. “192×192”).type
: Il tipo di immagine (es. “image/png”).
Qui sotto un esempio più completo di un file manifest.json
con un maggior numero di proprietà per una maggiore personalizzazione:
{
"name": "Mr.Webmaster App",
"short_name": "MRW App",
"description": "Una fantastica app che ti permette di avere MRW sempre con te!",
"start_url": "/home",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#cc5200",
"orientation": "portrait",
"scope": "/",
"icons": [
{
"src": "/icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
],
"related_applications": [],
"prefer_related_applications": false
}
Configurazione di un file manifest.json
La configurazione di un file manifest.json
varia in base all’applicazione, ma ci sono alcuni passaggi comuni da seguire per configurarlo correttamente:
La prima cosa da fare è creare un file vuoto chiamato manifest.json
e salvarlo nella root del progetto. Per creare un file json è sufficiente utilizzare un editor di testo (come il Blocco Note di Windows) avendo cura di salvare il file con estensione .json invece di .txt.
All’interno del nostro file manifest.json
andiamo ad inserire le proprietà essenziali come name
, start_url
, icons
, display
, e theme_color
. Per semplificare il lavoro potete fare copia e incolla del codice di esempio visto prima avendo cura, ovviamente, di personalizzarlo conn i dati della vostra app.
Una volta creato il file, questo dovrà essere “collegato” alla vostra applicazione. Per farlo sarà sufficiente inserire all’interno del codice HTML (nella porzione di codice tra <head> e </head>) un tag <link>
come da esempio:
<link rel="manifest" href="/manifest.json">
Per verificare di aver fatto tutto correttamente è consigliabile effettuare un test mediante strumenti come Lighthouse che consentono di verificare la corretta integrazione e il comportamento della PWA.
Strumenti utili per generare e validare manifest.json
Esistono diversi strumenti che facilitano la creazione e la validazione del file manifest.json
. Vediamoli brevemente:
PWA Builder
Uno strumento online che ti permette di generare rapidamente il file manifest.json
e altri componenti necessari per trasformare una web app in una PWA.
Web App Manifest Validator (by Redirection.io)
Un validatore online che verifica se il tuo file manifest.json
segue le specifiche corrette. Basta inserire la URL della web application per verificare la correttezza dell’implementazione effettuata.
Lighthouse
E’ possibile verificare la corretta implementazione del file manifest.json
anche mediante Lighthouse, un tool integrato in Chrome DevTools che ti aiuta a verificare le performance e la conformità della tua PWA, inclusa la corretta configurazione del manifest.json
.
Domande Frequenti
manifest.json
in una PWA? No, ma è fortemente raccomandato se vuoi che la tua applicazione venga trattata come una PWA e offra una migliore esperienza utente sui dispositivi mobili.
Il tuo file manifest.json
sarà comunque valido, ma potresti non ottenere il comportamento desiderato. Ad esempio, senza un’icona specificata, la tua app potrebbe non avere un’icona appropriata quando aggiunta alla schermata principale.
manifest.json
per applicazioni non-PWA? Sì, alcune proprietà del manifest.json
, come le icone, possono essere utili anche per applicazioni non-PWA, specialmente per migliorare l’aspetto e l’accessibilità su dispositivi mobili.
manifest.json
per trasformare un sito web in una PWA? No. Il manifest.json
è solo uno dei requisiti necessari per rendere il sito una PWA, ma ci sono altri componenti essenziali da implementare. Un altro elemento essenziale è il service worker, un componente fondamentale per abilitare le funzionalità offline (cache) e altre capacità avanzate di una PWA.