Configuration

    The configuration is identical in Flow (Java) and Fusion (TypeScript) applications. For enabling offline use, TypeScript needs to be used for providing the offline views.

    For a generic introduction to PWA, please see the article on What are Progressive Web Applications and Why Build a PWA.

    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 web application.

    See 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 is a JavaScript file that:

    • Runs separated 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 needed resources for a PWA when you use the 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:

    Show code

    Java

    Expand code

    Vaadin server automatically serves the , service worker, , and offline experience, and adds the necessary additions to the application headers.

    The shortName parameter should not exceed 12 characters. See for a list of @PWA annotation parameters you can use.

    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 respond to serve the client if a network is not 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 it is probable that PWAs that do not support HTTPs will malfunction in the future.

    PWA Web Application Manifest

    When the @PWA annotation is found, Vaadin automatically generates a web app manifest file, named manifest.webmanifest.

    Here is a list of properties in the file that you can customize. With the exception of 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

    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 the display parameter in the @PWA annotation.

    background_color

    The background color of the application. The default value is #f2f2f2 (gray). Set this property in the backgroundColor parameter in the @PWA annotation.

    theme_color

    The theme color of application. The default value is #ffffff (white). Set this property in the 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 cannot change this property in the @PWA annotation.

    start_url

    The start URL that is navigated to when the application is launched from the installed app (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 the startPath parameter in the @PWA annotation.

    icons

    Automatically created from .

    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 that:

    Show code

    Java

    Expand code

    Overriding the Generated Manifest

    You can override the generated manifest file with a custom manifest.

    To override the generated web application manifest file:

    1. Create a custom manifest file and name it to match the file name set in the manifestPath parameter in the @PWA annotation, for example manifest.webmanifest.

    When the @PWA annotation exists, Vaadin automatically generates a simple service worker during application startup.

    The generated service worker:

    • Caches , 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.

    The service worker uses 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:

    Show code

    Java

    Expand code

    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.

    PWA Application Icons

    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:

    1. Create an icon image named icon.png. The icon must be in PNG format.

    2. Add the image to icons/ in your static web resources ( 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 x 512 pixels. This is large enough to only 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:

    1. Create an image of the size you want to override and name in using the notation mentioned above. For example, icon-1125x2436.png for a custom hi-res splash screen image for iOS devices.

    2. 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).

    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:

    Show code

    Java

    Expand code

    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 frontend bundles, and the other necessary resources, and then serves them offline from the browser’s cache.

    When building application views that work offline is not needed, for example, if it is enough to only 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:

    1. Create a file named offline.html.

    2. 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).

    3. Specify offlinePath="offline.html" in the @PWA annotation.

    You can change the name of the offline page file specified in the offlinePath parameter.

    The offline page can only use resources found in the cache. By default, only the offline page, manifest, and 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.

    Show code

    PWA annotation with offlinePath setting:

    Expand code

    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.

    To use the built-in offline page, specify offlinePath="offline.html" as in .