Configuration

There are options you can use to customize the behavior of this plugin by adding pwa object in the next config in next.config.js:

Available Options

• disable: boolean - whether to disable pwa feature as a whole
  • default: 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 (opens in a new tab) as an example.
• scope: string - url scope for pwa
  • default: basePath (opens in a new tab) in next.config.js or /
  • set to /app so that path under /app will be PWA while others are not
• sw: string - service worker script file name
  • default: /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 (opens in a new tab)
  • 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: ['!noprecache/**/*'] - this means that the default behavior will precache all the files inside your public folder but files inside /public/noprecache folder. You can simply put files inside that folder to not precache them without config this.
  • 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.
• cacheStartUrl - whether to cache start url
  • default: true
  • discussion of use case to not cache start url at all (opens in a new tab)
• dynamicStartUrl - if your start url returns different HTML document under different state (such as logged in vs. not logged in), this should be set to true.
  • default: true
  • effective when cacheStartUrl set to true
  • recommend: set to false if your start url always returns same HTML document, then start url will be precached, this will help to speed up first load.
• dynamicStartUrlRedirect - if your start url redirect to another route such as /login, it's recommended to setup this redirected url for the best user experience.
  • default: undefined
  • effective when dynamicStartUrlRedirect set to true
• fallbacks - config precached routes to fallback when both cache and network not available to serve resources.
  • if you just need a offline fallback page, simply create a /_offline page such as pages/_offline.js and you are all set, no configuration necessary
  • default: object
    • fallbacks.document - fallback route for document (page), default to /_offline if you created that page
    • fallbacks.image - fallback route for image, default to none
    • fallbacks.audio - fallback route for audio, default to none
    • fallbacks.video - fallback route for video, default to none
    • fallbacks.font - fallback route for font, default to none
• cacheOnFrontEndNav - enable additional route cache when navigate between pages with next/link on front end. Checkout this example (opens in a new tab) for some context about why this is implemented.
  • default: false
  • note: this improve user experience on special use cases but it also adds some overhead because additional network call, I suggest you consider this as a trade off.
• 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
  • deprecated, use basePath (opens in a new tab) instead
• reloadOnOnline - changes the behaviour of the app when the device detects that it has gone back "online" and has a network connection. Indicate if the app should call location.reload() to refresh the app.
  • default: true
• customWorkerDir - customize the directory where next-pwa looks for a custom worker implementation to add to the service worker generated by workbox. For more information, check out the custom worker example (opens in a new tab).
  • default: worker
• customWorkerWebpack - Function to customize the webpack configuration for bundling custom workers. Receives the configuration object with default settings and must return the modified one.
  • default: undefined

Other Options

next-pwa uses workbox-webpack-plugin, other options which could also be put in pwa object can be found ON THE DOCUMENTATION (opens in a new tab) for GenerateSW (opens in a new tab) and InjectManifest (opens in a new tab). If you specify swSrc, InjectManifest plugin will be used, otherwise GenerateSW will be used to generate service worker.

Runtime Caching

next-pwa uses a default runtime cache.js (opens in a new tab)

There is a great chance you may want to customize your own runtime caching rules. Please feel free to copy the default cache.js file and customize the rules as you like. Don't forget to inject the configurations into your pwa config in next.config.js.

Here is the document on how to write runtime caching configurations (opens in a new tab), including background sync and broadcast update features and more!

Recommend .gitignore

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