PWA Starter: The PWA Checklist

November 20 2017
13 min. read

Text from Google's PWA Checklist used under a Creative Commons Attribution 3.0 License.

Google's PWA checklist presents both a basic and an advanced set of requirements for Progressive Web Applications. As I mentioned earlier not all these requirements are technical, some of them have to deal with the performance of your application/site and with best practices in responsive web design.

I've grouped them in two categories: Basic and Advanced requirements. I will comment on individual entries as needed.

Basic Requirements #

Serving through HTTPS in a requirement for service workers and most, if not all, modern features available in browsers. Whether you run a PWA or not you should consider moving your site to secure hosting.

If cost is an issue there are way to obtain low cost or free SSL certificates. Tools like letsencrypt.org make it trivial to obtain ceertificates and install them on your server.

Site is served over HTTPS
To Test	Use Lighthouse to verify Served over HTTPS
To Fix	Implement HTTPS and check out letsencrypt.org to get started

You're already creating responsive content, right? As designers and developers we know that it's not enough to do a desktop-first design and then tweak it for other form factors.

Even if we look at browser popularity we might be surprised at the results. According to Statcounters (gs.statcounter.com) the three most popular browsers, worldwide (08/16 to 08/17), are:

Browser	Market Share
Chrome	54.89%
Safari	14.88%
UC Browser	7.43%
Firefox	5.9%
Opera	4%
IE	3.69%

If you're looking at working in emerging markets, the figures change. According to Statcounter, the Browser market share for mobile devices in Asia breaks like this over the last year (same time period as before).

Browser	Market Share
Chrome	50.46%
UC Browser	22.23%
Safari	10.27%
Opera	6.38%
Samsung Internet	5.97%
Android	3.31%

So any way you look at it, it pays to be responsive.

Pages are responsive on tablets & mobile devices
To Test	Use Lighthouse to verify Yes to all of Design is mobile-friendly, although manually checking can also be helpful. Check the Mobile Friendly Test
To Fix	Look at implementing a responsive design, or adaptively serving a viewport-friendly site.

Use the service worker to make sure that at least the entry page to your site works while offline. This may be just a matter to cache the assets for the starting URL when you install the service worker (as we saw earlier).

Runtime caching should take care of ca ching the rest of your PWA.

The start URL (at least) loads while offline
To Test	Use Lighthouse to verify URL responds with a 200 when offline.
To Fix	Use a Service Worker.

Metadata provided for Add to Home screen
To Test	Use Lighthouse to verify User can be prompted to Add to Home screen is all Yes.
To Fix	Add a Web App Manifest to your project.

Working with a service worker will smooth out network issues and increase the perceived performance of your site or app. That said we still want the content to load fast and we should take all steps to make sure it happens even for older browsers that don't support service workers or the polyfill.

First load fast even on 3G
To Test	Use Lighthouse on a Nexus 5 (or similar) to verify time to interactive <10s for first visit on a simulated 3G network.
To Fix	There are many ways to improve performance. You can understand your performance better by using Pagespeed Insights (aim for score >85) and SpeedIndex on WebPageTest (aim for <4000 first view on Mobile 3G Nexus 5 Chrome) A few tips are to focus on loading less script, make sure as much script is loaded asynchronously as possible using <script async> and make sure render blocking CSS is marked as such. You can also look into using the PRPL pattern and tools like PageSpeed Module on the server.

Browsers are getting there in interoperability but they are not there quite yet. Make sure that it works on all your target browsers for mobile and desktop. Fix whatever doesn't work (duh).

Site works cross-browser
To Test	Test site in Chrome, Edge, Firefox and Safari
To Fix	Fix issues that occur when running the app cross-browser

Page transitions don't feel like they block on the network
Transitions should feel snappy as you tap around, even on a slow network, a key to perceived performance.
To Test	Open the app on a simulated very slow network. Every time you tap a link/button in the app the page should respond immediately, either by: Transitioning immediately to the next screen and showing a placeholder loading screen while waiting for content from the network. A loading indicator is shown while the app waits for a response from the network
To Fix	If using a single-page-app (client rendered), transition the user to the next page immediately and show a skeleton screen and use any content such as title or thumbnail already available while content loads.

