Make a Vaadin Flow Application an Installable PWA

How to define a custom offline page and enable installation on supported devices.

Understanding PWAs
PWA Resources
Customize Offline Page
Test Offline Page

Important

Deprecated

This tutorial is no longer maintained. It’s accessible, though, until the new tutorial is completed, which involves adding all of the topics in this tutorial to the new one.

On this part of this tutorial, you’ll turn the completed Customer Relationship Management (CRM) application into a Progressive Web Application (PWA), so that users can install it.

Understanding PWAs

The term PWA is used to describe modern web applications that offer a user experience similar to a native application. PWA technologies make applications faster, more reliable, and more engaging.

PWAs can be installed on most mobile devices and on desktops when using supported browsers. They can even be listed in the Microsoft Store and Google Play Store. You can learn more about the underlying technologies and features in the PWA configuration documentation.

Two main components enable PWA technologies:

ServiceWorker: a JavaScript worker file that controls network traffic and enables custom cache control.
Web application manifest: a JSON file that identifies the web application as an installable application.

PWA Resources

Vaadin provides the @PWA annotation, which automatically generates the required PWA resources. Add the @PWA annotation on Application.java as follows:

@SpringBootApplication
@Theme(value = "flowcrmtutorial")
@PWA( 1
    name = "Vaadin CRM", 2
    shortName = "CRM" 3
)
public class Application extends SpringBootServletInitializer implements AppShellConfigurator {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

The @PWA annotation tells Vaadin to create a ServiceWorker and a manifest file.
name is the full name of the application for the manifest file.
shortName should be short enough to fit under an icon when installed, and shouldn’t exceed 12 characters.

Application Icon

You can override the default icon by replacing src/main/resources/META-INF/resources/icons/icon.png with another 512px × 512px PNG icon.

You can use your own icon, or save a sample image, by right-clicking the link and selecting Save Link As. Be sure to have the file in PNG format.

Customize Offline Page

Vaadin creates a generic offline fallback page that displays when the application is launched offline. You can make your application appear more polished by replacing this default page with a custom page that follows your own design guidelines.

Use the code below to create offline.html in the src/main/resources/META-INF/resources folder:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <meta http-equiv="X-UA-Compatible" content="ie=edge"/>
    <title>Offline | Vaadin CRM</title>
    <style>
        body {
            display: flex;
            flex-direction: column;
            align-items: center;
            font-family: sans-serif;
            color: #555;
        }

        .content {
            width: 80%;
        }

        .offline-image {
            width: 100%;
            margin: 4em 0px;
        }
    </style>
</head>
<body>

<div class="content">
    <img src="./images/offline.png" alt="VaadinCRM is offline" class="offline-image"/>
    <h1>Oh deer, you're offline</h1>
    <p>Your internet connection is offline. Get back online to continue using Vaadin CRM.</p>
</div>
<script>
    window.addEventListener('online', () => window.location.reload()); 1
</script>
</body>
</html>

The JavaScript snippet reloads the page if the browser detects that it’s back online.

Add the following image — or use one of your own — to the META-INF/resources/images folder and name it offline.png.

You can make the files available offline by adding them to the @PWA annotation in Application as follows:

@PWA(
    name = "VaadinCRM",
    shortName = "CRM",
    offlinePath="offline.html",
    offlineResources = { "./images/offline.png"} 1
)

offlineResources is a list of files that Vaadin makes available offline through the ServiceWorker.

Now, restart the application. You can install it on supported browsers.

Test Offline Page

Shut down the server in IntelliJ and refresh the browser — or launch the installed application. You should now see the custom offline page.

On the next part of this tutorial, you’ll add both unit tests and in-browser tests to the application.

migration assistance

Download free e-book.
The complete guide is also available in an easy-to-follow PDF format.

Open in a
new tab
export class RenderBanner extends HTMLElement {
  connectedCallback() {
    this.renderBanner();
  }

  renderBanner() {
    let bannerWrapper = document.getElementById('tocBanner');

    if (bannerWrapper) {
      return;
    }

    let tocEl = document.getElementById('toc');

    // Add an empty ToC div in case page doesn't have one.
    if (!tocEl) {
      const pageTitle = document.querySelector(
        'main > article > header[class^=PageHeader-module--pageHeader]'
      );
      tocEl = document.createElement('div');
      tocEl.classList.add('toc');

      pageTitle?.insertAdjacentElement('afterend', tocEl);
    }

    // Prepare banner container
    bannerWrapper = document.createElement('div');
    bannerWrapper.id = 'tocBanner';
    tocEl?.appendChild(bannerWrapper);

    // Banner elements
    const text = document.querySelector('.toc-banner-source-text')?.innerHTML;
    const link = document.querySelector('.toc-banner-source-link')?.textContent;

    const bannerHtml = `<div class='toc-banner'>
          <a href='${link}'>
            <div class="toc-banner--img"></div>
            <div class='toc-banner--content'>${text}</div>
          </a>
        </div>`;

    bannerWrapper.innerHTML = bannerHtml;

    // Add banner image
    const imgSource = document.querySelector('.toc-banner-source .image');
    const imgTarget = bannerWrapper.querySelector('.toc-banner--img');

    if (imgSource && imgTarget) {
      imgTarget.appendChild(imgSource);
    }
  }
}

2861D7D6-5025-4A8B-A866-38C01AF5FF91

Docs