feat(gatsby-plugin-manifest): add cache busting to icon url (#8343)

* change cacheId generation only when the icon file is available * fix linter yarn lint:js --fix * update peerDependencies * change to createContentDigest * use fs-extra for consistency * feat: add cache busting used internal digest generator till the global one is available converted the node api to use ASYNC await to simplify new code added cache busting to favicon, manifest, and legacy head links * test: add tests for cache busting * Docs: added docs for cache busting to gatsby-plugin-manifest * test: fix createContentDigest test failing * fix: generateIcons not called when cache busting disabled * test: add tests to confirm icons are being generated, or not as they're suppose to be. * fix peer dep * cleanup code * clenaup tests * fix windows test
gatsbyjs · Mar 12, 2019 · 5f656f8 · 5f656f8
1 parent 72ec7ce
commit 5f656f8
Show file tree

Hide file tree

Showing 10 changed files with 443 additions and 200 deletions.
diff --git a/packages/gatsby-plugin-manifest/README.md b/packages/gatsby-plugin-manifest/README.md
@@ -35,7 +35,8 @@ There are three modes in which icon generation can function: automatic, hybrid,
 
 In the automatic mode, you are responsible for defining the entire web app manifest except for the icons portion. You only provide a high resolution source icon. The icons themselves and the needed config will be generated at build time. See the example `gatsby-config.js` below:
 
-```javascript:title=gatsby-config.js
+```js
+// in gatsby-config.js
 module.exports = {
   plugins: [
     {
@@ -110,7 +111,8 @@ The automatic mode is the easiest option for most people.
 
 However, if you want to include more or fewer sizes, then the hybrid option is for you. Like automatic mode, you should include a high resolution icon to generate smaller icons from. But unlike automatic mode, you provide the `icons` array config and icons are generated based on the sizes defined in your config. Here's an example `gatsby-config.js`:
 
-```javascript:title=gatsby-config.js
+```js
+// in gatsby-config.js
 module.exports = {
   plugins: [
     {
@@ -149,7 +151,8 @@ The hybrid option allows the most flexibility while still not requiring you to c
 
 In the manual mode, you are responsible for defining the entire web app manifest and providing the defined icons in the static directory. Only icons you provide will be available. There is no automatic resizing done for you. See the example `gatsby-config.js` below:
 
-```javascript:title=gatsby-config.js
+```js
+// in gatsby-config.js
 module.exports = {
   plugins: [
     {
@@ -189,7 +192,8 @@ module.exports = {
 
 iOS 11.3 added support for service workers but not the complete webmanifest spec. Therefore iOS won't recognize the icons defined in the webmanifest and the creation of `apple-touch-icon` links in `<head>` is needed. This plugin creates them by default. If you don't want those icons to be generated you can set the `legacy` option to `false` in plugin configuration:
 
-```javascript:title=gatsby-config.js
+```js
+// in gatsby-config.js
 module.exports = {
   plugins: [
     {
@@ -213,7 +217,8 @@ module.exports = {
 
 By default `gatsby-plugin-manifest` inserts `<meta content={theme_color} name="theme-color" />` tag to html output. This can be problematic if you want to programatically control that tag - for example when implementing light/dark themes in your project. You can set `theme_color_in_head` plugin option to `false` to opt-out of this behavior.
 
-```javascript:title=gatsby-config.js
+```js
+// in gatsby-config.js
 module.exports = {
   plugins: [
     {
@@ -237,7 +242,8 @@ module.exports = {
 
 Excludes `<link rel="shortcut icon" href="/favicon.png" />` link tag to html output. You can set `include_favicon` plugin option to `false` to opt-out of this behaviour.
 
-```javascript:title=gatsby-config.js
+```js
+// in gatsby-config.js
 module.exports = {
   plugins: [
     {
@@ -250,14 +256,48 @@ module.exports = {
         theme_color: `#a2466c`,
         display: `standalone`,
         icon: `src/images/icon.png`, // This path is relative to the root of the site.
-        theme_color_in_head: false, // This will avoid adding theme-color meta tag.
         include_favicon: false, // This will exclude favicon link tag
       },
     },
   ],
 }
 ```
 
+## Disabling or changing "[Cache Busting](https://www.keycdn.com/support/what-is-cache-busting)" Mode
+
+Cache Busting allows your updated icon to be quickly/easily visible to your sites visitors. HTTP caches could otherwise keep an old Icon around for days and weeks. Cache busting is only done in 'automatic' and 'hybrid' modes.
+
+Cache busting works by calculating a unique "digest" or "hash" of the provided icon and modifying links and file names of generated images with that unique digest. If you ever update your icon, the digest will change and caches will be busted.
+
+**Options:**
+
+- **\`query\`** - This is the default mode. File names are unmodified but a URL query is appended to all links. e.g. `icons/icon-48x48.png?digest=abc123`
+
+- **\`name\`** - Changes the cache busting mode to be done by file name. File names and links are modified with the icon digest. e.g. `icons/icon-48x48-abc123.png` (only needed if your CDN does not support URL query based cache busting)
+
+- **\`none\`** - Disables cache busting. File names and links remain unmodified.
+
+```js
+// in gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-plugin-manifest`,
+      options: {
+        name: `GatsbyJS`,
+        short_name: `GatsbyJS`,
+        start_url: `/`,
+        background_color: `#f7f0eb`,
+        theme_color: `#a2466c`,
+        display: `standalone`,
+        icon: `src/images/icon.png`, // This path is relative to the root of the site.
+        cache_busting_mode: `none`, // `none`, `name` or `query`
+      },
+    },
+  ],
+}
+```
+
 ## Enable CORS using `crossorigin` attribute
 
 Add a `crossorigin` attribute to the manifest `<link rel="manifest" crossorigin="use-credentials" href="/manifest.webmanifest" />` link tag.
@@ -268,7 +308,8 @@ You can find more information about `crossorigin` on MDN.
 
 [https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes)
 
-```javascript:title=gatsby-config.js
+```js
+// in gatsby-config.js
 module.exports = {
   plugins: [
     {

diff --git a/packages/gatsby-plugin-manifest/package.json b/packages/gatsby-plugin-manifest/package.json
@@ -30,7 +30,7 @@
   "license": "MIT",
   "main": "index.js",
   "peerDependencies": {
-    "gatsby": "^2.0.0"
+    "gatsby": "^2.0.15"
   },
   "repository": "https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-manifest",
   "scripts": {

diff --git a/packages/gatsby-plugin-manifest/src/__tests__/__snapshots__/gatsby-node.js.snap b/packages/gatsby-plugin-manifest/src/__tests__/__snapshots__/gatsby-node.js.snap
@@ -1,5 +1,3 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Test plugin manifest options correctly works with default parameters 1`] = `"{\\"name\\":\\"GatsbyJS\\",\\"short_name\\":\\"GatsbyJS\\",\\"start_url\\":\\"/\\",\\"background_color\\":\\"#f7f0eb\\",\\"theme_color\\":\\"#a2466c\\",\\"display\\":\\"standalone\\",\\"icons\\":[{\\"src\\":\\"icons/icon-48x48.png\\",\\"sizes\\":\\"48x48\\",\\"type\\":\\"image/png\\"},{\\"src\\":\\"icons/icon-72x72.png\\",\\"sizes\\":\\"72x72\\",\\"type\\":\\"image/png\\"},{\\"src\\":\\"icons/icon-96x96.png\\",\\"sizes\\":\\"96x96\\",\\"type\\":\\"image/png\\"},{\\"src\\":\\"icons/icon-144x144.png\\",\\"sizes\\":\\"144x144\\",\\"type\\":\\"image/png\\"},{\\"src\\":\\"icons/icon-192x192.png\\",\\"sizes\\":\\"192x192\\",\\"type\\":\\"image/png\\"},{\\"src\\":\\"icons/icon-256x256.png\\",\\"sizes\\":\\"256x256\\",\\"type\\":\\"image/png\\"},{\\"src\\":\\"icons/icon-384x384.png\\",\\"sizes\\":\\"384x384\\",\\"type\\":\\"image/png\\"},{\\"src\\":\\"icons/icon-512x512.png\\",\\"sizes\\":\\"512x512\\",\\"type\\":\\"image/png\\"}]}"`;
-
-exports[`Test plugin manifest options fails on non existing icon 1`] = `"icon (non/existing/path) does not exist as defined in gatsby-config.js. Make sure the file exists relative to the root of the site."`;