PWA template

[SteveSandersonMS]

The core idea this design is based on is that we want to minimize ties that Blazor has to any specific approach to service workers or offline support. This is because:

• Offline support is really tricky to get right and is full of gotchas and caveats. The desired solution will always vary by per-application requirements.
• In practice, people want to integrate with various types of tooling for generating service workers, such as sw-precache or workbox. If we had any Blazor-specific requirements, people would struggle to figure out how to make third-party tools comply with those requirements.

So, the approach used in this PR is to simplify things down to a really minimal, safe implementation that can exist entirely within the template. We're not shipping service worker features; we're just shipping an example of one way to do it in the template. Anyone who wants to do things a different way can do so, using whatever APIs or 3rd-party tooling they want, because there's literally nothing Blazor-specific in the requirements. Getting to this point of "no Blazor-specific requirements" is the whole point of doing #18859, which entirely removes .NET assemblies and linking from the picture as far as offline support is concerned.

Update: After discussions, we decided that we do want to ship some serviceworker-related build tooling. Specifically, we want to generate on build a manifest of the static files being published. Then a service worker can read this manifest and use its own logic to decide which of those files to actually cache for offline use.

#18859 is no longer a prerequisite for this work, but since it now exists and gives a significant measurable improvement to load times when not using a service worker, we should keep that anyway as an independent piece. It doesn't conflict with what we have here.

Offline strategy

There are many different ways to do offline. The biggest choice is between "network first" and "offline first" strategies. A "network first" approach always tries to get updates from the network, and falls back on cached data if the network is unavailable. A "cache first" approach always uses content from the cache, and separately updates the cache in the background at certain times.

The safest way to do offline is "cache first", so that's what we do here. It's also the same choice taken by Create-React-App's PWA mode and Polymer's PWA Starter Kit. The reason is:

• Offline/online is not really a binary distinction. There are different levels of network access. A common case with mobiles or captive portals is "device thinks it's online, but in practice the network is too slow to wait for, or returns invalid results (captive portals)". A network-first solution gets stuck on this, while an offline-first one is not affected.
• Without having more knowledge of the functional purpose of the files you're caching, you cannot assume it's safe to combine some resources from an older deployment with some from a newer deployment. So it's undesirable to go to the network for possible updates for each file individually. Instead, you want to check if the whole application has been updated, and if so, to get a complete new set of files in a separate cache, and only switch over to the new set once that whole set is obtained. This basically implies per-resource access is cache-first.

The specific mechanism for detecting service worker changes, creating a new cache, populating it, and only switching over once it's fully populated without errors, is a pattern designed into the basic service worker APIs (the "install"/"activate" cycle). There are awkward issues with it:

1. After you deploy an update, visitors will continue to use the old application for at least one visit before they start using the new application. Therefore if you're making API changes (e.g., changing the URL for some JSON API), you must make all changes in a back-compatible way, at least until you believe all clients will have upgraded. Or have some "version check" take place when the app first starts and refuse to function if out of date, like many native mobile apps do.
2. Most confusingly, even once an updated service worker is installed, it will not "activate" until the developer/user closes all browser tabs for your site. It is not sufficient just to refresh a tab. The reasons for this are subtle.

We will need to document these caveats. Despite these issues, this is the most standard way to build a service worker, and is the same as other major templates/starter kits do.

I strongly considered putting more complex logic into the service worker to mitigate one or both of these (for example, offline-first, but even before that try asking the network to check for updates, and if we find one then switch to network-first). However there are too many reasons why doing nonstandard things would blow up in our faces, so I think it's better to focus on ensuring developers can put in any custom service worker logic of their own.

With the implementation here, offline support is only enabled for published apps. It doesn't make sense to try doing offline support during development because:

1. After each change, you wouldn't see updates immediately, due to the caveats listed above
2. We only regenerate the assets manifest on build. If you edit files in wwwroot (or SWA in wwwroot in reference projects) and reload, the offline-first strategy would have no way to know there are any changes to fetch. And even if it did, the hash checks would fail until you next build and regenerate the manifest.

Developers who want to do their own different thing can do whatever they want. For example, they could implement a network-first strategy with no hash checking, in which case it would be fine to enable that in development (but would have lots more caveats in production).

[pranavkm]

Why not publish it without the published.js extension?

[SteveSandersonMS]

We do, that's what this does. Or are you suggesting this should be implemented differently?

I've tried to keep the MSBuild logic here incredibly basic. For example, not assuming the developer even knows what an item group is. It's just properties, which should be familiar to any OO developer.

[javiercn]

I think that I agree with Pranav, I feel it is better to do this outside of the user project. I don't think that the logic here is simple. We introduce the user to several MSBuild concepts and properties and it is not straightforward to understand what is happening here.

We could do this in several different ways:

• Add a new package for doing service workers.
  • All the logic gets encapsulated there and we trigger it based on the presence of a service-worker.js file on your app.
  • The fact that you added the package is the gesture you want the SW.
  • Everything gets handled transparently for you.
• We put the logic inside blazor.build
  • Same deal, but no package.
  • We would need a property to turn it off
  • Would be turned on by default based on the presence of a given file.

[javiercn]

Haven't looked at the tests and other stuff yet, but I think that we could find an approach that strikes a better balance between simplicy and making our customers successful.

The reason I think that is the case, is that it makes it really hard for customers to be successful once their project grows beyond the most basic requirements, and while customers can use other toolchains to do very sophisticaded stuff to get their SW code generated automatically, I feel it is too complex of a choice to say just use webpack or something similar.

I believe that we should strive for a middle ground that leverages our strengths and doesn't set up our customers for failure once they go beyond the basics.

My concrete proposal involves:

• Have a single service-worker.js file.
• Produce a separate file with the list of all the resources and options for the service worker in a script form.
  • Can be json, can be JS with an exported object.
  • Can include just the list of resources or a more future proof config object that can be passed down to the SW.
• Filter the resources based on the list included in the service worker.
• Intercept fetch requests based on the options imported.
• We can generate both files at build time and automatically add the appropriate Content items to the build for you.
• You get to configure your service worker however you want.
  • We simply give you facilities to leverage the existing knowledge we already have during the build.
    • For example, other SW implementations can leverage this by importing the script/json file with this data.

[javiercn]

I think that I agree with Pranav, I feel it is better to do this outside of the user project. I don't think that the logic here is simple. We introduce the user to several MSBuild concepts and properties and it is not straightforward to understand what is happening here.

We could do this in several different ways:

• Add a new package for doing service workers.
  • All the logic gets encapsulated there and we trigger it based on the presence of a service-worker.js file on your app.
  • The fact that you added the package is the gesture you want the SW.
  • Everything gets handled transparently for you.
• We put the logic inside blazor.build
  • Same deal, but no package.
  • We would need a property to turn it off
  • Would be turned on by default based on the presence of a given file.

[SteveSandersonMS]

Re-requesting review from @javiercn @pranavkm because this is now dramatically changed to reflect the outcome of our design discussions.

And there's now an E2E test showing it actually works offline :)

[javiercn]

👍

[javiercn]

This test is D O P E

[javiercn]

This is super dope. I like a lot how it turned out.

Great changes!