Deployment Mode: Vulcanising and Service Worker

Resources of deployed application are different from those used in everyday development. Both structure and the way they are controlled in a browser differ significantly and it should be considered every time we add new web component, integrate maps, charts etc. This should also be considered when adding new icons, css styles or new pages outside the main SPA (Single Page App, which is also PWA, Progressive Web App). Let's dive into this...

The main difference is that almost all JS resources for an SPA is vulcanised into a single JS file. This is done by VulcanizingUtility. The main tool that is used for this, is Rollup.

Rollup, however, is a tool for JavaScript bundling and it can not capture icons into vulcanised file. For example, icon.svg from the snippet below, would not get picked up for vulcanisation.

...
const template = html`
    <style>
        .custom-checkbox {
            background-image: url(/resources/images/icon.svg);
        }
    </style>
    ...
`;
...

/resources/images/icon.svg is just not a dependency in JavaScript modules sense. We consider it as an "external resource" and it should be explicitly passed to the VulcanizingUtility.vulcanize call as the last argument (or into this method for platform "external resources"):

vulcanize(
    component.injector(),
    "../../../tg/platform-web-ui/src/main/resources",
    "../../../tg/platform-web-ui/src/main/web/ua/com/fielden/platform/web",
    "../fleet-web-ui/src/main/resources",
    "../fleet-web-ui/src/main/web/fielden",
    "../../../tg/platform-web-ui/src/main/web/ua/com/fielden/platform/web/",
    "../fleet-web-ui/src/main/web/fielden/",
    System.getProperty("os.name").toLowerCase().contains("windows") ? Vulcanize::windowsCommands : Vulcanize::unixCommands,
    propsAndAdditionalPaths._2,
    propsAndAdditionalPaths._3,
    "/resources/images/icon.svg"
);

Vulcaniser then generates a checksum for this resource and this checksum will then be used for resource loading. This process is controlled by a service worker. Service Worker checks whether the checksum for a resource differs from its previous value. If yes, it reloads the resource, otherwise a cached resource is used. So, if we forget to register "external resource" with the Vulcaniser, then the resource would not get loaded in the deployment mode.

IMPORTANT: please always retest application in the deployment mode in case where some HTML / JS / CSS resources were changed / added / removed, even if it works in the development mode.

In summary:

1. register all "external resources" in either Vulcanize (end-application) or VulcanizingUtility (platform)
2. revulcanise (see https://github.com/fieldenms/tg/wiki/Polymer-3.0-installation#running-vulcaniser for more details)
3. refresh end-application projects and TG projects in Eclipse
4. adjust your application-johndoe.properties to workflow=deployment
5. start server and refresh the app; open context menu -> Inspect -> Application -> Service Worker to observe newly registered service worker
6. retest your changes
7. context menu -> Inspect -> Application -> Service Worker -> Unregister
8. context menu -> Inspect -> Application -> Cache Storage -> remove both our storage entries
9. close all application tabs, that was controlled by already unregistered service worker (to ensure it will be unregistered completely)
10. revert application-johndoe.properties and all vulcanised files, they should not ever be committed (unless you are preparing a release)

P.S. Please note that all pages, which are outside of the main SPA JS script (startup-resources-vulcanized.js), are also considered "external". There are several such resources at the platform level:

1. index.html and dependencies
2. login page dependencies (without login.html)
3. logout.html and dependencies
4. login-initiate-reset.html and dependencies
5. login-initiated-reset.html and dependencies
6. GraphiQL and dependencies
7. GIS component images / fonts

Don't forget to register all new dependencies for those resources as well.

P.S.S. A separate note for app icons, which are registered in application-startup-resources.js using iconsets -- they are not "external" and are vulcanised into startup-resources-vulcanized.js -- no need to register them separately with the Vulcaniser.