Using Workbox 2 and Angular to create a Progressive Web App. Part 1: App shell
This is a set of 5 articles dedicated to creating PWAs using the newest framework and library mentioned in the header. We start from PWA essentials and move to more sophisticated features. The code for all 5 parts is ready and pushed to the repo I mention below,
Part 1: App shell. This resource
Part 2: Runtime caching. Soon
Part 3: Broadcast channel. Soon
Part 4: Background sync. Soon
Part 5: Push notifications. Soon
The web apps we call “progressive” today will be the regular ones in the nearest future. Create React App generates PWA by default, Angular CLI will do the same soon, other frameworks have corresponding templates and generators.
What if we want to add PWA features to our app in framework-agnostic way? There are some great helpers for us! I believe, the current de-facto standard is sw-precache by Google. Its successor, presented at Google I/O 2017, is named Workbox. This article is about my experiments with its version 2.0, released recently.
Let’s go for the classics and create a Twitter-like demo app: some feeds, posting a message, push notifications. Since this is a PWA Twitter, we’ll call it PWAtter :) Here is the hosted demo.
According the definition, Progressive Web App is the app using the latest web technologies (by using the modern browsers’ APIs). For PWAtter we’ll take the following subset of features:
- Web manifest
- Application shell and runtime caching to optimize networking
- Gentle app shell update flow
- Offline fallback for the message posting (with “replay when online” feature)
- Push notifications
We skip the story about web manifest, as for our case it’s not about the coding. I just generated the assets using realfavicongenerator.net. We jump straight to the…
In simple words, this is the minimal set of the files required for your application to start and display some meaningful parts of UI. For example, header with application title, menu, loading indicator. In the best case, all this should be server-rendered, but let’s keep this for another article — it’s not a strict requirement for app shell concept. What could we do with these files? Right! Put them all into the cache (a special one, operated via Cache API, do not mess it with HTTP cache), and serve from there using Service Worker API, instead of going for the network. This way we have our app up and running in offline mode + avoid some network requests in online mode.
Some things to care about:
- Exact list of files: we don’t want to manage this manually. The set could be different from build to build, also filenames could contain hashes, if we go for cache-busting (I mean HTTP cache here).
- Versioning: we don’t want to show app shell v1 forever.
- Cache management: it’s our duty to do a spring cleaning after new version of app shell landed. Cache in not endless and has some quotas.
All listed above could be solved by just one command of Workbox CLI.
Angular app and testing offline mode
Let’s jump to our Angular app for the moment. I prepared everything for our demos on the PWAtter repo (we need
step1 branch). Clone it, and install npm packages.
To be able to build the app, we heed Angular CLI to be installed:
npm install @angular/cli --global
Now we can go for:
npm run build-prod
This will generate Angular app in
dist folder (this command is nothing but a shortcut to Angular CLI’s production build with disabled filenames hashing — for the visually cleaner output).
Let’s serve it using any static webserver and open in Chrome (I strongly recommend you to check if you use the latest version of the browser)
I use Web Server for Chrome extension.
Obviously, after we switch to Offline mode (using Chrome DevTools):
we’ll see our good old friend — offline dyno.
Workbox setting up
Let’s say farewell to this animal! It’s time to install Workbox:
npm install workbox-cli --global
Now we can run:
This nice CLI will ask some questions (to get this dialog, please delete
workbox-cli-config.js file first) about file types and location and generate a service worker. In my example I called it
? What is the root of your web app? dist
? Which file types would you like to cache? (Press <space> to select, <a> to toggle all, <i> to inverse selection)txt, png, ico, htm
l, js, json, css
? What should the path of your new service worker file be (i.e. './build/sw.js')? dist/sw-default.js
? Last Question - Would you like to save these settings to a config file? Yes
This is very convenient to save the settings in
workbox-cli-config.js, as this tool offers, so this file will appear again.
Let’s go to the
dist folder. Three new files appeared:
sw-default.js— auto-generated service worker
workbox-sw.prod.v2.0.0.js— Workbox’ high-level library (+its
What’s inside the first file?
- Importing main library
- The list of all files we specified during setup and their hashes (revisions)
- Instantiating of
WorkboxSWobject and calling
Looking ahead, I can say that as a result we also got all the routing rules set up for us by this code, so it’s not only precaching itself.
Registering service worker
Now we are ready to ask browser to use this auto-generated
sw-default.js as a service worker for our app. There are two ways possible:
- Having registration code in
- Register our service worker after Angular app bootstrapped
The best practice here is: the later — the better, for service worker not to compete with the main thread for bandwidth and processor time, saving precious milliseconds of first-time load for our customers. So we go for the second option.
If you still want to register service worker without using events exposed by your framework-of-choice, do not forget to put the registration code to
window.onloadevent (to follow the best practice I mentioned).
For our case, the code in
main.ts will look like:
For sure, it could be much more laconic, but I decided to output all the feedback I have, for the testing purposes.
npm run build-full-workbox-default
(this is the conjunction of Angular build and Workbox generate commands in my
package.json). And hit refresh in your browser. Do not forget to switch off offline-mode :)
And now… magic moment! Turn on offline mode again, reload the page — boom! The app is still there.
Well, it looks a bit broken. For the demo purpose I decided to use external font and icon font, and of course Workbox CLI couldn’t locate and place these assets during the build. We will fix this in the next chapter, but for now let’s check what happened.
Open DevTools -> Application — this will be our main section. You will see the service worker registered to serve our origin (combination of protocol+hostname+port) and its scope (root in our case):
Also, we can check the contents of Cache (you may need to right-click on Cache Storage and choose Refresh Caches to see the actual content):
From the Workbox
Revisioned assets can be cached intelligently during the install (i.e. old files are cleared from the cache, new files are added to the cache and unchanged files are left as is).
In addition to maintaining the cache, this method will also set up the necessary routes to serve the precached assets using a cache-first strategy.
We could fine-tune the build behaviour by specifying
globIgnores in settings file:
Awesome! It means that we have to do nothing (except one-time npm script setup action) to generate a fresh app shell on each build, to serve the assets from cache, to maintain cache lifecycle in an optimal way. Yes and no.
Yes — for the simplest PWA cases. Where we need only an app shell and all the assets are available during the build time. Then we can fully rely on this 100% auto-generated service worker, which intended to be the main one.
No — for the rest of cases :) Even in our simplest app we already need something more (caching resources in a runtime), and service workers could be very different for different projects. So we need a way to create our own main service worker, and extend it by Workbox features. In contrary to
sw-precache, it’s possible now! Actually, using
workbox-cli is the one of three ways to build PWAs using workbox — the top-level one, simplest, but not flexible at all.
On the next chapter we
- Go away from
workbox-cliin favour of
- Create our custom service worker and extend it by
- Implement runtime caching with the different strategies to optimize networking for font assets and API calls
Stay tuned! I’ll be happy to answer your questions on Twitter @webmaxru. You may want to check my speaking appearances for this year.
I present mainly about PWA and Angular. Catch me there to have a chat about these.