Progressive Web Applications
Some extra configuration enables a Vaadin application to run as a Progressive Web Application (PWA). PWAs aim to give the same experience as native applications, with a user-friendly installation flow, and a capability to work offline. They look like a regular application in the home screen of a mobile device or in the application menus of a desktop operating system. A PWA needs some metadata, such as name, description, and icon, which are used by the operating system to display information about the application.
To enable offline use, TypeScript needs to be used to provide the offline views. Hilla is the recommended framework to build client-side views.
For a generic introduction to PWA, see the article on What are Progressive Web Applications and Why Build a PWA.
Progressive Web Application Concepts
All PWAs have the following common basic features that enable native-app-like behavior:
- Web Application Manifest
-
The manifest provides information about an application, for example its name, theme, icon, and description. These details are needed to make an installable version of the web application.
See PWA Web Application Manifest for details about defining a manifest.
- Service Worker
-
A service worker is a type of web worker, a JavaScript program that runs in the background. Its ability to intercept network requests makes it possible to serve files directly from the browser’s cache and create a full application experience, even when no network is available.
Essentially, it’s a JavaScript file that:
-
runs separately from the main browser thread;
-
intercepts network requests;
-
caches and retrieves resources from the cache;
-
delivers Push messages.
See PWA Service Worker for details about defining a service worker.
-
Creating PWAs with Flow
Vaadin Flow automatically serves the required resources for a PWA when you use the @PWA
annotation in the Application Shell.
The @PWA
annotation must be placed in the Application Shell class.
For example, you can use the @PWA
annotation to automatically serve PWA resources as follows:
@PWA(name = "My Progressive Web Application",
shortName = "MyPWA")
public class AppShell implements AppShellConfigurator {
}
The Vaadin server automatically serves the manifest, service worker, icons, and offline experience, and adds the necessary additions to the application headers.
The shortName
parameter shouldn’t exceed 12 characters.
See PWA Web Application Manifest for a list of @PWA
annotation parameters you can use.
Application Installation Requirements
To support installation on devices, the following features are required. These depend on the device and browser used:
- Icons
-
Different icon sizes are needed to support different devices. To enhance the experience, splash screen images are also required.
- Offline support
-
The service worker must be able to respond to serve the client if a network isn’t available.
- Header information
-
The application must include browser- and/or device-specific theming and icon data in the header. This is in addition to the manifest file.
- HTTPS
-
Many new browser features, including those required for PWAs, require HTTPS. Even if your PWA currently works without HTTPS in some environments (for example, Android), this is likely to change and PWAs that don’t support HTTPS probably malfunction in the future.
PWA Web Application Manifest
When the @PWA
annotation is found, Vaadin automatically generates a web application manifest file named manifest.webmanifest
.
Here is a list of properties in the file that you can customize.
Except for scope
, all properties can be set in the @PWA
annotation.
name
-
The name of the application. Set this property in the
name
parameter in the@PWA
annotation. short_name
-
The short name of the application. This shouldn’t exceed 12 characters. It’s used on the device home screen, where there is a limited amount of space. Set this property in the
shortName
parameter in the@PWA
annotation. description
-
The description of the application. The default value is an empty string. Set this property in the
description
parameter in the@PWA
annotation. display
-
Defines the preferred display mode for the application. The default value is
standalone
. Set this property in thedisplay
parameter in the@PWA
annotation. background_color
-
The background color of the application. The default value is
#f2f2f2
(gray). Set this property in thebackgroundColor
parameter in the@PWA
annotation. theme_color
-
The theme color of application. The default value is
#ffffff
(white). Set this property in thebackgroundColor
parameter in the@PWA
annotation. scope
-
Defines the navigation scope of the website’s context. This restricts the web pages that can be viewed while the manifest is applied. The value is set to the context path of application. You can’t change this property in the
@PWA
annotation. start_url
-
The start URL that’s navigated to when the application is launched from the installed application (home screen). The default value is an empty string
""
that points to the default route target for the application (marked with@Route("")
). Set this property in thestartPath
parameter in the@PWA
annotation. icons
-
Automatically created from icon resources.
Note
| For more information about these properties, see Web Application Manifest in the Mozilla Developer Network (MDN) web docs. |
Renaming the Manifest
You can change the default name (manifest.webmanifest
) of the web application manifest, using the manifestPath
parameter in the @PWA
annotation.
The following example shows how to do this:
@PWA(name = "My Progressive Web Application",
shortName = "MyPWA",
manifestPath = "manifest.json")
Overriding the Generated Manifest
You can override the generated manifest file with a custom manifest.
To override the generated web application manifest file:
-
Create a custom manifest file and name it to match the file name set in the
manifestPath
parameter in the@PWA
annotation, for examplemanifest.webmanifest
. -
Add the file to your
src/main/webapp/
folder.
PWA Service Worker
When the @PWA
annotation exists, Vaadin automatically generates a simple service worker during application startup.
The generated service worker:
-
caches offline resources, including the TypeScript views, offline page, icons, and custom (user-defined) offline resources;
-
handles the offline experience, by serving the TypeScript views offline, or the separate offline page.
Note
| The service worker can only respond to full navigation events, such as refresh or direct navigation to a URL. |
The service worker uses Google Workbox to cache resources.
Defining Custom Cache Resources
You can define custom resources to be cached automatically by the service worker, using the offlineResources
parameter in the @PWA
annotation.
For example, to define styles/offline.css
, img/offline.jpg
and js/jquery.js
as offline resources for caching:
@PWA(name = "My Progressive Web Application",
shortName = "MyPWA",
offlineResources = {
"styles/offline.css", "js/jquery.js", "img/offline.jpg" })
Overriding the Generated Service Worker
You can override the generated service worker with a custom service worker.
To override the generated service worker file, create the file named sw.ts
in the frontend
folder.
Note
|
Default service worker
To ensure that your custom service worker deals with offline support and resource caching, you can copy the default service worker from target/sw.ts and use it as a template.
|
PWA Application Icons
PWAs need at least three icons: a favicon for the browser page, a device icon for the installed application, and an icon used on the splash screen of the installed application.
Using a Custom Icon
Vaadin uses and serves default PWA icons automatically, but you can use a custom icon.
To use a custom icon image:
-
Create an icon image named
icon.png
. The icon must be inPNG
format. -
Add the image to
icons/
in your static web resources (src/main/resources/META-INF/resources/icons/
in Spring projects,src/main/webapp/icons/
for non-Spring projects).
Vaadin automatically scans for an image named icon.png
in the /icons
folder in the webapp
resources folder.
It uses this image to create appropriately sized images for different devices.
If no icon is found, the default image is used as a fallback.
To ensure that all resized images are attractive, use an image of at least 512 × 512 pixels. This is only large enough to be scaled down, as scaling up can cause pixelation.
Overriding Generated Icons
All generated images are named using the icon-[width]x[height].png notation, for example icon-1125x2436.png.
To override a generated image:
-
Create an image of the size you want to override and name it using the notation mentioned above; for example,
icon-1125x2436.png
for a custom high-resolution splash screen image for iOS devices. -
Add the image to
icons/
in your static web resources (src/main/resources/META-INF/resources/icons/
in Spring projects,src/main/webapp/icons/
for non-Spring projects).
Renaming Icons
You can change the default icon path to a custom path, using the iconPath
parameter in the @PWA
annotation.
A custom path can be defined with the iconPath
parameter in the @PWA
annotation, as shown in the following example:
@PWA(name = "My Progressive Web Application",
shortName = "MyPWA",
iconPath = "img/icons/logo.png")
PWA Offline Experience
Vaadin supports two alternative ways of building offline experiences:
-
Client-side TypeScript views (default)
-
A separate offline page
For PWAs built with Vaadin, the service worker provides offline support for TypeScript routes and views. This enables building custom view logic in the offline mode. By default, it stores the application shell HTML, the compiled front-end bundles, and the other necessary resources, and then serves them offline from the browser’s cache.
When it isn’t required to build application views that work offline (for example, if it’s enough only to display a static content page in the offline mode), you can optionally use a separate offline page instead of TypeScript views (offlinePath
property in @PWA
annotation).
Offline TypeScript Views
Adding the @PWA
annotation on your application shell class enables the service worker, which automatically serves the client-side views offline.
The service worker also caches and serves offline all the imported dependencies (using import
) in TypeScript views.
Creating a Custom Offline Page
To use a separate offline page:
-
Create a file named
offline.html
. -
Add the file to your static web resources directory (
src/main/resources/META-INF/resources/
in Spring projects,src/main/webapp/
for non-Spring projects). -
Specify
offlinePath="offline.html"
in the@PWA
annotation.
You can change the name of the specified offline page file in the offlinePath
parameter.
The offline page can only use resources found in the cache.
By default, only the offline page, manifest, and icons are cached.
If your page needs external resources (such as CSS, images, Web Components), you can define them using the offlineResources
parameter in the @PWA
annotation.
See Defining Custom Cache Resources for more.
@PWA(name = "My Progressive Web Application",
shortName = "MyPWA",
offlinePath = "offline.html")
public class AppShell implements AppShellConfigurator {
}
Generated Offline Page
The generated offline page provides compatibility with PWAs built with earlier versions of Vaadin. Consider using TypeScript views offline, or a custom offline page.
Vaadin has a built-in offline.html
generated offline page.
This is a simple page that:
-
includes the application name and icon;
-
communicates to the user that the application is offline, because there is no network connection.
To use the built-in offline page, specify offlinePath="offline.html"
, as in the earlier example.
EE06DDFE-6934-49E0-AF99-2316376BD26C