Skip to content
This repository has been archived by the owner on Aug 10, 2022. It is now read-only.

Commit

Permalink
Updates to reflect the latest Workbox webpack plugin options. (#5677)
Browse files Browse the repository at this point in the history 
* Updates to reflect the latest Workbox webpack plugin options.

* Linting
  • Loading branch information
@jeffposnick
jeffposnick authored and Matt Gaunt committed Jan 19, 2018
1 parent 13571f0 commit 6bf2f55
Show file tree
Hide file tree
Showing 7 changed files with 338 additions and 260 deletions.
41 changes: 31 additions & 10 deletions src/content/en/tools/workbox/guides/_shared/common-generate-schema.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,21 +198,42 @@
supported by
<a href="/web/tools/workbox/reference-docs/prerelease/workbox.strategies#methods"><code>workbox.strategies</code></a>.
</p>
<p>
The <code>options</code> properties can be used to configure instances of the cache
expiration, cacheable response, and broadcast cache update plugins to apply to a given route.
</p>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">runtimeCaching: [{
// Match same-origin requests for URLs ending in .jpg:
urlPattern: /.jpg$/,
handler: 'cacheFirst',
// Any options provided will be used when
// creating the caching strategy.
// Match any same-origin request that contains 'api'.
urlPattern: /api/,
// Apply a network-first strategy.
handler: 'networkFirst',
options: {
cacheName: 'image-cache',
cacheExpiration: {
maxEntries: 10
}
}
// Fall back to the cache after 10 seconds.
networkTimeoutSeconds: 10,
// Use a custom cache name for this route.
cacheName: 'my-api-cache',
// Configure custom cache expiration.
expiration: {
maxEntries: 5,
maxAgeSeconds: 60,
},
// Configure which responses are considered cacheable.
cacheableResponse: {
statuses: [0, 200],
headers: {'x-test': 'true'},
},
// Configure the broadcast cache update plugin.
broadcastUpdate: {
channelName: 'my-update-channel',
},
// Add in any additional plugin logic you need.
plugins: [
{cacheDidUpdate: () => /* custom plugin code */}
],
},
}, {
// To match cross-origin requests, use a RegExp that matches
// the start of the origin:
Expand Down
121 changes: 121 additions & 0 deletions src/content/en/tools/workbox/guides/_shared/common-webpack.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
<tr>
<td>
<p>chunks</p>
</td>
<td>
<p>
<em>Optional <code>Array</code> of <code>String</code>, defaulting to <code>[]</code></em>
</p>
<p>
By default, Workbox will precache assets regardless of which <code>chunk</code> the asset is
part of.
</p>
<p>
If you would like to override this behavior via a whitelist, specify one or more
<code>chunk</code> names. Only assets belonging to those <code>chunk</code>s will be
precached; any assets belonging to another <code>chunk</code> or without a <code>chunk</code>
association will be skipped.
</p>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">// *Only* include assets that belong to these chunks:
chunks: ['chunk-name-1', 'chunk-name-2']</pre>
</td>
</tr>

<tr>
<td>
<p>exclude</p>
</td>
<td>
<p>
<em>Optional <code>Array</code> of <code>RegExp</code> or <code>String</code>,
defaulting to <code>[/\.map$/, /^manifest.*\.js(?:on)?$/]</code></em>
</p>
<p>
This allows you to specifically omit assets matching any of the provided criteria from being
included in the precache manifest. It provides a filename-based approach to filtering.
</p>
<p>
This filtering takes place <em>after</em> any <code>chunk</code>-based filtering is applied.
</p>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">// Exclude JPG and PNG assets from precaching:
exclude: [/\.jpg$/, /\.png$/]</pre>
</td>
</tr>

<tr>
<td>
<p>excludeChunks</p>
</td>
<td>
<p>
<em>Optional <code>Array</code> of <code>String</code>, defaulting to <code>[]</code></em>
</p>
<p>
By default, Workbox will precache all assets generated by the webpack compilation, regardless
of which <code>chunk</code> the asset is part of.
</p>
<p>
If you would like to override this behavior via a blacklist, specify one or more
<code>chunk</code> names. Any assets belonging to those <code>chunks</code> will be skipped.
</p>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">// Exclude assets that belong to these chunks:
excludeChunks: ['chunk-name-1', 'chunk-name-2']</pre>
</td>
</tr>

<tr>
<td>
<p>include</p>
</td>
<td>
<p>
<em>Optional <code>Array</code> of <code>RegExp</code> or <code>String</code></em>
</p>
<p>
This allows you to only include assets matching any of the provided criteria when creating the
precache manifest. It provides a filename-based approach to filtering.
</p>
<p>
This filtering takes place <em>after</em> any <code>chunk</code>-based filtering is applied.
</p>
<p>
In keeping with
<a href="https://webpack.js.org/configuration/module/#condition">webpack convention</a>,
the option `test` can be used as an alias/alternative to `include`.
</p>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">// Only include HTML and JS assets when precaching:
include: [/\.html$/, /\.js$/]</pre>
</td>
</tr>

<tr>
<td>
<p>swDest</p>
</td>
<td>
<p>
<em>Optional <code>String</code>, defaulting to `'service-worker.js'`</em>
</p>
<p>
The path and filename of the service worker file that will be created by the build process,
relative to the webpack output directory.
</p>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">swDest: 'custom-sw-name.js'</pre>
</td>
</tr>

46 changes: 27 additions & 19 deletions src/content/en/tools/workbox/guides/_shared/generate-sw-schema.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,29 +48,37 @@

<tr>
<td>
<p>importWorkboxFromCDN</p>
<p>importWorkboxFrom</p>
</td>
<td>
<p>
<em>Optional <code>Boolean</code>, defaulting to <code>true</code></em>
</p>
<p>
If true, the <code>workbox-sw.js</code> runtime and associated libraries will be automatically
imported into the generated service worker from the official CDN URL.
</p>
<p>
If false, the <code>workbox-sw.js</code> runtime and associated libraries will be copied
locally into a versioned subdirectory of <code>swDest</code>.
</p>
<p>
Functionality is identical regardless of which option is used; setting this to
<code>false</code> is recommended for developers who would prefer not to rely on the official
CDN as a dependency.
</p>
<em>Optional <code>String</code>, defaulting to 'cdn'</em>
</p>
<p>
Valid values are <code>'cdn'</code>, <code>'local'</code>, and <code>'disabled</code>.
</p>
<ul>
<li>
<code>'cdn'</code>, the default, will use a URL for the Workbox runtime libraries hosted on
a highly-available <a href="https://cloud.google.com/storage/">Google Cloud Storage</a>
instance.
</li>
<li>
<code>'local'</code> will copy <em>all</em> of the Workbox runtime libraries into a
versioned directory alongside your generated service worker, and configure the service
worker to use those local copies. This option is provided for developers who would prefer
to host everything themselves and not rely on the Google Cloud Storage CDN.
</li>
<li>
<code>'disabled'</code> will opt-out automatic behavior. It's up to you to host a local copy
of the Workbox libraries at your preferred URL, and to pass in the correct path to
<code>workbox-sw.js</code> via the <code>importScripts</code> configuration option.
</li>
</ul>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">importWorkboxFromCDN: false</pre>
<pre class="prettyprint">importWorkboxFrom: 'local'</pre>
</td>
</tr>

Expand All @@ -83,8 +91,8 @@
<em>Required <code>String</code></em>
</p>
<p>
The path to the final service worker file that will be created by the build process, relative
to the current working directory.
The path and filename of the service worker file that will be created by the build process,
relative to the current working directory.
</p>
<p>
<strong>Example:</strong>
Expand Down
36 changes: 36 additions & 0 deletions src/content/en/tools/workbox/guides/_shared/webpack-generate-sw.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<tr>
<td>
<p>importWorkboxFrom</p>
</td>
<td>
<p>
<em>Optional <code>String</code>, defaulting to 'cdn'</em>
</p>
<ul>
<li>
<code>'cdn'</code>, the default, will use a URL for the Workbox runtime libraries hosted on
a highly-available <a href="https://cloud.google.com/storage/">Google Cloud Storage</a>
instance.
</li>
<li>
<code>'local'</code> will copy <em>all</em> of the Workbox runtime libraries into a
versioned directory alongside your generated service worker, and configure the service
worker to use those local copies. This option is provided for developers who would prefer
to host everything themselves and not rely on the Google Cloud Storage CDN.
</li>
<li>
<code>'disabled'</code> will opt-out automatic behavior. It's up to you to host a local copy
of the Workbox libraries at your preferred URL, and to pass in the correct path to
<code>workbox-sw.js</code> via the <code>importScripts</code> configuration option.
</li>
<li>
Passing in a string corresponding to the webpack chunk name containing a custom Workbox
runtime library bundle is also supported.
</li>
</ul>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">importWorkboxFrom: 'name-of-workbox-chunk'</pre>
</td>
</tr>
64 changes: 64 additions & 0 deletions src/content/en/tools/workbox/guides/_shared/webpack-inject-manifest.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
<tr>
<td>
<p>importWorkboxFrom</p>
</td>
<td>
<p>
<em>Optional <code>String</code>, defaulting to 'cdn'</em>
</p>
<ul>
<li>
<code>'cdn'</code>, the default, will use a URL for the Workbox runtime libraries hosted on
a highly-available <a href="https://cloud.google.com/storage/">Google Cloud Storage</a>
instance.
</li>
<li>
<code>'disabled'</code> will opt-out automatic behavior. It's up to you to host a local copy
of the Workbox libraries at your preferred URL, and ensure that they are loaded via
<code>importScripts()</code>.
</li>
<li>
Passing in a string corresponding to the webpack chunk name containing a custom Workbox
runtime library bundle is also supported.
</li>
</ul>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">importWorkboxFrom: 'name-of-workbox-chunk'</pre>
</td>
</tr>


<tr>
<td>
<p>swSrc</p>
</td>
<td>
<p>
<em>Required <code>String</code></em>
</p>
<p>
If <code>swSrc</code> is left <code>undefined</code>, the plugin will generate a brand-new
service worker file as part of each compilation, configured based on the options provided.
</p>
<p>
If <code>swSrc</code> is provided, the plugin assumes it refers to an existing service worker
file. The code in this file will be included as-is, with one addition: a call to
<a href="https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/importScripts" class="external"><code>importScripts()</code></a>
will be prepended to the existing code, automatically configured to import the generated
<code>manifestFilename</code> file, as well as the necessary Workbox runtime library code.
</p>
<p>
When providing <code>swSrc</code>, your service worker code can reference the
<code>self.__precacheManifest</code> variable to obtain a list of
<a href="/web/tools/workbox/reference-docs/prerelease/module-workbox-build#.ManifestEntry"><code>ManifestEntry</code>s</a>
obtained as part of the compilation:
<code>workbox.precaching.precacheAndRoute(self.__precacheManifest)</code>
</p>
<p>
<strong>Example:</strong>
</p>
<pre class="prettyprint">swSrc: path.join('dev', 'sw.js')</pre>
</td>
</tr>
Loading

0 comments on commit 6bf2f55

Please sign in to comment.