When service workers were first introduced, a set of common caching strategies
emerged. A caching strategy is a pattern that determines how a service worker
generates a response after receiving a fetch event.
`workbox-strategies` provides the most common caching strategies so it's easy to
apply them in your service worker.
We won't go into much detail outside of the strategies supported by Workbox,
but you can [learn more in the Offline Cookbook](https://web.dev/articles/offline-cookbook).
## Using Strategies
In the following examples, we'll show you how to use the Workbox caching
strategies with `workbox-routing`. There are some options you can define with
each strategy that are covered in the
[Configuring Strategies section of this doc](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#configuring_strategies).
In the [Advanced Usage section](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#advanced_usage), we'll cover how you can use
the caching strategies directly without `workbox-routing`.
### Stale-While-Revalidate
The [stale-while-revalidate](https://web.dev/articles/offline-cookbook#stale_while_revalidate)
pattern allows you to respond to the request as quickly as possible with a
cached response if available, falling back to the network request if it's
not cached. The network request is then used to update the cache. As opposed to
[some implementations](https://github.com/GoogleChrome/workbox/issues/2807)
of stale-while-revalidate, this strategy will always make a revalidation request,
regardless of the age of the cached response.
This is a fairly common strategy where having the most up-to-date resource
is not vital to the application.
```javascript
import {registerRoute} from 'workbox-routing';
import {StaleWhileRevalidate} from 'workbox-strategies';
registerRoute(
({url}) => url.pathname.startsWith('/images/avatars/'),
new StaleWhileRevalidate()
);
```
### Cache First (Cache Falling Back to Network)
Offline web apps will rely heavily on the cache, but for assets that are
non-critical and can be gradually cached, a
[cache first](https://web.dev/articles/offline-cookbook#cache_falling_back_to_network)
is the best option.
If there is a Response in the cache, the Request will be fulfilled using the
cached response and the network will not be used at all. If there isn't a cached
response, the Request will be fulfilled by a network request and the response
will be cached so that the next request is served directly from the cache.
```javascript
import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
registerRoute(({request}) => request.destination === 'style', new CacheFirst());
```
### Network First (Network Falling Back to Cache)
For requests that are updating frequently, the
[network first](https://web.dev/articles/offline-cookbook#network_falling_back_to_cache)
strategy is the ideal solution. By default, it will try to fetch the latest
response from the network. If the request is successful, it'll put the response
in the cache. If the network fails to return a response, the cached response
will be used.
```javascript
import {registerRoute} from 'workbox-routing';
import {NetworkFirst} from 'workbox-strategies';
registerRoute(
({url}) => url.pathname.startsWith('/social-timeline/'),
new NetworkFirst()
);
```
### Network Only
If you require specific requests to be fulfilled from the network, the
[network only](https://web.dev/articles/offline-cookbook#network_only)
is the strategy to use.
```javascript
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';
registerRoute(({url}) => url.pathname.startsWith('/admin/'), new NetworkOnly());
```
### Cache Only
The [cache only](https://web.dev/articles/offline-cookbook#cache_only)
strategy ensures that responses are obtained from a cache. This is less common
in workbox, but can be useful if you have your own precaching step.
```javascript
import {registerRoute} from 'workbox-routing';
import {CacheOnly} from 'workbox-strategies';
registerRoute(({url}) => url.pathname.startsWith('/app/v2/'), new CacheOnly());
```
## Configuring Strategies
All of the strategies allow you to configure:
- The name of the cache to use in the strategy.
- Cache expiration restrictions to use in the strategy.
- An array of plugins that will have their lifecycle methods called when fetching and caching a request.
### Changing the Cache Used by a Strategy
You can change the cache a strategy used by supplying a cache name. This is
useful if you want to separate out your assets to help with debugging.
```javascript
import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
registerRoute(
({request}) => request.destination === 'image',
new CacheFirst({
cacheName: 'image-cache',
})
);
```
### Using Plugins
Workbox comes with a set of plugins that can be used with these strategies.
- [workbox-background-sync](https://developer.chrome.com/docs/workbox/modules/workbox-background-sync.md.txt)
- [workbox-broadcast-update](https://developer.chrome.com/docs/workbox/modules/workbox-broadcast-update.md.txt)
- [workbox-cacheable-response](https://developer.chrome.com/docs/workbox/modules/workbox-cacheable-response.md.txt)
- [workbox-expiration](https://developer.chrome.com/docs/workbox/modules/workbox-expiration.md.txt)
- [workbox-range-requests](https://developer.chrome.com/docs/workbox/modules/workbox-range-requests.md.txt)
To use any of these plugins (or a custom plugin), you just need to pass in
instances to the `plugins` option.
```javascript
import {registerRoute} from 'workbox-routing';
import {CacheFirst} from 'workbox-strategies';
import {ExpirationPlugin} from 'workbox-expiration';
registerRoute(
({request}) => request.destination === 'image',
new CacheFirst({
cacheName: 'image-cache',
plugins: [
new ExpirationPlugin({
// Only cache requests for a week
maxAgeSeconds: 7 * 24 * 60 * 60,
// Only cache 10 requests.
maxEntries: 10,
}),
],
})
);
```
## Custom Strategies
In addition to configuring strategies, Workbox allows you to create your own custom strategies.
This can be done by importing and extending the `Strategy` base class from `workbox-strategies`:
```javascript
import {Strategy} from 'workbox-strategies';
class NewStrategy extends Strategy {
_handle(request, handler) {
// Define handling logic here
}
}
```
In this example, `handle()` is used as a request strategy to define specific handling logic. There
are two request strategies that can be used:
- `handle()`: Perform a request strategy and return a `Promise` that will resolve with a `Response`, invoking all [relevant plugin callbacks](https://developer.chrome.com/docs/workbox/using-plugins.md.txt#methods_for_custom_plugins).
- `handleAll()`: Similar to `handle()`, but returns two `Promise` objects. The first is equivalent to what `handle()` returns and the second will resolve when promises that were added to `event.waitUntil()` within the strategy have completed.
Both request strategies are invoked with two parameters:
- `request`: The `Request` the strategy will return a response for.
- `handler`: A `StrategyHandler` instance automatically created for the current strategy.
### Creating A New Strategy
The following is an example of a new strategy that re-implements the behavior of `NetworkOnly`:
```javascript
class NewNetworkOnlyStrategy extends Strategy {
_handle(request, handler) {
return handler.fetch(request);
}
}
```
Notice how `handler.fetch()` is called instead of the native `fetch` method. The `StrategyHandler`
class provides a number of fetch and cache actions that can be used whenever `handle()` or
`handleAll()` is used:
- `fetch`: Fetches a given request, and invokes the `requestWillFetch()`, `fetchDidSucceed()`, and `fetchDidFail()` plugin lifecycle methods
- `cacheMatch`: Matches a request from the cache, and invokes the `cacheKeyWillBeUsed()` and `cachedResponseWillBeUsed()` plugin lifecycle methods
- `cachePut`: Puts a request/response pair in the cache, and invokes the `cacheKeyWillBeUsed()`, `cacheWillUpdate()`, and `cacheDidUpdate()` plugin lifecycle methods
- `fetchAndCachePut`: Calls `fetch()` and runs `cachePut()` in the background on the response generated by `fetch()`.
- `hasCallback`: Takes a callback as input and returns true if the strategy has at least one plugin with the given callback.
- `runCallbacks`: Runs all plugin callbacks matching a given name, in order, passing a given param object (merged with the current plugin state) as the only argument.
- `iterateCallbacks`: Accepts a callback and returns an iterable of matching plugin callbacks, where each callback is wrapped with the current handler state (i.e. when you call each callback, whatever object parameter you pass it will be merged with the plugin's current state).
- `waitUntil`: Adds a promise to the extend lifetime promises of the event associated with the request being handled (usually a `FetchEvent`).
- `doneWaiting`: Returns a promise that resolves once all promises passed to `waitUntil()` have settled.
- `destroy`: Stops running the strategy and immediately resolves any pending `waitUntil()` promises.
> [!NOTE]
> **Note:** Refer to the [source
> implementation](https://github.com/GoogleChrome/workbox/blob/6d38919ebbc9664327e19ff00302d805c8166170/packages/workbox-strategies/src/StrategyHandler.ts) of `StrategyHandler` to see all the parameters accepted by each action
### Custom Cache Network Race Strategy
The following example is based on
[cache-network-race](https://jakearchibald.com/2014/offline-cookbook/#cache--network-race) from the
Offline Cookbook (which Workbox does not provide), but goes a step further and always updates the
cache after a successful network request. This in an example of a more complex strategy that uses
multiple actions.
```javascript
import {Strategy} from 'workbox-strategies';
class CacheNetworkRace extends Strategy {
_handle(request, handler) {
const fetchAndCachePutDone = handler.fetchAndCachePut(request);
const cacheMatchDone = handler.cacheMatch(request);
return new Promise((resolve, reject) => {
fetchAndCachePutDone.then(resolve);
cacheMatchDone.then(response => response && resolve(response));
// Reject if both network and cache error or find no response.
Promise.allSettled([fetchAndCachePutDone, cacheMatchDone]).then(
results => {
const [fetchAndCachePutResult, cacheMatchResult] = results;
if (
fetchAndCachePutResult.status === 'rejected' &&
!cacheMatchResult.value
) {
reject(fetchAndCachePutResult.reason);
}
}
);
});
}
}
```
## Advanced Usage
If you want to use the strategies in your own fetch event logic, you can
use the strategy classes to run a request through a specific strategy.
For example, to use the stale-while-revalidate strategy, you can do the
following:
```javascript
self.addEventListener('fetch', event => {
const {request} = event;
const url = new URL(request.url);
if (url.origin === location.origin && url.pathname === '/') {
event.respondWith(new StaleWhileRevalidate().handle({event, request}));
}
});
```
You can find the list of available classes in the
[workbox-strategies reference docs](https://developer.chrome.com/docs/workbox/reference/workbox-strategies).
## Types
### CacheFirst
An implementation of a [cache-first](https://developer.chrome.com/docs/workbox/caching-strategies-overview.md.txt#cache-first-falling-back-to-network)
request strategy.
A cache first strategy is useful for assets that have been revisioned,
such as URLs like `/styles/example.a8f5f1.css`, since they
can be cached for long periods of time.
If the network request fails, and there is no cache match, this will throw
a `WorkboxError` exception.
#### Properties
- constructor void
Creates a new instance of the strategy and sets all documented option
properties as public instance properties.
Note: if a custom strategy class extends the base Strategy class and does
not need more than these properties, it does not need to define its own
constructor.
The `constructor` function looks like:
```typescript
(options?: StrategyOptions) => {...}
```
- options [StrategyOptions](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyOptions) optional
- returns[CacheFirst](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-CacheFirst)
- cacheName string
- fetchOptions RequestInit optional
- matchOptions CacheQueryOptions optional
- plugins [WorkboxPlugin](https://developer.chrome.com/docs/workbox/workbox-core/#type-WorkboxPlugin)\[\]
- _awaitComplete void
The `_awaitComplete` function looks like:
```typescript
(responseDone: Promise, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- responseDone Promise\
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- _getResponse void
The `_getResponse` function looks like:
```typescript
(handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- handle void
Perform a request strategy and returns a `Promise` that will resolve with
a `Response`, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox
[`workbox-routing.Route`](https://developer.chrome.com/docs/workbox/workbox-routing/#type-Route), this method is automatically
called when the route matches.
Alternatively, this method can be used in a standalone `FetchEvent`
listener by passing it to `event.respondWith()`.
The `handle` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returnsPromise\
- handleAll void
Similar to `workbox-strategies.Strategy~handle`, but
instead of just returning a `Promise` that resolves to a `Response` it
it will return an tuple of `[response, done]` promises, where the former
(`response`) is equivalent to what `handle()` returns, and the latter is a
Promise that will resolve once any promises that were added to
`event.waitUntil()` as part of performing the strategy have completed.
You can await the `done` promise to ensure any extra work performed by
the strategy (usually caching responses) completes successfully.
The `handleAll` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returns\[Promise\, Promise\\]
A tuple of \[response, done\]
promises that can be used to determine when the response resolves as
well as when the handler has completed all its work.
### CacheOnly
An implementation of a [cache-only](https://developer.chrome.com/docs/workbox/caching-strategies-overview.md.txt#cache-only)
request strategy.
This class is useful if you want to take advantage of any
[Workbox plugins](https://developer.chrome.com/docs/workbox/using-plugins.md.txt).
If there is no cache match, this will throw a `WorkboxError` exception.
#### Properties
- constructor void
Creates a new instance of the strategy and sets all documented option
properties as public instance properties.
Note: if a custom strategy class extends the base Strategy class and does
not need more than these properties, it does not need to define its own
constructor.
The `constructor` function looks like:
```typescript
(options?: StrategyOptions) => {...}
```
- options [StrategyOptions](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyOptions) optional
- returns[CacheOnly](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-CacheOnly)
- cacheName string
- fetchOptions RequestInit optional
- matchOptions CacheQueryOptions optional
- plugins [WorkboxPlugin](https://developer.chrome.com/docs/workbox/workbox-core/#type-WorkboxPlugin)\[\]
- _awaitComplete void
The `_awaitComplete` function looks like:
```typescript
(responseDone: Promise, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- responseDone Promise\
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- _getResponse void
The `_getResponse` function looks like:
```typescript
(handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- handle void
Perform a request strategy and returns a `Promise` that will resolve with
a `Response`, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox
[`workbox-routing.Route`](https://developer.chrome.com/docs/workbox/workbox-routing/#type-Route), this method is automatically
called when the route matches.
Alternatively, this method can be used in a standalone `FetchEvent`
listener by passing it to `event.respondWith()`.
The `handle` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returnsPromise\
- handleAll void
Similar to `workbox-strategies.Strategy~handle`, but
instead of just returning a `Promise` that resolves to a `Response` it
it will return an tuple of `[response, done]` promises, where the former
(`response`) is equivalent to what `handle()` returns, and the latter is a
Promise that will resolve once any promises that were added to
`event.waitUntil()` as part of performing the strategy have completed.
You can await the `done` promise to ensure any extra work performed by
the strategy (usually caching responses) completes successfully.
The `handleAll` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returns\[Promise\, Promise\\]
A tuple of \[response, done\]
promises that can be used to determine when the response resolves as
well as when the handler has completed all its work.
### NetworkFirst
An implementation of a
[network first](https://developer.chrome.com/docs/workbox/caching-strategies-overview.md.txt#network-first-falling-back-to-cache)
request strategy.
By default, this strategy will cache responses with a 200 status code as
well as [opaque responses](https://developer.chrome.com/docs/workbox/caching-resources-during-runtime.md.txt#opaque-responses).
Opaque responses are are cross-origin requests where the response doesn't
support [CORS](https://enable-cors.org/).
If the network request fails, and there is no cache match, this will throw
a `WorkboxError` exception.
#### Properties
- constructor void
The `constructor` function looks like:
```typescript
(options?: NetworkFirstOptions) => {...}
```
- options [NetworkFirstOptions](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-NetworkFirstOptions) optional
- returns[NetworkFirst](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-NetworkFirst)
- cacheName string
- fetchOptions RequestInit optional
- matchOptions CacheQueryOptions optional
- plugins [WorkboxPlugin](https://developer.chrome.com/docs/workbox/workbox-core/#type-WorkboxPlugin)\[\]
- _awaitComplete void
The `_awaitComplete` function looks like:
```typescript
(responseDone: Promise, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- responseDone Promise\
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- _getResponse void
The `_getResponse` function looks like:
```typescript
(handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- handle void
Perform a request strategy and returns a `Promise` that will resolve with
a `Response`, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox
[`workbox-routing.Route`](https://developer.chrome.com/docs/workbox/workbox-routing/#type-Route), this method is automatically
called when the route matches.
Alternatively, this method can be used in a standalone `FetchEvent`
listener by passing it to `event.respondWith()`.
The `handle` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returnsPromise\
- handleAll void
Similar to `workbox-strategies.Strategy~handle`, but
instead of just returning a `Promise` that resolves to a `Response` it
it will return an tuple of `[response, done]` promises, where the former
(`response`) is equivalent to what `handle()` returns, and the latter is a
Promise that will resolve once any promises that were added to
`event.waitUntil()` as part of performing the strategy have completed.
You can await the `done` promise to ensure any extra work performed by
the strategy (usually caching responses) completes successfully.
The `handleAll` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returns\[Promise\, Promise\\]
A tuple of \[response, done\]
promises that can be used to determine when the response resolves as
well as when the handler has completed all its work.
### NetworkFirstOptions
#### Properties
- cacheName string optional
- fetchOptions RequestInit optional
- matchOptions CacheQueryOptions optional
- networkTimeoutSeconds number optional
- plugins [WorkboxPlugin](https://developer.chrome.com/docs/workbox/workbox-core/#type-WorkboxPlugin)\[\] optional
### NetworkOnly
An implementation of a
[network-only](https://developer.chrome.com/docs/workbox/caching-strategies-overview.md.txt#network-only)
request strategy.
This class is useful if you want to take advantage of any
[Workbox plugins](https://developer.chrome.com/docs/workbox/using-plugins.md.txt).
If the network request fails, this will throw a `WorkboxError` exception.
#### Properties
- constructor void
The `constructor` function looks like:
```typescript
(options?: NetworkOnlyOptions) => {...}
```
- options [NetworkOnlyOptions](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-NetworkOnlyOptions) optional
- returns[NetworkOnly](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-NetworkOnly)
- cacheName string
- fetchOptions RequestInit optional
- matchOptions CacheQueryOptions optional
- plugins [WorkboxPlugin](https://developer.chrome.com/docs/workbox/workbox-core/#type-WorkboxPlugin)\[\]
- _awaitComplete void
The `_awaitComplete` function looks like:
```typescript
(responseDone: Promise, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- responseDone Promise\
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- _getResponse void
The `_getResponse` function looks like:
```typescript
(handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- handle void
Perform a request strategy and returns a `Promise` that will resolve with
a `Response`, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox
[`workbox-routing.Route`](https://developer.chrome.com/docs/workbox/workbox-routing/#type-Route), this method is automatically
called when the route matches.
Alternatively, this method can be used in a standalone `FetchEvent`
listener by passing it to `event.respondWith()`.
The `handle` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returnsPromise\
- handleAll void
Similar to `workbox-strategies.Strategy~handle`, but
instead of just returning a `Promise` that resolves to a `Response` it
it will return an tuple of `[response, done]` promises, where the former
(`response`) is equivalent to what `handle()` returns, and the latter is a
Promise that will resolve once any promises that were added to
`event.waitUntil()` as part of performing the strategy have completed.
You can await the `done` promise to ensure any extra work performed by
the strategy (usually caching responses) completes successfully.
The `handleAll` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returns\[Promise\, Promise\\]
A tuple of \[response, done\]
promises that can be used to determine when the response resolves as
well as when the handler has completed all its work.
### NetworkOnlyOptions
#### Properties
- fetchOptions RequestInit optional
- networkTimeoutSeconds number optional
- plugins [WorkboxPlugin](https://developer.chrome.com/docs/workbox/workbox-core/#type-WorkboxPlugin)\[\] optional
### StaleWhileRevalidate
An implementation of a
[stale-while-revalidate](https://developer.chrome.com/docs/workbox/caching-strategies-overview.md.txt#stale-while-revalidate)
request strategy.
Resources are requested from both the cache and the network in parallel.
The strategy will respond with the cached version if available, otherwise
wait for the network response. The cache is updated with the network response
with each successful request.
By default, this strategy will cache responses with a 200 status code as
well as [opaque responses](https://developer.chrome.com/docs/workbox/caching-resources-during-runtime.md.txt#opaque-responses).
Opaque responses are cross-origin requests where the response doesn't
support [CORS](https://enable-cors.org/).
If the network request fails, and there is no cache match, this will throw
a `WorkboxError` exception.
#### Properties
- constructor void
The `constructor` function looks like:
```typescript
(options?: StrategyOptions) => {...}
```
- options [StrategyOptions](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyOptions) optional
- returns[StaleWhileRevalidate](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StaleWhileRevalidate)
- cacheName string
- fetchOptions RequestInit optional
- matchOptions CacheQueryOptions optional
- plugins [WorkboxPlugin](https://developer.chrome.com/docs/workbox/workbox-core/#type-WorkboxPlugin)\[\]
- _awaitComplete void
The `_awaitComplete` function looks like:
```typescript
(responseDone: Promise, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- responseDone Promise\
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- _getResponse void
The `_getResponse` function looks like:
```typescript
(handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- handle void
Perform a request strategy and returns a `Promise` that will resolve with
a `Response`, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox
[`workbox-routing.Route`](https://developer.chrome.com/docs/workbox/workbox-routing/#type-Route), this method is automatically
called when the route matches.
Alternatively, this method can be used in a standalone `FetchEvent`
listener by passing it to `event.respondWith()`.
The `handle` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returnsPromise\
- handleAll void
Similar to `workbox-strategies.Strategy~handle`, but
instead of just returning a `Promise` that resolves to a `Response` it
it will return an tuple of `[response, done]` promises, where the former
(`response`) is equivalent to what `handle()` returns, and the latter is a
Promise that will resolve once any promises that were added to
`event.waitUntil()` as part of performing the strategy have completed.
You can await the `done` promise to ensure any extra work performed by
the strategy (usually caching responses) completes successfully.
The `handleAll` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returns\[Promise\, Promise\\]
A tuple of \[response, done\]
promises that can be used to determine when the response resolves as
well as when the handler has completed all its work.
### Strategy
An abstract base class that all other strategy classes must extend from:
#### Properties
- constructor void
Creates a new instance of the strategy and sets all documented option
properties as public instance properties.
Note: if a custom strategy class extends the base Strategy class and does
not need more than these properties, it does not need to define its own
constructor.
The `constructor` function looks like:
```typescript
(options?: StrategyOptions) => {...}
```
- options [StrategyOptions](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyOptions) optional
- returns[Strategy](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-Strategy)
- cacheName string
- fetchOptions RequestInit optional
- matchOptions CacheQueryOptions optional
- plugins [WorkboxPlugin](https://developer.chrome.com/docs/workbox/workbox-core/#type-WorkboxPlugin)\[\]
- _awaitComplete void
The `_awaitComplete` function looks like:
```typescript
(responseDone: Promise, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- responseDone Promise\
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- _getResponse void
The `_getResponse` function looks like:
```typescript
(handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}
```
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- request Request
- event ExtendableEvent
- returnsPromise\
- _handle void
The `_handle` function looks like:
```typescript
(request: Request, handler: StrategyHandler) => {...}
```
- request Request
- handler [StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- returnsPromise\
- handle void
Perform a request strategy and returns a `Promise` that will resolve with
a `Response`, invoking all relevant plugin callbacks.
When a strategy instance is registered with a Workbox
[`workbox-routing.Route`](https://developer.chrome.com/docs/workbox/workbox-routing/#type-Route), this method is automatically
called when the route matches.
Alternatively, this method can be used in a standalone `FetchEvent`
listener by passing it to `event.respondWith()`.
The `handle` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returnsPromise\
- handleAll void
Similar to `workbox-strategies.Strategy~handle`, but
instead of just returning a `Promise` that resolves to a `Response` it
it will return an tuple of `[response, done]` promises, where the former
(`response`) is equivalent to what `handle()` returns, and the latter is a
Promise that will resolve once any promises that were added to
`event.waitUntil()` as part of performing the strategy have completed.
You can await the `done` promise to ensure any extra work performed by
the strategy (usually caching responses) completes successfully.
The `handleAll` function looks like:
```typescript
(options: FetchEvent | HandlerCallbackOptions) => {...}
```
- options FetchEvent \| [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
A `FetchEvent` or an object with the
properties listed below.
- returns\[Promise\, Promise\\]
A tuple of \[response, done\]
promises that can be used to determine when the response resolves as
well as when the handler has completed all its work.
### StrategyHandler
A class created every time a Strategy instance calls
`workbox-strategies.Strategy~handle` or
`workbox-strategies.Strategy~handleAll` that wraps all fetch and
cache actions around plugin callbacks and keeps track of when the strategy
is "done" (i.e. all added `event.waitUntil()` promises have resolved).
#### Properties
- constructor void
Creates a new instance associated with the passed strategy and event
that's handling the request.
The constructor also initializes the state that will be passed to each of
the plugins handling this request.
The `constructor` function looks like:
```typescript
(strategy: Strategy, options: HandlerCallbackOptions) => {...}
```
- strategy [Strategy](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-Strategy)
- options [HandlerCallbackOptions](https://developer.chrome.com/docs/workbox/workbox-core/#type-HandlerCallbackOptions)
- returns[StrategyHandler](https://developer.chrome.com/docs/workbox/modules/workbox-strategies.md.txt#type-StrategyHandler)
- event ExtendableEvent
- params any optional
- request Request
- url URL optional
- cacheMatch void
Matches a request from the cache (and invokes any applicable plugin
callback methods) using the `cacheName`, `matchOptions`, and `plugins`
defined on the strategy object.
The following plugin lifecycle methods are invoked when using this method:
- cacheKeyWillBeUsed()
- cachedResponseWillBeUsed()
The `cacheMatch` function looks like:
```typescript
(key: RequestInfo) => {...}
```
- key RequestInfo
The Request or URL to use as the cache key.
- returnsPromise\
A matching response, if found.
- cachePut void
Puts a request/response pair in the cache (and invokes any applicable
plugin callback methods) using the `cacheName` and `plugins` defined on
the strategy object.
The following plugin lifecycle methods are invoked when using this method:
- cacheKeyWillBeUsed()
- cacheWillUpdate()
- cacheDidUpdate()
The `cachePut` function looks like:
```typescript
(key: RequestInfo, response: Response) => {...}
```
- key RequestInfo
The request or URL to use as the cache key.
- response Response
The response to cache.
- returnsPromise\
`false` if a cacheWillUpdate caused the response
not be cached, and `true` otherwise.
- destroy void
Stops running the strategy and immediately resolves any pending
`waitUntil()` promises.
The `destroy` function looks like:
```typescript
() => {...}
```
- doneWaiting void
Returns a promise that resolves once all promises passed to
`workbox-strategies.StrategyHandler~waitUntil`
have settled.
Note: any work done after `doneWaiting()` settles should be manually
passed to an event's `waitUntil()` method (not this handler's
`waitUntil()` method), otherwise the service worker thread may be killed
prior to your work completing.
The `doneWaiting` function looks like:
```typescript
() => {...}
```
- returnsPromise\
- fetch void
Fetches a given request (and invokes any applicable plugin callback
methods) using the `fetchOptions` (for non-navigation requests) and
`plugins` defined on the `Strategy` object.
The following plugin lifecycle methods are invoked when using this method:
- `requestWillFetch()`
- `fetchDidSucceed()`
- `fetchDidFail()`
The `fetch` function looks like:
```typescript
(input: RequestInfo) => {...}
```
- input RequestInfo
The URL or request to fetch.
- returnsPromise\
- fetchAndCachePut void
Calls `this.fetch()` and (in the background) runs `this.cachePut()` on
the response generated by `this.fetch()`.
The call to `this.cachePut()` automatically invokes `this.waitUntil()`,
so you do not have to manually call `waitUntil()` on the event.
The `fetchAndCachePut` function looks like:
```typescript
(input: RequestInfo) => {...}
```
- input RequestInfo
The request or URL to fetch and cache.
- returnsPromise\
- getCacheKey void
Checks the list of plugins for the `cacheKeyWillBeUsed` callback, and
executes any of those callbacks found in sequence. The final `Request`
object returned by the last plugin is treated as the cache key for cache
reads and/or writes. If no `cacheKeyWillBeUsed` plugin callbacks have
been registered, the passed request is returned unmodified
The `getCacheKey` function looks like:
```typescript
(request: Request, mode: "read"
| "write"
) => {...}
```
- request Request
- mode "read"
\| "write"
- returnsPromise\
- hasCallback void
Returns true if the strategy has at least one plugin with the given
callback.
The `hasCallback` function looks like:
```typescript
(name: C) => {...}
```
- name C
The name of the callback to check for.
- returnsboolean
- iterateCallbacks void
Accepts a callback and returns an iterable of matching plugin callbacks,
where each callback is wrapped with the current handler state (i.e. when
you call each callback, whatever object parameter you pass it will
be merged with the plugin's current state).
The `iterateCallbacks` function looks like:
```typescript
(name: C) => {...}
```
- name C
The name fo the callback to run
- returnsGenerator\anyunknown\>
- runCallbacks void
Runs all plugin callbacks matching the given name, in order, passing the
given param object (merged ith the current plugin state) as the only
argument.
Note: since this method runs all plugins, it's not suitable for cases
where the return value of a callback needs to be applied prior to calling
the next callback. See
`workbox-strategies.StrategyHandler#iterateCallbacks`
below for how to handle that case.
The `runCallbacks` function looks like:
```typescript
(name: C, param: Omit) => {...}
```
- name C
The name of the callback to run within each plugin.
- param Omit\
The object to pass as the first (and only) param
when executing each callback. This object will be merged with the
current plugin state prior to callback execution.
- returnsPromise\
- waitUntil void
Adds a promise to the
\[extend lifetime promises\]`https://w3c.github.io/ServiceWorker/#extendableevent-extend-lifetime-promises`
of the event associated with the request being handled (usually a
`FetchEvent`).
Note: you can await
`workbox-strategies.StrategyHandler~doneWaiting`
to know when all added promises have settled.
The `waitUntil` function looks like:
```typescript
(promise: Promise) => {...}
```
- promise Promise\
A promise to add to the extend lifetime promises
of the event that triggered the request.
- returnsPromise\
### StrategyOptions
#### Properties
- cacheName string optional
- fetchOptions RequestInit optional
- matchOptions CacheQueryOptions optional
- plugins [WorkboxPlugin](https://developer.chrome.com/docs/workbox/workbox-core/#type-WorkboxPlugin)\[\] optional