next-service-worker

What is this? 🧐

A minimal wrapper around Workbox to quickly add a service worker to your Next.js site. Get precached pages and offline support out of the box.

Installation & Usage 📦

1. Add this package to your project:

   • npm install next-service-worker or yarn add next-service-worker

2. Update your next.config.js:

   + const { serviceWorker } = require("next-service-worker");
   + const withServiceWorker = serviceWorker();
   
   /** @type {import('next').NextConfig} */
   const nextConfig = {
     reactStrictMode: true,
   };
   
   - module.exports = nextConfig;
   + module.exports = withServiceWorker(nextConfig);

3. (Optional): Add the generated service worker files to your .gitignore:

   # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
   
   # dependencies
   /node_modules
   /.pnp
   .pnp.js
   
   ...
   
   + # generated service worker (next-service-worker)
   + public/service-worker.js
   + public/workbox-*.js

4. That's it! A service worker that precaches all of your build's static assets will be generated. Static assets will be served from the service worker's cache instead of making network calls, speeding up your page views and enabling offline viewing 🙌.

Verification 🤔

1. To view the production service worker, run next build && next start.
2. The service worker must first install before it intercepts any traffic. You can view the status of the service worker in Chrome by opening the dev console, clicking the Application tab and then clicking the Service Workers tab.
3. Disable your internet connection and click around your site. Your assets will be served by the service worker. This is most obvious when you are disconnected from the internet, but even when users have an internet connection your assets will be served from the service worker and not from the network -- markedly speeding up these requests.

API Overview 🛠

Autoregister the service worker.

If false, then the application must initialize the service worker by invoking register. Set this to false if you'd like to take control over when you service worker is initialized. You'll then need to add something like the following to your application:

if ("serviceWorker" in navigator) {
  navigator.serviceWorker.register("/service-worker.js");
}

Defaults to true. Recommended: true.

Defaults to GenerateSW which will generate a service worker.

Note: injectManifest is not supported at this time. If you would like it to be supported, please open an issue

Examples 🚀

Check out the next-service-worker-example. The only change from the default NextJS setup is the addition of next.config.js!

Common Service Worker Pitfalls ⚠️

You must serve your application over HTTPS in production environments. Service Workers must be served from the site's origin over HTTPS.

Some browsers special case localhost, so this may not be necessary during local development. HTTPS is not handled by this library. You can use a reverse proxy like Nginx or Caddy if you want to setup HTTPS for local development.

The service worker origin constraint means that service workers can not control pages on a different subdomain. Eg mysite.com can not be controlled by a service worker if that was served from a subdomain such as mycdn.mysite.com. To learn more about how service workers work in general, read MDN's documentation.

Related Projects

• Next PWA
• Next Offline

Contributing 👫

PR's and issues welcomed! For more guidance check out CONTRIBUTING.md

Licensing 📃

See the project's MIT License.