shadowwalker/next-pwaPublic

NotificationsYou must be signed in to change notification settings
Fork338
Star4.1k

Zero config PWA plugin for Next.js, with workbox 🧰

License

MIT license

4.1k stars 338 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 407 Commits
.github		.github
examples		examples
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitpod.yml		.gitpod.yml
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
build-custom-worker.js		build-custom-worker.js
build-fallback-worker.js		build-fallback-worker.js
cache.js		cache.js
fallback.js		fallback.js
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
register.js		register.js

Repository files navigation

Zero Config PWA Plugin forNext.js

This plugin is powered byworkbox and other good stuff.

👋 Share your awesome PWA project 👉here

Features

0️⃣ Zero config for registering and generating service worker
✨ Optimized precache and runtime cache
💯 Maximize lighthouse score
🎈 Easy to understand examples
📴 Completely offline support with fallbacksexample 🆕
📦 Useworkbox andworkbox-window v6
🍪 Work with cookies out of the box
🔉 Default range requests for audios and videos
☕ No custom server needed for Next.js 9+example
🔧 Handle PWA lifecycle events opt-inexample
📐 Custom worker to run extra code with code splitting andtypescript supportexample
📜Public environment variables available in custom worker as usual
🐞 Debug service worker with confidence in development mode without caching
🌏 Internationalization (a.k.a I18N) withnext-i18nextexample
🛠 Configurable by the sameworkbox configuration options forGenerateSW andInjectManifest
🚀 Spin up aGitPod and try out examples in rocket speed
⚡ Supportblitz.js (simply add toblitz.config.js)
🔩 (Experimental) precaching.module.js whennext.config.js hasexperimental.modern set totrue

NOTE 1 -next-pwa version 2.0.0+ should only work withnext.js 9.1+, and static files should only be served throughpublic directory. This will make things simpler.
NOTE 2 - If you encounter errorTypeError: Cannot read property **'javascript' of undefined** during build,please consider upgrade to webpack5 innext.config.js.

Install

If you are new tonext.js orreact.js at all, you may want to first checkoutlearn next.js ornext.js document. Then start froma simple example orprogressive-web-app example in next.js repository.

yarn add next-pwa

Basic Usage

Step 1: withPWA

Update or createnext.config.js with

