Posted onOct 23, 2021 • Originally published atbionicjulia.com onOct 23, 2021

Progressive Web App (PWA) in Next.js

#nextjs #react

First things first - what even is a Progressive Web App, or PWA for short?

If you've got some time, check out theMDN docs to get a good overview. If I had to take a stab at defining PWAs in my own words, it's a way of allowing a web app to be accessed as if it was a native app, on mobile or desktop devices.

So, what is it that actually makes an app, a Progressive Web App?

Whilst I don't think there's an official standard on this, some of the key principles to consider are:

Is it installable, so that it can be accessed, say on your mobile home screen?
Does it work offline / under poor network connections?
Is it responsive to whatever device it's being viewed on?
Does it adhere to progressive enhancement, in that it caters to older devices (at a more basic level), but also newer ones?

Why might you want to consider making your web app into a PWA?

Whilst it can be simple enough to allow your users to continue accessing your app through your mobile browser, allowing it to be accessed as a pseudo native app directly from a home screen may:

Be more efficient;
- Loading times can be near instantaneous due to the use of service workers and caching.
- You only need to send updates for bits that have actually changed, as opposed to updating an entire native app.
Provide a nicer native experience vs. a web browser e.g. with mobile-specific app icons, responsive design and features and full screen modes);
Allow your users to access your app without a network connection; and
Provide more direct connection and engagement with your end user through use of features like push notifications.

How to create a PWA in Next.js

The really nice thing about Next.js is that they have an official way of doing this with thenext-pwa package. Here are the steps I took:

Install the package withyarn add next-pwa.
If you don't already have one, create amanifest.json file in your/public folder. This file basically provides metadata about your app, to your browser, so that it knows how to render your app when downloaded as an extension on desktop or mobile. You can search for manifest generators online, but the one thing you'll need beforehand is an icon for your app. You can see an example of what my manifest file looks like in the appendix below.
We now need make themanifest.json file accessible on browser load. Within the/pages directory, open (or create) the_document.tsx file. If you've not come across this file before, read more about ithere. You basically want to add a link to your manifest JSON within the<Head> tags so that your browser can access it. Alternatively, if you've already got access to your app's<Head> tags somewhere else (e.g.index.tsx), then just put it in there.

<Head>    // ...<linkrel="manifest"href="/manifest.json"/>    // ...</Head>

Innext.config.js, require thenext-pwa package and wrap your module export function with it. (Detailed instructions are available in thenext-pwa Github repo.)

constwithPWA=require('next-pwa')module.exports=withPWA({target:'serverless',pwa:{dest:'public',disable:process.env.NODE_ENV==='development',},// ... whatever other config you might have})

Note that there are other settings you can configure your PWA to adhere to, so just check out the official documentation to learn more.

And that's basically the setup in a nutshell. To test it's all working as expected, you can uncomment out thedisable line for the dev environment in the config file above, then build your app in Next (I useyarn build for this). Head over tolocalhost:3000 and you should see an option in your browser to "install" your app.

This is what it looks like on my production site:

Note that running this build for the first time will create a number of new PWA files in yourpublic folder, includingsw.js which is your service worker. You're going to want to ensure these don't get cached so remember to ignore these files in your version control (see troubleshooting tips below).

Offline support

One thing to note is that thenext-pwa package tries to load content by grabbing it from the cache and network. If both of these sources fail, an error page will be rendered instead. For a nicer user experience, you can define a custom page for the user to see by creating a new file called_offline.tsx in thepages directory. All pages which cannot be downloaded will then display this page instead.

To overwrite the file location for this fallback page, in addition to setting up fallback content for other media types like images, videos, fonts etc., you can define these in thenext.config.js file within thepwa settings.

module.exports=withPWA({target:'serverless',pwa:{dest:'public',disable:process.env.NODE_ENV==='development',fallbacks:{image:'/offline.png',document:'/pages/offline-2.tsx',},},// ...})

This is what my offline page looks like:

Troubleshooting tips

If you want to test it in the local dev environment, and see an error that looks something like this, you might need to install webpack as a dev dependency.

Couldnotfindfilesfor/ in .next/build-manifest.json

To do that, runyarn add webpack --dev.

Ensure you keep content updated by adding the following PWA files to.gitignore (if you use git), so that these are not checked in and cached, but generated each time you build your app.

# .gitignore  /public/sw.js  /public/workbox-*.js  /public/worker-*.js  /public/sw.js.map  /public/workbox-*.js.map  /public/worker-*.js.map  /public/fallback-*.js

Appendix

Mymanifest.json file:

{"name":"Bionic Julia","short_name":"Bionic Julia","description":"My thoughts and learnings","start_url":"/","orientation":"portrait-primary","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}