workbox-expiration

It's fairly common to want to put restrictions on a cache in terms of how long it should allow items to be stored in a cache or how many items should be kept in a cache. Workbox provides this functionality through the workbox-expiration plugin that allows you to limit the number of entries in a cache and / or remove entries that have been cached for a long period of time.

# Restrict the Number of Cache Entries

To restrict the number of entries stored in a cache, you can use the maxEntries option like so:

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({
        maxEntries: 20,
      }),
    ],
  })
);

With this, the Plugin will be added to this route. After a cached response is used or a new request is added to the cache, the plugin will look at the configured cache and ensure that the number of cached entries doesn't exceed the limit. If it does, the oldest entries will be removed.

# Restrict the Age of Cached Entries

To restrict how long a request is cached for, you can define a max age in seconds using the maxAgeSeconds option like so:

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({
        maxAgeSeconds: 24 * 60 * 60,
      }),
    ],
  })
);

The plugin will check and remove entries after each request or cache update.

# Advanced Usage

If you'd like to use the expiration logic separate from any other Workbox module, you can do so with the CacheExpiration class.

To apply restrictions to a cache, you'd create an instance of CacheExpiration for the cache you want to control like so:

import {CacheExpiration} from 'workbox-expiration';

const cacheName = 'my-cache';
const expirationManager = new CacheExpiration(cacheName, {
  maxAgeSeconds: 24 * 60 * 60,
  maxEntries: 20,
});

Whenever you update a cached entry, you need to call the updateTimestamp() method so that its age is updated.

await openCache.put(request, response);

await expirationManager.updateTimestamp(request.url);

Then, whenever you want to expire a set of entries, you can call the expireEntries() method which will enforce the maxAgeSeconds and maxEntries configuration.

await expirationManager.expireEntries();