Il file manifest.json: cos’è e a cosa serve

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.

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