Offline support

next-pwa has built-in offline support for both Pages Router and App Router. By default, it caches HTML requests, RSC requests, and RSC precaches separately. This behavior can be overridden with workboxOptions.runtimeCaching.

By default, in development mode, next-pwa sets every resource to be served from the network only to ensure that the app works as expected.

If you see the behavior where your app reloads infinitely, it might be because you have disabled next-pwa from building a service worker in development mode, in which case, try unregistering its service worker, which might have been installed by a production build of your app before, if it exists.

Sometimes fetching from both the cache and the network fails, in which case a resource can be setup to be precached and served in place of an error.

To enable this behavior for pages, simply add a /_offline.tsx file to pages/ or a /~offline/page.tsx file to app/. You are all set! When the user is offline, all pages that are not cached will fallback to /_offline (or /~offline if you are using App Router). You can use this example to see it in action.

To also add a fallback for other resources, change your next.config.js like so:

const withPWA = require("@ducanh2912/next-pwa").default({
  // Your other options,
  fallbacks: {
    // Failed page requests fallback to this.
    document: "/~offline",
    // This is for /_next/.../.json files.
    data: "/fallback.json",
    // This is for images.
    image: "/fallback.webp",
    // This is for audio files.
    audio: "/fallback.mp3",
    // This is for video files.
    video: "/fallback.mp4",
    // This is for fonts.
    font: "/fallback-font.woff2",
  },
});

module.exports = withPWA({
  // Your Next.js config
});

next-pwa helps you precache those resources on first load, then inject a fallback handler to handlerDidError plugin to all runtimeCaching entries, so that precached resources are served when fetching fails.