Each page has a URL
To Test	Ensure individual pages are deep linkable via the URLs and that URLs are unique for the purpose of shareability on social media by testing with individual pages can be opened and directly accessed via new browser windows.
To Fix	If building a single-page app, make sure the client-side router can re-construct app state from a given URL.

Advanced Requirements (Exemplary PWAs) #

The basic requirements for a PWA represent an "MVP" of what a PWA can be. These advanced requirements point out to additional resources, concepts and ideas that will make the app even better.

These fall under the "nice to have" or "these are optional but strongly encouraged" parts of a PWA.

Whether a PWA or a regular site we want to make sure that search engines can find your app and show it to potential users. Because the concept of PWA is new there hasn't been much done in the search engine space and discoverability spacces. Microsoft Bing search engine has taken the lead in this area.

We [Microsoft] are already using the Bing Crawler to identify PWAs on the Web for our PWA research. The Web App Manifest is a proactive signal from developers that a given website should be considered an app; we’re listening to that signal and evaluating those sites as candidates for the Store. Once we identify quality PWAs, we’ll automatically generate the APPX wrapper format used by the Windows Store and assemble a Store entry based on metadata about the app provided in the Web App Manifest. Aarong Gustafson - Progressive Web Apps and the Windows Ecosystem

For more information, see Google's guide to social optimization and social discovery.

Site's content is indexed by Google
To Test	Use the Fetch as Google tool to preview how Google will see your site when it is crawled.
To Fix	Google's indexing system does run JavaScript but some issues may need to be fixed to make content accessible. For example, if you are using new browser features like the Fetch API, ensure that they are polyfilled in browsers without support.

Just like regular pages, the pages of a PWA bennefit from metadata. This will help Google and other searc engine crawlerss to better index your content. See the examples under the to-fix section for ideas of what you can do with Metadata. Also check James Williams course on HTML5 structured data on Linkedin Learning

Note that this refers to generic metadata, not the one you'd use for Facebook or Twitter. That comes in the next section.

Schema.org metadata is provided where appropriate
Schema.org metadata can help improve the appearance of your site in search engines.
To Test	Use the testing tool to ensure title, image, description etc. are available.
To Fix	Markup the content. For example: A recipe app should have the Recipe type markup for Rich Cards. A news app should have the NewsArticle type markup for Rich Cards and/or AMP support. An ecommerce app should have the Product type markup for Rich Cards.

Social metadata is the other part of making you applicaation known and includes Facebook, Twitter, Google+ and others.

Social metadata is provided where appropriate
To Test	Open a representative page in Facebook's crawler and ensure it looks reasonable Check that Twitter Cards meta data is present (for example <meta name="twitter:card" content="summary" />) if you feel it would be appropriate
To Fix	Mark up content with Open Graph tags and as advised by Twitter.

Some sites still use 2 sites for the same content, one is the standard www and the other one is a specialized mobile site, usually called m-dot (m.site.com). To help search engine crawlers use the rel="canonical attribute of the link tag to tell the crawler which one is the canonical version.

Canonical URLs are provided when necessary
This is only necessary if your content is available at multiple URLs.
To Test	Determine whether any piece of content is available at two different URLs. Open both of these pages and ensure they use <link rel=canonical> tags in the head to indicate the canonical version

To Fix Add a canonical link tag to the of each page, pointing to the canonical source document. See Use canonical URLs for more information.

The history API lets you programmatically control the navigation of your app. Using it means that your users will be able to navigate throughout the application without having to worry if the browser will remember the sites you visited.

Pages use the History API
To Test	For single page apps, ensure the site doesn't use fragment identifiers. For example everything after the #! in https://example.com/#!user/26601.
To Fix	Use the History API instead of page fragments.

User experience #

A PWA is no different than any other app in how users will react to poor UX and UI. We need to present a great user experience as we can.