constwithPWA=require('next-pwa')({dest:'public'})module.exports=withPWA({// next.js config})

After runningnext build, this will generate two files in yourpublic:workbox-*.js andsw.js, which will automatically be served statically.

If you are using Next.js version 9 or newer, then skip the options below and move on to Step 2.

If you are using Next.js older than version 9, you'll need to pick an option below before continuing to Step 2.

Option 1: Host Static Files

Copy files to your static file hosting server, so that they are accessible from the following paths:https://yourdomain.com/sw.js andhttps://yourdomain.com/workbox-*.js.

One example is using Firebase hosting service to host those files statically. You can automate the copy step using scripts in your deployment workflow.

For security reasons, you must host these files directly from your domain. If the content is delivered using a redirect, the browser will refuse to run the service worker.

Option 2: Use Custom Server

When an HTTP request is received, test if those files are requested, then return those static files.

Exampleserver.js

const{ createServer}=require('http')const{ join}=require('path')const{ parse}=require('url')constnext=require('next')constapp=next({dev:process.env.NODE_ENV!=='production'})consthandle=app.getRequestHandler()app.prepare().then(()=>{createServer((req,res)=>{constparsedUrl=parse(req.url,true)const{ pathname}=parsedUrlif(pathname==='/sw.js'||/^\/(workbox|worker|fallback)-\w+\.js$/.test(pathname)){constfilePath=join(__dirname,'.next',pathname)app.serveStatic(req,res,filePath)}else{handle(req,res,parsedUrl)}}).listen(3000,()=>{console.log(`> Ready on http://localhost:${3000}`)})})

The following setup has nothing to do withnext-pwa plugin, and you probably have already set them up. If not, go ahead and set them up.

Step 2: Add Manifest File (Example)

Create amanifest.json file in yourpublic folder:

{"name":"PWA App","short_name":"App","icons": [    {"src":"/icons/android-chrome-192x192.png","sizes":"192x192","type":"image/png","purpose":"any maskable"    },    {"src":"/icons/android-chrome-384x384.png","sizes":"384x384","type":"image/png"    },    {"src":"/icons/icon-512x512.png","sizes":"512x512","type":"image/png"    }  ],"theme_color":"#FFFFFF","background_color":"#FFFFFF","start_url":"/","display":"standalone","orientation":"portrait"}

Step 3: Add Head Meta (Example)

Add the following into_document.jsx or_app.tsx, in<Head>:

<metaname="application-name"content="PWA App"/><metaname="apple-mobile-web-app-capable"content="yes"/><metaname="apple-mobile-web-app-status-bar-style"content="default"/><metaname="apple-mobile-web-app-title"content="PWA App"/><metaname="description"content="Best PWA App in the world"/><metaname="format-detection"content="telephone=no"/><metaname="mobile-web-app-capable"content="yes"/><metaname="msapplication-config"content="/icons/browserconfig.xml"/><metaname="msapplication-TileColor"content="#2B5797"/><metaname="msapplication-tap-highlight"content="no"/><metaname="theme-color"content="#000000"/><linkrel="apple-touch-icon"href="/icons/touch-icon-iphone.png"/><linkrel="apple-touch-icon"sizes="152x152"href="/icons/touch-icon-ipad.png"/><linkrel="apple-touch-icon"sizes="180x180"href="/icons/touch-icon-iphone-retina.png"/><linkrel="apple-touch-icon"sizes="167x167"href="/icons/touch-icon-ipad-retina.png"/><linkrel="icon"type="image/png"sizes="32x32"href="/icons/favicon-32x32.png"/><linkrel="icon"type="image/png"sizes="16x16"href="/icons/favicon-16x16.png"/><linkrel="manifest"href="/manifest.json"/><linkrel="mask-icon"href="/icons/safari-pinned-tab.svg"color="#5bbad5"/><linkrel="shortcut icon"href="/favicon.ico"/><linkrel="stylesheet"href="https://fonts.googleapis.com/css?family=Roboto:300,400,500"/><metaname="twitter:card"content="summary"/><metaname="twitter:url"content="https://yourdomain.com"/><metaname="twitter:title"content="PWA App"/><metaname="twitter:description"content="Best PWA App in the world"/><metaname="twitter:image"content="https://yourdomain.com/icons/android-chrome-192x192.png"/><metaname="twitter:creator"content="@DavidWShadow"/><metaproperty="og:type"content="website"/><metaproperty="og:title"content="PWA App"/><metaproperty="og:description"content="Best PWA App in the world"/><metaproperty="og:site_name"content="PWA App"/><metaproperty="og:url"content="https://yourdomain.com"/><metaproperty="og:image"content="https://yourdomain.com/icons/apple-touch-icon.png"/><!-- apple splash screen images --><!--<link rel='apple-touch-startup-image' href='/images/apple_splash_2048.png' sizes='2048x2732' /><link rel='apple-touch-startup-image' href='/images/apple_splash_1668.png' sizes='1668x2224' /><link rel='apple-touch-startup-image' href='/images/apple_splash_1536.png' sizes='1536x2048' /><link rel='apple-touch-startup-image' href='/images/apple_splash_1125.png' sizes='1125x2436' /><link rel='apple-touch-startup-image' href='/images/apple_splash_1242.png' sizes='1242x2208' /><link rel='apple-touch-startup-image' href='/images/apple_splash_750.png' sizes='750x1334' /><link rel='apple-touch-startup-image' href='/images/apple_splash_640.png' sizes='640x1136' />-->

Tip: Put theviewport head meta tag into_app.js rather than in_document.js if you need it.

<metaname='viewport'content='minimum-scale=1, initial-scale=1, width=device-width, shrink-to-fit=no, user-scalable=no, viewport-fit=cover'/>

Offline Fallbacks

Offline fallbacks are useful when the fetch failed from both cache and network, a precached resource is served instead of present an error from browser.

To get started simply add a/_offline page such aspages/_offline.js orpages/_offline.jsx orpages/_offline.ts orpages/_offline.tsx. Then you are all set! When the user is offline, all pages which are not cached will fallback to '/_offline'.

Use this example to see it in action

next-pwa helps you precache those resources on the first load, then inject a fallback handler tohandlerDidError plugin to allruntimeCaching configs, so that precached resources are served when fetch failed.

You can also setupprecacheFallback.fallbackURL in yourruntimeCaching config entry to implement similar functionality. The difference is that above method is based on the resource type, this method is based matched url pattern. If this config is set in the runtimeCaching config entry, resource type based fallback will be disabled automatically for this particular url pattern to avoid conflict.

Configuration

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

constwithPWA=require('next-pwa')({dest:'public'// disable: process.env.NODE_ENV === 'development',// register: true,// scope: '/app',// sw: 'service-worker.js',//...})module.exports=withPWA({// next.js config})

Available Options

disable: boolean - whether to disable pwa feature as a whole
- default:false
- setdisable: false, so that it will generate service worker in bothdev andprod
- setdisable: true to completely disable PWA
- if you don't need to debug service worker indev, you can setdisable: process.env.NODE_ENV === 'development'
register: boolean - whether to let this plugin register service worker for you
- default totrue
- set tofalse when you want to handle register service worker yourself, this could be done incomponentDidMount of your root app. you can consider theregister.js as an example.
scope: string - url scope for pwa
- default:basePath innext.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 theRuntime 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, pleaseALWAYS 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 thepublic folder from being precached.
- default:['!noprecache/**/*'] - this means that the default behavior will precache all the files inside yourpublic 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 withnext-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
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 whencacheStartUrl set totrue
- recommend: set tofalse 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 whendynamicStartUrlRedirect set totrue
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 aspages/_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 withnext/link on front end. Checkout thisexample 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 onexample.com/subdomain~~
- deprecated, usebasePath 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 calllocation.reload() to refresh the app.
- default:true
customWorkerDir - customize the directory wherenext-pwa looks for a custom worker implementation to add to the service worker generated by workbox. For more information, check out thecustom worker example.
- default:worker

Other Options

next-pwa usesworkbox-webpack-plugin, other options which could also be put inpwa object can be foundON THE DOCUMENTATION forGenerateSW andInjectManifest. If you specifyswSrc,InjectManifest plugin will be used, otherwiseGenerateSW will be used to generate service worker.

Runtime Caching

next-pwa uses a default runtimecache.js

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

Here is thedocument on how to write runtime caching configurations, including background sync and broadcast update features and more!

Tips

Common UX pattern to ask user to reload when new service worker is installed
Use a convention like{command: 'doSomething', message: ''} object whenpostMessage to service worker. So that on the listener, it could do multiple different tasks usingif...else....
When you are debugging service worker, constantlyclean application cache to reduce some flaky errors.
If you are redirecting the user to another route, please noteworkbox by default only cache response with 200 HTTP status, if you really want to cache redirected page for the route, you can specify it inruntimeCaching such asoptions.cacheableResponse.statuses=[200,302].
When debugging issues, you may want to format your generatedsw.js file to figure out what's really going on.
Forcenext-pwa to generate worker box production build by specify the optionmode: 'production' in yourpwa section ofnext.config.js. Thoughnext-pwa automatically generate the worker box development build during development (by runningnext) and worker box production build during production (by runningnext build andnext start). You may still want to force it to production build even during development of your web app for following reason:
1. Reduce logging noise due to production build doesn't include logging.
2. Improve performance a bit due to production build is optimized and minified.
If you just want to disable worker box logging while keeping development build during development,simply putself.__WB_DISABLE_DEV_LOGS = true in yourworker/index.js (create one if you don't have one).
It is common developers have to useuserAgent string to determine if users are using Safari/iOS/MacOS or some other platform,ua-parser-js library is a good friend for that purpose.