Using the Lighthouse Plugin

The easiest way to use Lighthouse is through the Lighthouse extension² Google publishes. To install the extension,

2. https://chrome.google.com/webstore/detail/lighthouse/blipmdconlkpinefehnmjammfjpmpbjk

• Open Chrome or one of the browsers built using Chromium (like Microsoft Edge), and open the Chrome Web Store (by either opening the Extensions page or searching for it).

• Search for the Lighthouse extension in the store.

• Click the Add to Chrome button to install the extension in the browser.

With the extension installed, Chrome adds a lighthouse icon to the toolbar, as shown in Figure 8.1.

In the browser, navigate to the Tip Calculator app running in the local server process (started in Preparing to Code), then click the Lighthouse button.

When you click the Options button, Chrome opens a dialog allowing you to set the scope for the audit performed by the extension, as shown in Figure 8.2. All we care about right now is the PWA report, so enable the Progressive Web App option and disable all others, then click the OK button to return to Lighthouse. You can come back later and try out the other options.

Click the Generate Report button shown in Figure 8.1, and Chrome opens a new window hosting the selected web app in a simulated mobile device and exercises the app in different conditions. I haven’t studied exactly what tests it performs, but you can tell that it’s loading the app with and without network connectivity and recording what happens in the app. When it completes its assessment, Chrome opens the page shown in Figure 8.3 listing the results of the audit.

As you can see from the figure, the results are dismal. Remember though, this is the bare bones version of the Tip Calculator app; it doesn’t have a manifest file or a service worker, so the results should not be a surprise. Knowing what you know by now about service workers and manifest files, you should be able to see where these files would bolster the results.

Since I’m hosting the app on Netlify, and they automatically provide an SSL certificate, I get a few extra points here. For your locally hosted app, this result should be different, although in my testing, Lighthouse seemed to incorrectly think I was hosting over an HTTPS connection even when I wasn’t. This is probably an internal browser hack that enables the browser to run PWAs from localhost.

It’s a little hard to see, but at the top of the page is the PWA logo I highlighted in Figure 1.1 so many pages ago. In the report in Figure 8.3, it’s greyed out and hard to see because the app is not a PWA, and that’s a simple way the extension highlights this fact.

If you rerun the report against the complete PWA from the end of Chapter 2, you get the happier results shown in Figure 8.4. Notice that the PWA logo at the top of the report is complete and colored, plus you have this bold green checkmark proudly proclaiming success.

Lighthouse offers several output options, shown in the upper-right corner of Figure 8.5. You can print short or expanded versions of the report or get the report as HTML or JSON.

The report lets you know what work you need to do to deliver the full PWA version of the selected app. You may or may not want to do all the work it recommends, but that’s up to you. Lighthouse is just a quick and simple litmus test for PWAs.

The browser extension is my preferred approach for running Lighthouse, although I expect that most developers prefer the option outlined in the following section. Generating the report through the extension delivers the report in a new browser window, making it easy to review and print for later reference.

Using the Lighthouse Tools in the Browser

To make it easier for developers to run Lighthouse during the development process, Google provides a Lighthouse audit right inside the Chrome DevTools. There’s no extension to install or any extra setup—it’s just there, ready to go to work.

To access Lighthouse through Chrome DevTools, open a web app in the browser, then open DevTools and look for the Audits tab, shown in Figure 8.6.

Here you have a few more options than what’s available through the extension; you can specify to test the mobile or desktop version of the app and control how the tools throttle the network connection during the audit. Select the options that work for your app, then click the Run Audits button to start the test. When Lighthouse finishes its test, it displays the results in the audit window shown in Figure 8.7.

From the report page, you have limited options: you can (1) create a new audit, clear (2) the report, or (3) download the report in JSON format.

Using the Lighthouse Node Module

You can also install Lighthouse as a node module and run it from a command-line or in a node app. To install the module, open a terminal window or command prompt, then execute the following command:

npm install -g lighthouse

With the module installed, you can run the report against a site using the following command:

lighthouse <url>

In this example, <url> is the site URL you want to audit. For the book’s public Tip Calculator app, you would use the following:

Click here to view code image

lighthouse https://learningpwa.com/tipcalc/

The module launches Chrome and performs the same tests you’ve seen before. The only difference is what it does with the results, as shown in the following output:

Click here to view code image

