next-service-worker
A Next.js plugin that generates a Service Worker. Powered by Workbox.
🧐
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 -
Add this package to your project:
-
npm install next-service-worker
oryarn add next-service-worker
-
-
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);
-
(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
-
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 - To view the production service worker, run
next build && next start
. - 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 theService Workers
tab. - 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 Name | Description | Type |
---|---|---|
registration.autoRegister |
Autoregister the service worker. If if ("serviceWorker" in navigator) {
navigator.serviceWorker.register("/service-worker.js");
} Defaults to |
boolean | undefined |
workbox |
Options passed to `worbox-build`. See all available configuration options [here](https://developer.chrome.com/docs/workbox/modules/workbox-build/)
Defaults to Note: |
InjectManifestOptions | GenerateSWOptions |
🚀
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
👫
Contributing PR's and issues welcomed! For more guidance check out CONTRIBUTING.md
📃
Licensing See the project's MIT License.