Ensure all content, especially images and ads, have fixed sizing in CSS or inline on the element. consider ways to present a preview of the content until it's downloaded.

Content doesn't jump as the page loads
To Test	Load various pages in the PWA and ensure content or UI doesn't "jump" as the page loads
To Fix	Ensure all content, especially images and ads, have fixed sizing in CSS or inline on the element. Before the image loads you may want to show a grey square or blurred/small version (if available) as a placeholder

This is an interesting case. I seldom see this being enforced but the user experience works consistently and doesn't make you scroll up or down to get to the section of the content we were looking at.

Pressing back from a detail page retains scroll position on the previous list page
To Test	Find a list view in the app. Scroll down. Tap an item to enter the detail page. Scroll around on the detail page. Press back and ensure the list view is scrolled to the same place it was at before the detail link/button was tapped.
To Fix	Restore the scroll position in lists when the user presses 'back'. Some routing libraries have a feature to do this for you.

In mobile most applications will use the system's virtual keyboard. When the keyboard appears, make sure the content is not obscured under the keyboard.

When tapped, inputs aren't obscured by the on screen keyboard
To Test	Find a page with text inputs. Scroll to put the text input as low on the screen as you can make it. Tap the input and verify it is not covered when the keyboard appears.
To Fix	Explore using features like Element.scrollIntoView() and Element.scrollIntoViewIfNeeded() to ensure the input is visible when tapped.

Content is easily shareable from standalone or full screen mode
To Test	Ensure from standalone mode (after adding the app to your home screen) that you are able to share content, if appropriate, from within the app's UI.
To Fix	Provide social share buttons, or a generic share button within your UI. If a generic button, you may want to directly copy the URL to the user's clipboard when tapped, offer them social networks to share to, or try out the new Web Share API to integrate with the native sharing system on Android.

Site is responsive across phone, tablet and desktop screen sizes
To Test	View the PWA on small, medium and large screens and ensure it works reasonably on all.
To Fix	Review our guide on implementing responsive UIs.

Any app install prompts are not used excessively
To Test	Check the PWA doesn't use an app install interstitial when loaded
To Fix	There should only be one top or bottom app install banner After the PWA is added to the user's home screen, any top/bottom banners should be removed.

Whenever you use Add to Home Screen you're responsible for not annoying your users by presenting A2HS before the user had the chance to evaluate your site and make a decision or at inoportune times.

The Add to Home Screen prompt is intercepted
To Test	Check the browser doesn't display the A2HS at an inopportune moment, such as when the user is in the middle of a flow that shouldn't be interrupted, or when another prompt is already displayed on the screen.
To Fix	Intercept the beforeinstallprompt event and prompt later Chrome manages when to trigger the prompt but for situations this might not be ideal. You can defer the prompt to a later time in the app's usage.

Performance #

Users are pushy and expect more than our apps. They want them fast and they want responsive and they want high quality. This section will look at the performance requirements for great PWAs.

First load very fast even on 3G
To Test	Use Lighthouse on a Nexus 5 (or similar) to verify time to interactive < 5s for first visit on a simulated 3G network (as opposed to the 10s goal for baseline PWAs)
To Fix	Review the performance section of WebFundamentals and ensure you're following the best practices. You can understand your performance better by using Pagespeed Insights (aim for a score >85) and SpeedIndex on WebPageTest (aim for a score <4000 on the first view on Mobile 3G Nexus 5 Chrome). A few tips are to focus on loading less script, make sure as much script is loaded asynchronously as possible using <script async> and make sure render blocking CSS is marked as such.

Caching #

One of the great things about PWAs is that they smooth out network connections making PWAs look like they are faster.

We can accomplish the caching performance with service worker that use cache-first strategies. This will pull the data from the cache and, only if not cached, will fetch it from the network and store it in the cache.

There are exceptions to the rule. You may not want to cache large videos, audio or other large files. If so present the user with cues that the content is not available offline.

Site uses cache-first networking
To Test	Set the network emulation to the slowest setting and browse around the app. Then, set the network emulation to offline and browse around. The app should not feel faster when offline than on a slow connection.
To Fix	Use cache-first responses wherever possible.

