Add caching and service worker docs to the web FAQ

[johnpryan]

This adds some information about web caching and service workers to the web FAQ.

cc/ @ditman @kevmoo

[flutter-website-bot]

Visit the preview URL for this PR (updated for commit 50360f3):

https://flutter-docs-prod--pr11397-caching-and-service-workers-77emc0en.web.app

[sfshaza2]

A few little things. I'll go ahead and LGTM, but please fix. :)

[ditman]

This is already published!

https://docs.flutter.dev/platform-integration/web/faq#why-doesnt-my-app-update-immediately-after-its-deployed

Thanks @johnpryan!

[slavap]

@johnpryan @ditman
Unfortunately this section https://docs.flutter.dev/platform-integration/web/faq#how-do-i-clear-the-web-cache-after-a-deployment-and-force-an-app-download
does not provide a working solution and only adds confusion.
There are three ways to solve this:

1. Properly configure cache headers on hosting - it is not so obvious and needs multiple examples.
2. Use "subfolder version" approach - it is simple and works without any headers [web] DeferredLoadException after deploying a new version of app flutter#127459 (comment)
3. Post-processing script for adding ?v=nnn for everything - it is kind of proper implementation of the mentioned section, i.e.

<script src="flutter_bootstrap.js?v=123" async></script>

is naïve, and has to be like bash script from flutter/flutter#127459 (comment)

[johnpryan]

Unfortunately this section does not provide a working solution and only adds confusion.

Do you think we should just remove it? This section is only necessary if you need to clear the web cache immediately after deploying a new version, which is probably not a requirement for most apps. If you have a link we can point to for better guidance I'd be happy to replace it.

Properly configure cache headers on hosting - it is not so obvious and needs multiple examples.

What would those additional examples look like? We are providing a Firebase example in the FAQ now.

Use "subfolder version" approach

This is an interesting approach - have you had any issues with it? Are you using a routing package like go_router?

Post-processing script for adding ?v=nnn for everything - it is kind of proper implementation of the mentioned section, i.e. is naïve, and has to be like bash script from flutter/flutter#127459 (comment)

I think it's a commonly used technique, but you're right it's not as simple as we describe in the docs. I'm happy to provide a link to a blog post or article that explains this technique.

[slavap]

@johnpryan

Do you think we should just remove it?

Of course not! But this section is very important and must provide a complete solution for Flutter Web's caching problems.
Just search how many issues are opened about caching, deferred loading, pubspec version, web worker, ...
Developers are just lost and need a clear detailed explanation.

We are providing a Firebase example in the FAQ now.

Firebase is fine, but it has to be more "generic" - i.e. which headers for which files, and then how to implement this strategy on different hosting platforms (e.g. Firebase, AWS, Azure, self-hosted Apache, Tomcat, ...). Perhaps the community could help here.

This is an interesting approach - have you had any issues with it? Are you using a routing package like go_router?

For me, it works great. But I'm using auto_route and not bothering about # in urls.
The only reported problem was about using it with "path URL strategy", but even for that case there is a workaround flutter/flutter#127459 (comment)
So I believe this solution could be added to the docs, considering it does not require any cache headers config on hosting.
Actually, this trick is partially influenced by GWT, which compiles deferred scripts to a unique named subfolder on every build.

not as simple as we describe in the docs. I'm happy to provide a link to a blog post or article that explains this technique.

you may directly add this link to the docs flutter/flutter#127459 (comment)
OR just copy bash script from there to the docs.
The problem is this script patches compiled js results, which is scary for people, and also new versions of Flutter may require adjustments of this script. Ideally, it would be really nice if "flutter build web" just had a compile option for adding this "?v=nnn" in ALL proper places during the build.

[ditman]

For me, it works great. But I'm using auto_route and not bothering about # in urls.

@slavap How are you redirecting people from the root of your domain to your versioned folder deployment? That's the bit that I haven't seen solved!

[slavap]

@ditman not sure I’ve got your question. index.html is placed exactly the same as usual Flutter Web deployment, only the rest of files go to subfolder on the same level as index.html

[ditman]

@ditman not sure I’ve got your question. index.html is placed exactly the same as usual Flutter Web deployment, only the rest of files go to subfolder on the same level as index.html

Ah, so you're updating your index.html to inject assets from /versionA to /versionB when you deploy? Understood! (I thought you were moving the whole build/web under a versioned folder)

[slavap]

@ditman The main point is that there is no need to do "heavy" editing of index.html, it is usually just enough to change "base href" as:

<head>
  <base href="web1234/">

[philitell]

Please support documenting the "subfolder"-approach. This a simple workaround for a major problem that has been around way too long.
You just need to change base href e.g. by using the "--base-href" argument for flutter build and move the index.html file to the parent folder.

1. Create a build

flutter build web --base-href "/my_project_1_1_2/"

2. Copy content of build/web to a folder on your server (folder name contains the version number in one or other way) and move the index.html file to the parent folder. So the final file/folder-structure on your server looks like:

my_project/
   index.html
   my_project_1_1_2/

For Deployment of e.g. version 1.1.3 you deploy your files to subfolder "my_project_1_1_3" and update index.html in the parent directory.

[zs-dima]

@philitell it is a very bad workaround

[philitell]

@zs-dima This workaround achieves the desired behaviour and is very easy to implement. What do you consider a "good" workaround for this issue?