Skip to main content


Adds drop-in support for making a Gatsby site work offline and more resistant to bad network connections. It creates a service worker for the site and loads the service worker into the client.

If you’re using this plugin with gatsby-plugin-manifest (recommended) this plugin should be listed after that plugin so the manifest file can be included in the service worker.


npm install --save gatsby-plugin-offline

How to use

// In your gatsby-config.js
plugins: [`gatsby-plugin-offline`]

Overriding options

When adding this plugin to your gatsby-config.js, you can pass in options to override the default Workbox config.

The default config is as follows. Warning, you can break the offline support and AppCache setup by changing these options so tread carefully.

const options = {
  importWorkboxFrom: `local`,
  globDirectory: rootDir,
  modifyUrlPrefix: {
    // If `pathPrefix` is configured by user, we should replace
    // the default prefix with `pathPrefix`.
    "/": `${pathPrefix}/`,
  navigateFallback: `${pathPrefix}/offline-plugin-app-shell-fallback/index.html`,
  // Only match URLs without extensions or the query `no-cache=1`.
  // So will pass but
  // and
  // will not.
  // We only want the service worker to handle our "clean"
  // URLs and not any files hosted on the site.
  // Regex based on
  navigateFallbackWhitelist: [/^([^.?]*|[^?]*\.([^.?]{5,}|html))(\?.*)?$/],
  navigateFallbackBlacklist: [/\?(.+&)?no-cache=1$/],
  cacheId: `gatsby-plugin-offline`,
  // Don't cache-bust JS or CSS files, and anything in the static directory
  dontCacheBustUrlsMatching: /(.*\.js$|.*\.css$|\/static\/)/,
  runtimeCaching: [
      // Add runtime caching of various page resources.
      urlPattern: /\.(?:png|jpg|jpeg|webp|svg|gif|tiff|js|woff|woff2|json|css)$/,
      handler: `staleWhileRevalidate`,
      // Use the Network First handler for external resources
      urlPattern: /^https?:/,
      handler: `networkFirst`,
  skipWaiting: true,
  clientsClaim: true,

Was this helpful? edit this page on GitHub