![Jeff Posnick](https://web.dev/images/authors/jeffposnick.jpg) Jeff Posnick [X](https://twitter.com/jeffposnick) [GitHub](https://github.com/jeffposnick) [Homepage](https://jeffy.info/)

<br />

Two APIs play a crucial role in building reliable web apps:
[Service Worker](https://developer.mozilla.org/docs/Web/API/Service_Worker_API)
and [Cache Storage](https://developer.mozilla.org/docs/Web/API/Cache). But
using them effectively---without introducing subtle bugs or bumping into edge
cases---can be a challenge. For example, errors in your service worker code can
cause caching problems; users might be shown out-of-date content or broken
links.

[Workbox](https://developer.chrome.com/docs/workbox) is a high-level
service worker toolkit built on top of the Service Worker and Cache Storage
APIs. It provides a production-ready set of libraries for adding offline support to
web apps. The toolkit is structured into two collections: tools that help manage
code that runs inside of your service worker, and tools that integrate with your
build process.

### Runtime code

This is the code that runs inside of your service worker script and controls how
it intercepts outgoing requests and interacts with the Cache Storage API.
Workbox has a
[dozen or so library modules in total](https://developer.chrome.com/docs/workbox/modules),
that each handle a variety of specialized use cases. The most important modules
determine *whether* the service worker will respond (known as
[routing](https://developer.chrome.com/docs/workbox/modules/workbox-routing)),
and *how* it will respond (known as the
[caching strategy](https://developer.chrome.com/docs/workbox/modules/workbox-strategies)).

### Build integration

Workbox offers
[command line](https://developer.chrome.com/docs/workbox/modules/workbox-cli),
[Node.js module](https://developer.chrome.com/docs/workbox/modules/workbox-build),
and
[webpack plugin](https://developer.chrome.com/docs/workbox/modules/workbox-webpack-plugin)
tools that provide alternative ways to accomplish two things:

- Create a service worker script based on a set of configuration options. The generated service worker uses Workbox's runtime libraries "under the hood" to put into action the caching strategies you configure.
- Generate a list of URLs that should be "[precached](https://developer.chrome.com/docs/workbox/modules/workbox-precaching)", based on configurable patterns to include and exclude files generated during your build process.

## Why should you use Workbox?

Using Workbox when building your service worker is optional---there are a number
of guides out there that walk through
[common caching strategies](https://web.dev/articles/offline-cookbook.md.txt)
from a "vanilla" service worker perspective. If you do decide to use Workbox,
here are some of its benefits.

### Cache management

Workbox handles cache updates for you, either tied in to your build process when
using precaching, or via configurable size/age policies when using runtime
caching. The underlying Cache Storage API is powerful, but it does not have any
built-in support for cache expiration. Tools like Workbox fill that gap.

### Extensive logging and error reporting

When you're getting started with service workers, figuring out *why* something
is being cached (or, equally frustrating, why it *isn't* cached) is a challenge.
Workbox automatically detects when you're running a development version of your
website on `localhost`, and turns on debug logging in your browser's JavaScript
console.

![Workbox logging to the DevTools console](https://web.dev/static/articles/workbox/image/workbox-logging-the-devt.png)

By following along with the log messages, you can get to the root of any
configuration or invalidation problems much more quickly than if you were going
it alone.

### A tested, cross-browser codebase

Workbox is developed against a cross-browser test suite, and when possible,
automatically falls back to alternative implementations of features that are
missing from certain browsers.

- The [`workbox-broadcast-cache-update module`](https://developer.chrome.com/docs/workbox/modules/workbox-broadcast-update) uses the [Broadcast Channel API](https://developer.mozilla.org/docs/Web/API/Broadcast_Channel_API) when available, and falls back to a [`postMessage()`](https://developer.mozilla.org/docs/Web/API/Window/postMessage)-based implementation on browsers that lack support.
- The [workbox-background-sync module](https://developer.chrome.com/docs/workbox/modules/workbox-background-sync) uses the [Background Sync API](https://developer.chrome.com/blog/background-sync) if possible, and if not, falls back to retrying queued events each time the service worker starts up.

## How should you use Workbox?

### Framework integration

If you're starting a new project from scratch, you can take advantage of the
Workbox integration found in many popular starter kits and add-on plugins:

- [create-react-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)
- [vue-cli](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-plugin-pwa/README.md)
- [preact-cli](https://github.com/prateekbh/preact-cli-workbox-plugin/blob/master/README.md)
- [Gatsby](https://www.gatsbyjs.org/packages/gatsby-plugin-offline/)
- [Next.js](https://github.com/hanford/next-offline/blob/master/readme.md)

### Add Workbox to your existing build process

If you already have a build process for your site in place, dropping in the
appropriate
[command line](https://developer.chrome.com/docs/workbox/modules/workbox-cli),
[Node.js module](https://developer.chrome.com/docs/workbox/modules/workbox-build),
or
[webpack plugin](https://developer.chrome.com/docs/workbox/modules/workbox-webpack-plugin)
tool may be all you need to start using Workbox.

In particular, the Workbox command line interface makes it easy to get up and
running, featuring a `wizard` mode that will check your local development
environment and suggest a reasonable default configuration that you could use
moving forward:

```bash
workbox wizard
? What is the root of your web app (i.e. which directory do you deploy)? src/
? Which file types would you like to precache? css, js, html
? Where would you like your service worker file to be saved? build/sw.js
? Where would you like to save these configuration options? workbox-config.js
```

To build your service worker, run `workbox generateSW workbox-config.js`
as part of a build process. See the [`generateSW` documentation](https://goo.gl/fdTQBf) for details.
You can further customize your service worker by making changes to `workbox-config.js`.
See the [documentation of the options](https://goo.gl/gVo87N) for details.

### Use Workbox at runtime in an existing service worker

If you have an existing service worker and want to try out Workbox's runtime
libraries,
[import Workbox from its official CDN](https://developer.chrome.com/docs/workbox/modules/workbox-sw#using-workbox-sw-via-cdn)
and start using it for runtime caching right away. This use
case means that you won't be able to take advantage of precaching (which
requires build-time integration), but it's great for prototyping and trying out
different caching strategies on the fly.

```javascript
// Replace 3.6.3 with the current version number of Workbox.
importScripts('https://storage.googleapis.com/workbox-cdn/releases/3.6.3/workbox-sw.js');

workbox.routing.registerRoute(
  new RegExp('\.png$'),
  workbox.strategies.cacheFirst({
    cacheName: 'images-cache',
  })
);
```