status Generating results... +1ms
Printer html output written to /Users/johnwargo/learningpwa.com_2019-09-05_07-28-40.
  report.html +79ms
CLI Protip: Run lighthouse with `--view` to immediately open the HTML report in your
  browser +2ms
ChromeLauncher Killing Chrome instance 54056 +1ms

The Lighthouse module generates its output directly to an .html file in the current folder. If you want the module to launch the report in the browser immediately after generating it, you must add the –-view parameter to the command line, as shown in the following example:

Click here to view code image

lighthouse https://learningpwa.com/tipcalc/ --view

Since the module writes its results to the current folder, you must make sure you have write rights to the folder before running the test. As I tested this for this chapter’s content, I opened a command prompt in Windows, switched to the root of my system’s C drive, and executed the command. When the report completed, I received the following error:

Click here to view code image

ChromeLauncher Killing Chrome instance 52092 +80ms
Runtime error encountered: EPERM: operation not permitted, open
  'C:	ip-calc-test.netlify.com_2019-08-31_15-43-46.report.html'
Error: EPERM: operation not permitted, open
  'C:	ip-calc-test.netlify.com_2019-08-31_15-43-46.report.html'

This happened because Windows users don’t have access to the root of drive C by default. When I switched to a folder where I had write permissions, the module worked as expected.

You can also use the module in a node app, and Google provides complete instructions.³ I must admit that I struggle to find a use case for this; the results you get from running Lighthouse is a lot of data, and I can’t see the need to write an app that parses and understands the results.

3. https://github.com/GoogleChrome/lighthouse/blob/master/docs/readme.md#using-programmatically

Using the PWABuilder UI

To use PWABuilder, fire up your browser of choice and navigate to https://pwabuilder.com; the browser will open the page shown in Figure 8.8. Enter the URL for a publicly available web app in the input field, then click the Start button to continue. You can use my https://tip-calc-test.netlify.com/ app if you’d like.

The app churns for a little while, then delivers the report shown in Figure 8.9. Here, PWABuilder highlights the PWA deficiencies for the provided web app. Reading through this report, you should see that it lists a lot of the same information provided by Lighthouse. What happens next is what differentiates PWABuilder from Lighthouse.

Notice the options on the report page to View Generated Manifest and Choose a Service Worker. As part of the work it did scanning the app, it built a manifest file using information it gleaned from the app. PWABuilder also offers a catalog of service workers you can use in your app. I’ll cover both options in a minute.

If you scroll down the report page, you’ll see a list of options for adding additional features to an app, shown in Figure 8.10. This links you to a catalog of free code snippets you can use. The snippet catalog lists some standard browser capabilities, such as geolocation, copy to clipboard, and the ability to install a PWA (a topic covered in Chapter 2), plus some code to interact with several Microsoft services from Microsoft Graph.

This version of the Tip Calculator app doesn’t have a manifest file, so PWABuilder generates one for the app automatically and gives you the ability to tweak it through the web UI. If the app had a manifest file configured, PWABuilder would let you edit it.

At the top of Figure 8.9 is a Manifest tab; click it and you’ll see the page shown in Figure 8.11. PWABuilder builds this manifest file using information it’s able to learn about the app by scanning its contents. For example, it pulls the values for the manifest file’s name and short_name properties from the index.html file’s title attribute. For app icons, it pulls in all of the icons referenced in the index.html file’s icon link elements.

Use the edit fields, shown on the left side of the figure, to change the properties in the manifest file. You can use the Images and Settings tabs in the editor to tweak other aspects of the manifest, adding or removing image files, setting the scope for the app, and more.

With all manifest settings in place, use the code areas on the right side of the page to copy the manifest file and the link to load it over to your web app. The code box in the top-right corner contains the code you must add to your index.html file’s head section to load the manifest. The code box in the lower-right corner of the editor contains the actual manifest file content. You should copy the content, then make a new file in the web app project’s root folder called manifest.webmanifest and place the copied code there.

This process adds the manifest to the project. To make the app installable, use the code snippet available by clicking View Snippet, as shown in the lower-left corner of Figure 8.10. What you’ll find there is pretty much the same code you’ll find in early code examples in Chapter 2.

Next, click on the Service Worker tab, and you’ll see the page shown in Figure 8.12. Here you’ll find sample code and implementation instructions for many of the caching strategies discussed in Chapter 4, “Resource Caching.” PWABuilder doesn’t generate anything here specific to your web app. It just offers some standard options you can copy over into your web app and configure for your app’s needs.