There are times when it's important for the user to know if they are offline. For example: You should tell the user they are offline if they are trying to complete an ecommerce transation or trying to view videos that are only available online.

Site appropriately informs the user when they're offline
To Test	Emulate an offline network and verify the PWA provides an indication that you are offline.
To Fix	Use the Network Information API to show the user an indication when they're offline.

Push notifications #

This check list only applies if notifications are implemented. Adding push notifications is not a requirement for an exemplary progressive web app.

Always provide context for the user to decide if they should enable notifications. Tell them what types of messages your app will push and be explicit as to what permissions you want. If you're asking for permission to use Push Notifications then do just that.

If your app is requesting permission for push notification on first visit you better have a good explanation right up front as to why you're asking before users have a chance to exprience your app.

Provide context to the user about how notifications will be used
To Test	Visit the site, and find the push notifications opt-in flow When you are shown the permission request by the browser, ensure that context has been provided explaining what the site wants the permission for If the site is requesting for the permission on page load, ensure it provides very clear context simultaneously for why the user should enable push notifications
To Fix	See our guide to creating user-friendly Notifications permissions flows.

Please, please, please don't annoy your users by presenting them with Push Notification signups on every page of your site. Remember that if they block your application, it will stay blocked until they decide to unblock it an add notifications from your site.

As the test below indicates, if the user doesn't opt in to your application's notification workflow you shouldn't prompt them againn in the same session.

UI encouraging users to turn on Push Notifications must not be overly aggressive.
To Test	Visit the site and find the push notifications opt in flow. Ensure that if you dismiss push notification, the site does not re-prompt in the same way within the same session.
To Fix	If users say they don't want a certain kind of notification, do not reprompt for at least a few days (for example, one week).

Site dims the screen when permission request is showing
To Test	Visit the site and find the push notifications opt-in flow. When Chrome is showing the permission request, ensure that the page is "dimming" (placing a dark overlay over) all content not relevant to explaining why the site needs push notifications.
To Fix	When calling Notification.requestPermission dim the screen. Undim it when the promise resolves.

If you decide to use push notifications in your site make sure they are relevant ant timely. By this I mean that the user only gets notifications when they perform and acction, therre is new/updated information, something happens that requires the user to take action and it's about the site they are visting.

Push notifications must be timely, precise and relevant
To Test	Enable push notifications from the site and ensure the use cases they're using the push notifications for are: Timely — A timely notification is one that appears when users want it and when it matters to them Precise — A precise notification is one that has specific information that can be acted on immediately Relevant — A relevant message is one about people or subjects that the user cares about
To Fix	See our guide on creating great push notifications for advice. If your content is not timely and relevant to this user, consider using email instead.

Make sure the user has a way to disable and, hopefully, reenable notifications without going to the browser's UI to do so.

Provides controls to enable and disable notifications
To Test	Enable push notifications from the site. Ensure there is some place on the site that allows you to manage your notifications permissions or disable them.
To Fix	Create a UI that allows users to manage their notification preferences.

Additional features #

These are additional features that make PWAs easier to work with. They only apply if you're using the API on your site/app.

User is logged in across devices via Credential Management API
This only applies if your site has a sign in flow.
To Test	Create an account for a service and ensure you see the save password/account dialog show up. Click "Save". Clear cookies for the site (via clicking on the padlock or Chrome settings) and refresh the site. Ensure that you either see an account picker (e.g. if there are multiple accounts saved) or are automatically signed back in. Sign out and refresh the site. Ensure that you see the account picker.
To Fix	Follow our Credential Management API Integration Guide.

User is logged in across devices via Credential Management API
This check only applies if your site accepts payments.
To Test	Enter the payment flow. Instead of filling out a conventional form, verify the user is able to pay easily via the native UI triggered by the Payment Request API.
To Fix	Follow our Payment Request API Integration Guide.

Edit on Github

rolling your own Node CLI tools PWA Starter: More APIs to make an even better PWA