feat(manifest): add useWebmanifestExtension option and improve docs (#241)

Co-authored-by: paul_melero <paulmelero@gmail>
Co-authored-by: pooya parsa <pooya@pi0.ir>

Author: 3 people

docs/modules/manifest.md

@@ -9,13 +9,75 @@ sidebar: auto
 
 Manifest adds [Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) with no pain.
 
-You can pass options to `pwa.manifest` in `nuxt.config.js` to override defaults.
+You can pass options to `pwa.manifest` in `nuxt.config.js` to override defaults. Check the
+[valid options](https://developer.mozilla.org/en-US/docs/Web/Manifest#Members) available and and it's
+[default options](#default-options) for deeper insights.
 
 ```js
 pwa: {
   manifest: {
     name: 'My Awesome App',
-    lang: 'fa'
+    lang: 'fa',
+    useWebmanifestExtension: false
   }
 }
 ```
+
+# Default options
+
+| Property                          | Type            | Default                                                      | Description                                                     |
+| --------------------------------- | --------------- | ------------------------------------------------------------ | --------------------------------------------------------------- |
+| `name` <sup>\*1</sup>             | `String`        | `package.json`'s name property                               | [maximum of 45 characters]                                      |
+| `short_name` <sup>\*1</sup>       | `String`        | `package.json`'s name property                               | [maximum of 12 characters]                                      |
+| `description` <sup>\*2</sup>      | `String`        | `package.json`'s description property                        |                                                                 |
+| `icons` <sup>\*1</sup>            | `Array<Object>` | `[]`                                                         | (See the [icon module])                                         |
+| `start_url` <sup>\*1</sup>        | `String`        | `routerBase + '?standalone=true'`                            | It has to be relative to where the manifest is placed           |
+| `display` <sup>\*1</sup>          | `String`        | `'standalone'`                                               |                                                                 |
+| `background_color` <sup>\*2</sup> | `String`        | `'#ffffff'`                                                  |                                                                 |
+| `theme_color` <sup>\*2</sup>      | `String`        | `this.options.loading.color`                                 | Nuxt [loading color] option                                     |
+| `dir`                             | `String`        | `'ltr'`                                                      | `ltr` or `rtl`. Used with `lang`                                |
+| `lang`                            | `String`        | `'en'`                                                       | Recommended if used `dir`                                       |
+| `useWebmanifestExtension` <sup>\*3</sup>       | `Boolean`       | `false`                                                      | Whether to use `webmanifest` file extension (or default `json`) |
+| `publicPath`                      | `String`        | A combination of `routerBase` and `options.build.publicPath` |                                                                 |
+
+- <sup>\*1</sup> Mandatory (according [to Google](https://web.dev/add-manifest)).
+  Although [official documentation](https://w3c.github.io/manifest/#json-schema) only mentions `name` and `icons`
+- <sup>\*2</sup> Recommended (according [to Google](https://web.dev/add-manifest))
+- <sup>\*3</sup> Please see [wiki](https://github.com/nuxt-community/pwa-module/wiki/.webmanifest)
+
+[icon module]: https://pwa.nuxtjs.org/modules/icon.html
+[maximum of 45 characters]: https://developer.chrome.com/apps/manifest/name
+[maximum of 12 characters]: https://developer.chrome.com/apps/manifest/name
+[loading color]: https://nuxtjs.org/api/configuration-loading/#customizing-the-progress-bar
+
+For more information, check out:
+
+- the spec: https://w3c.github.io/manifest/
+- Pete LePage's article: https://web.dev/add-manifest/
+- MDN Docs: https://developer.mozilla.org/en-US/docs/Web/Manifest
+
+## Difference between `name` and `short_name`:
+
+### `name`
+
+> The name (maximum of 45 characters) is the primary identifier of the app and is a required field. It is displayed in the following locations:
+>
+> - Install dialog
+> - Extension management UI
+> - Chrome Web Store
+
+Source: https://developer.chrome.com/apps/manifest/name
+
+### `short_name`
+
+> The short_name (maximum of 12 characters recommended) is a short version of the app's name. It is an optional field and if not specified, the name will be used, > though it will likely be truncated. The short name is typically used where there is insufficient space to display the full name, such as:
+>
+> - Device home screens
+> - New Tab page
+
+Source: https://developer.chrome.com/apps/manifest/name
+
+## `useWebmanifestExtension`:
+
+This options sets the manifest file extension to `.json` or `.webmanifest`. For more information, check
+[this wiki page](https://github.com/nuxt-community/pwa-module/wiki/.webmanifest).

lib/manifest/module.js

@@ -28,7 +28,8 @@ function addManifest (pwa) {
     display: 'standalone',
     background_color: '#ffffff',
     theme_color: this.options.loading && this.options.loading.color,
-    lang: 'en'
+    lang: 'en',
+    useWebmanifestExtension: false
   }
 
   const options = { ...defaults, ...pwa.manifest }
@@ -37,10 +38,17 @@ function addManifest (pwa) {
   const manifest = { ...options }
   delete manifest.src
   delete manifest.publicPath
+  delete manifest.useWebmanifestExtension
 
   // Stringify manifest & generate hash
   const manifestSource = JSON.stringify(manifest)
-  const manifestFileName = `manifest.${hash(manifestSource).substr(0, 8)}.json`
+  const manifestFileName = `manifest.${
+      hash(manifestSource).substr(0, 8)
+    }.${
+      options.useWebmanifestExtension
+      ? 'webmanifest'
+      : 'json'
+    }`
 
   // Merge final manifest into options.manifest for other modules
   if (!this.options.manifest) {

test/__snapshots__/pwa.test.js.snap

@@ -17,6 +17,7 @@ Array [
   "fixture/.nuxt/dist/client/icons/icon_384.b8f3a1.png",
   "fixture/.nuxt/dist/client/icons/icon_512.b8f3a1.png",
   "fixture/.nuxt/dist/client/icons/icon_64.b8f3a1.png",
+  "fixture/.nuxt/dist/client/manifest.bee706d5.webmanifest",
   "fixture/.nuxt/dist/server",
   "fixture/.nuxt/dist/server/index.spa.html",
   "fixture/.nuxt/dist/server/index.ssr.html",
@@ -43,6 +44,7 @@ Array [
   "fixture/dist/_nuxt/icons/icon_384.b8f3a1.png",
   "fixture/dist/_nuxt/icons/icon_512.b8f3a1.png",
   "fixture/dist/_nuxt/icons/icon_64.b8f3a1.png",
+  "fixture/dist/_nuxt/manifest.bee706d5.webmanifest",
   "fixture/dist/icon.png",
   "fixture/dist/index.html",
   "fixture/dist/offline.html",

test/fixture/nuxt.config.js

@@ -12,7 +12,8 @@ module.exports = {
 
   manifest: {
     name: 'Test Project Name',
-    description: 'Test Project Description'
+    description: 'Test Project Description',
+    useWebmanifestExtension: true
   },
 
   workbox: {