When you add the manifest file to the project and implement a service worker, then run the scan again; you should see different, and hopefully better, results than the ones shown in Figure 8.9. As you can see, letting PWABuilder help you through the process is much easier than all that coding we did in earlier chapters of this book.

Creating Deployable Apps

Another feature of PWABuilder is its ability to generate starter projects for deployable apps for Android, iOS, macOS, and Windows, as shown in Figure 8.13. The technologies used to build or package these apps vary depending on the selected target platform.

For Android, PWABuilder generates a Trusted Web Activities (TWA)⁵ app, a type of Android app that enables PWAs to run in a simple app shell on Android devices. For iOS, PWABuilder generates an Apache Cordova app you can build and deploy to iOS devices. I cover the options for Windows in PWAs and the Microsoft Store later in the chapter. In my testing, I found that some of the projects were half-baked and missing complete instructions. My suggestion is that you download the packages from this page and look at them; perhaps by the time you read this, what’s available will be more useful.

5. https://developers.google.com/web/updates/2019/02/using-twa

Using the PWABuilder CLI

PWABuilder supports a command-line option as well, and what you get is essentially an updated version of what was available with the ManifoldJS project many years ago: the ability to generate deployable apps for multiple target platforms based on a single manifest file.

To install the PWABuilder command-line interface (CLI), open a terminal window or command prompt and execute the following command:

npm install -g pwabuilder

Next, to generate apps based on the web app at a specific URL, execute the following command:

pwabuilder <url>

Replace <url> with the full URL pointing to the source web app. For example, to generate apps for the public Tip Calculator app, you would execute the following command:

Click here to view code image

pwabuilder https://learningpwa.com/tipcalc/

For a locally hosted web app like the ones we created in this book, use the following command:

pwabuilder http://localhost:3001

The PWABuilder CLI will scan the file and warn you if it finds any issues with the app, as shown in the top of Figure 8.14. Since it’s generating apps for each target platform, you should fix these errors before continuing. Next, the tool creates app for multiple target platforms in a folder named with the short name of the scanned app.

You can open the newly created folder and read through the instructions provided with each target platform to build and deploy apps for each.

PWABuilder and Visual Studio

Right after I finished this chapter, Microsoft released a preview version of the PWABuilder extension for Visual Studio Code. It’s still in preview, so I don’t know exactly how this will work when it’s released, but I can at least show you how it works today and hope it’s not too much different in its final form.

To get the extension, open Visual Studio Code and then open the extensions pane, as shown in Figure 8.15. Type pwabuilder in the search field, as shown in the figure, and you should see the extension appear. Click the Install button to add the extension to your Visual Studio Code installation.

With the extension in place, open a web app project in Visual Studio Code, then open the command palette, as shown in Figure 8.16. Type pwa, and the command dropdown should show the available options for PWABuilder, as shown in the figure.

Right now, the only available options are to generate a manifest file or generate a service worker for the selected app project. Since it’s PWABuilder under the covers, what happens next shouldn’t be a surprise. If you select Generate Manifest, Visual Studio Code opens the Manifest Generator page, shown in Figure 8.17.

Populate the form with the same options discussed earlier in the chapter, selecting an icon for the app as well as providing additional settings for the manifest file. When you’re done, click the Generate button on the bottom of the form. At this point, Visual Studio Code prompts you to select the target folder for the manifest, which should be the root folder of the app. When you make your selection, the extension saves the manifest file in a file called manifest.json, then opens the file for editing, as shown in Figure 8.18.

The extension doesn’t update your project’s index.html file to use the manifest, so at this point, you should open that file and add the following line to the <head> section of the file:

Click here to view code image

<link rel="manifest" href="manifest.json">

Save your changes to the file, and your app has the first requirement of an installable PWA: a manifest file.

Adding a service worker to your project follows the same process: open the command palette, type pwa, then select Generate Service Worker. When you select this option, you’ll see the screen shown in Figure 8.19. In this case, the extension isn’t generating a service worker for your project, it’s merely displaying the same service worker options you saw in Figure 8.12.

Follow the instructions on the page to update your project’s landing page (typically the project’s index.html file) with the code necessary to load a service worker, then select the service worker you want to use and add it to the project as well.