next-pwa

When using next-pwa, you should add the generated service worker files to your .gitignore to prevent them from being committed to version control.

**/public/workbox-*.js
**/public/sw.js

To run the demonstration project for Next.js 9+, navigate to the example directory, install dependencies, build the application, and start the development server.

cd examples/next-9
yarn install
yarn build
yarn start

You can implement fallback routes, images, or fonts when a fetch error occurs (typically when the user is offline) by using the Inject Manifest module from workbox.

This approach provides more control over the service worker compared to the default zero-config setup, though it requires more manual implementation. This pattern is useful for handling scenarios where a fetch fails due to connectivity issues.

By default, next-pwa uses a standard cache.js configuration. To customize caching strategies, you should copy the default cache.js file, modify the rules, and then import/inject those configurations into your pwa object in next.config.js.

Rules should follow the Workbox RuntimeCaching structure. Ensure that rules with a smaller, more specific scope are placed before rules with a larger scope in the array.

To gain manual control over the service worker registration lifecycle instead of using the automatic registration provided by next-pwa, follow these two steps:

1. In your next.config.js, set the register option to false.
2. Manually trigger the registration in your application code using window.workbox.register().

This approach allows you to handle lifecycle events manually and implement custom logic, such as prompting users to reload the page when a new service worker version is available.

To prevent users from seeing a browser 'connection lost' page when they refresh a page that was reached via client-side navigation (e.g., using next/link or next/router) while offline, enable cacheOnFrontEndNav.

Since next-pwa@5.2.1, you can achieve this by setting cacheOnFrontEndNav: true in your pwa configuration object within next.config.js. This forces the service worker to intercept and cache routes that would otherwise only be handled by client-side routing, ensuring they are available for offline refreshes.

You can implement fallback routes for specific resource types (image, font, audio, video) when a fetch error occurs (typically when the user is offline).

To use the default fallback for pages, simply create a /_offline page (e.g., pages/_offline.js, pages/_offline.jsx, or pages/_offline.tsx). No additional configuration is required for the default page fallback.

To configure fallbacks for other resource types, use the fallbacks key within the pwa configuration object in your next.config.js.

pwa: {
  // ...
  fallbacks: {
    image: '/static/images/fallback.png',
    // document: '/other-offline',  // if you want to fallback to a custom page other than /_offline
    // font: '/static/font/fallback.woff2',
    // audio: ...,
    // video: ...,
  },
  // ...
}

This example demonstrates how to integrate next-pwa with a custom express server and next-i18next for internationalization.

Important Note on Service Workers: Because the service worker sw.js must be served directly without any redirection, you must ensure its route is excluded from the i18n middleware. Failure to exclude the service worker route from i18n middleware will prevent the PWA from functioning correctly.

cd examples/next-i18next
yarn install
yarn build
yarn start

To run the minimal example provided in this repository, navigate to the example directory, install dependencies, build the Next.js application, and start the server. This example uses fastify as a custom server to serve sw.js and precache scripts statically, and includes a manifest.json and icon set to achieve full offline support and 100 Lighthouse scores.

cd examples/minimal
yarn install
yarn build
yarn start

To run the demonstration project for front-end navigation caching, navigate to the example directory and use the following commands:

cd examples/cache-on-front-end-nav
yarn install
yarn build
yarn start

To enable PWA support, wrap your next.config.js with the withPWA function. You must specify a dest directory (typically 'public') where the generated service worker files (sw.js and workbox-*.js) will be stored.

Note: next-pwa version 2.0.0+ requires next.js 9.1+ and static files must be served from the public directory.

const withPWA = require('next-pwa')({
  dest: 'public'
})

module.exports = withPWA({
  // next.js config
})