PWA

Zero Config PWA Plugin for Next.js. This plugin is powered by workbox and other good stuff.

Features

  • Zero config for registering and generating a service worker

  • Optimized precache and runtime cache

  • Maximize lighthouse score

  • Easy to understand examples

  • Completely offline support

  • Use workbox and workbox-window v6

  • Work with cookies out of the box

  • No custom server needed for Next.js 9+

  • Handle PWA lifecycle events opt-in

  • Custom worker to run extra code in service worker with code splitting

  • Debug service worker with confidence in development mode without caching

  • Internationalization (a.k.a I18N) with next-i18next

  • Configurable by the same workbox configuration options for GenerateSW and InjectManifest

  • Spin up a GitPod and try out examples in rocket speed

  • (Experimental) precaching .module.js when next.config.js has experimental.modern set to true

How to use

Thanks to Next.js 9+, we can use the public folder to serve static files from the root / URL path. It cuts the need to write custom server only to serve those files. Therefore the setup is easier and concise. We can use next.config.js to config next-pwa to generates service worker and workbox files into the public folder.

Step 1: Install library

Step 2: withPWA

Update or create next.config.js with

Available Options

  • disable: boolean - whether to disable pwa feature as a whole

    • default to false

    • set disable: false, so that it will generate service worker in both dev and prod

    • set disable: true to completely disable PWA

    • if you don't need to debug service worker in dev, you can set disable: process.env.NODE_ENV === 'development'

  • register: boolean - whether to let this plugin register service worker for you

    • default to true

    • set to false when you want to handle register service worker yourself, this could be done in componentDidMount of your root app. you can consider the register.js as an example.

  • scope: string - url scope for pwa

    • default to /

    • set to /app so that path under /app will be PWA while others are not

  • sw: string - service worker script file name

    • default to /sw.js

    • set to another file name if you want to customize the output file name

  • runtimeCaching - caching strategies (array or callback function)

    • default: see the Runtime Caching section for the default configuration

    • accepts an array of cache entry objects, please follow the structure here

    • Note: the order of the array matters. The first rule that matches is effective. Therefore, please ALWAYS put rules with larger scope behind the rules with a smaller and specific scope.

  • publicExcludes - an array of glob pattern strings to exclude files in the public folder from being precached.

    • default: [] - this means that the default behavior will precache all the files inside your public folder

    • example: ['!img/super-large-image.jpg', '!fonts/not-used-fonts.otf']

  • buildExcludes - an array of extra pattern or function to exclude files from being precached in .next/static (or your custom build) folder

    • default: []

    • example: [/chunks\/images\/.*$/] - Don't precache files under .next/static/chunks/images (Highly recommend this to work with next-optimized-images plugin)

    • doc: Array of (string, RegExp, or function()). One or more specifiers used to exclude assets from the precache manifest. This is interpreted following the same rules as Webpack's standard exclude option.

  • subdomainPrefix: string - url prefix to allow hosting static files on a subdomain

    • default: "" - i.e. default with no prefix

    • example: /subdomain if the app is hosted on example.com/subdomain

Step 3: Add Manifest File

Create a manifest.json file in your public folder:

Step 4: Add Head Meta

Add the following into _document.jsx or _document.tsx, in <Head>:

Tip: Put the viewport head meta tag into _app.js rather than in _document.js if you need it.

PreviousRedux ConfigsNextSEO

Last updated

Was this helpful?