Adds a dontCacheBustUrlsMatching option.

README.md

@@ -31,6 +31,7 @@ The full documentation is in this README, and the
   - [Options Parameter](#options-parameter)
     - [cacheId [String]](#cacheid-string)
     - [directoryIndex [String]](#directoryindex-string)
+    - [dontCacheBustUrlsMatching [Regex]](#dontcachebusturlsmatching-regex)
     - [dynamicUrlToDependencies [Object⟨String,Array⟨String⟩⟩]](#dynamicurltodependencies-objectstringarraystring)
     - [handleFetch [boolean]](#handlefetch-boolean)
     - [ignoreUrlParametersMatching [Array⟨Regex⟩]](#ignoreurlparametersmatching-arrayregex)
@@ -260,6 +261,33 @@ mappings between a directory URL and a corresponding file.
 
 _Default_: `'index.html'`
 
+#### dontCacheBustUrlsMatching [Regex]
+It's very important that the requests `sw-precache` makes to populate your cache
+result in the most up-to-date version of a resource at a given URL. Requests
+that are fulfilled with out-of-date responses (like those found in your
+browser's HTTP cache) can end up being read from the service worker's cache
+indefinitely. Jake Archibald's [blog post](https://jakearchibald.com/2016/caching-best-practices/#a-service-worker-can-extend-the-life-of-these-bugs)
+provides more context about this problem.
+
+In the interest of avoiding that scenario, `sw-precache` will, by default,
+append a cache-busting parameter to the end of each URL it requests when
+populating or updating its cache. Developers who are explicitly doing "the right
+thing" when it comes to setting HTTP caching headers on their responses might
+want to opt out of this cache-busting. For example, if all of your static
+resources already include versioning information in their URLs (via a tool like
+[`gulp-rev`](https://github.com/sindresorhus/gulp-rev)), and are served with
+long-lived HTTP caching headers, then the extra cache-busting URL parameter
+is not needed, and can be safely excluded.
+
+`dontCacheBustUrlsMatching` gives you a way of opting-in to skipping the cache
+busting behavior for a subset of your URLs (or all of them, if a catch-all value
+like `/./` is used).
+If set, then each URL that's prefetched will be matched against this value.
+If there's a match, then the URL will be prefetched as-is, without an additional
+cache-busting URL parameter appended.
+
+_Default_: not set
+
 #### dynamicUrlToDependencies [Object⟨String,Array⟨String⟩⟩]  
 Maps a dynamic URL string to an array of all the files that URL's contents
 depend on. E.g., if the contents of `/pages/home` are generated server-side via

lib/functions.js

@@ -63,11 +63,19 @@ module.exports = {
     });
   },
 
-  createCacheKey: function(originalUrl, paramName, paramValue) {
+  createCacheKey: function(originalUrl, paramName, paramValue,
+                           dontCacheBustUrlsMatching) {
     // Create a new URL object to avoid modifying originalUrl.
     var url = new URL(originalUrl);
-    url.search += (url.search ? '&' : '') +
-      encodeURIComponent(paramName) + '=' + encodeURIComponent(paramValue);
+
+    // If dontCacheBustUrlsMatching is not set, or if we don't have a match,
+    // then add in the extra cache-busting URL parameter.
+    if (!dontCacheBustUrlsMatching ||
+        !(url.toString().match(dontCacheBustUrlsMatching))) {
+      url.search += (url.search ? '&' : '') +
+        encodeURIComponent(paramName) + '=' + encodeURIComponent(paramValue);
+    }
+
     return url.toString();
   }
 };

lib/sw-precache.js

@@ -79,6 +79,7 @@ function generate(params, callback) {
     params = defaults(params || {}, {
       cacheId: '',
       directoryIndex: 'index.html',
+      dontCacheBustUrlsMatching: null,
       dynamicUrlToDependencies: {},
       handleFetch: true,
       ignoreUrlParametersMatching: [/^utm_/],
@@ -245,6 +246,7 @@ function generate(params, callback) {
         cacheId: params.cacheId,
         // Ensure that anything false is translated into '', since this will be treated as a string.
         directoryIndex: params.directoryIndex || '',
+        dontCacheBustUrlsMatching: params.dontCacheBustUrlsMatching || false,
         externalFunctions: externalFunctions,
         handleFetch: params.handleFetch,
         ignoreUrlParametersMatching: params.ignoreUrlParametersMatching,

service-worker.tmpl

@@ -41,7 +41,7 @@ var urlsToCacheKeys = new Map(
     var relativeUrl = item[0];
     var hash = item[1];
     var absoluteUrl = new URL(relativeUrl, self.location);
-    var cacheKey = createCacheKey(absoluteUrl, hashParamName, hash);
+    var cacheKey = createCacheKey(absoluteUrl, hashParamName, hash, <%= dontCacheBustUrlsMatching %>);
     return [absoluteUrl.toString(), cacheKey];
   })
 );

test/test.js

@@ -405,4 +405,18 @@ describe('createCacheKey', function() {
     assert.strictEqual(cacheKey, 'http://example.com/test/path?existing=value&name=value');
     done();
   });
+
+  it('should not append the parameter when the URL matches the exclusion pattern', function(done) {
+    var url = 'http://example.com/test/path?existing=value';
+    var cacheKey = externalFunctions.createCacheKey(url, 'name', 'value', /example/);
+    assert.strictEqual(cacheKey, url);
+    done();
+  });
+
+  it('should append the parameter when the URL does not match the exclusion pattern', function(done) {
+    var url = 'http://example.com/test/path?existing=value';
+    var cacheKey = externalFunctions.createCacheKey(url, 'name', 'value', /no_match/);
+    assert.strictEqual(cacheKey, 'http://example.com/test/path?existing=value&name=value');
+    done();
+  });
 });