FFFF Dusting and cleaning of the web pages by sfshaza2 · Pull Request #13160 · flutter/website · GitHub
[go: up one dir, main page]
Skip to content

Dusting and cleaning of the web pages #13160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sfshaza2 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Dusting and cleaning of the web pages #13160

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
af2b5c2
Dusting and cleaning.
sfshaza2 Mar 9, 2026
11f88ca
adding info about SEO
sfshaza2 Mar 9, 2026
2e3f920
Tweaking and incorporating feedback
sfshaza2 Mar 9, 2026
193700c
Putting the Jaspr site back as the URL
sfshaza2 Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions src/content/platform-integration/web/building.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ application using Flutter.

Before you can build a web application with Flutter,
make sure that you have the [Flutter SDK][] and a web browser installed.
See the [Set up web development for Flutter][Setup-web] instructions
Visit [Set up web development for Flutter][Setup-web] instructions
for details.

## Set up a Flutter project
Expand Down Expand Up @@ -42,7 +42,7 @@ and run your Flutter app.

## Run your app

See the following sections to run your app.
Check out the following sections to run your app.

### Run your app from the command line

Expand Down Expand Up @@ -82,7 +82,7 @@ $ flutter run -d chrome --wasm
```

Flutter web offers multiple build modes and renderers.
For more information, see [Web renderers][].
For more information, check out [Web renderers][].

### Disable hot reload in VS Code

Expand Down Expand Up @@ -143,6 +143,7 @@ $ flutter build web
```

### Build your app using WebAssembly

You can also pass the `--wasm` flag to build your app using WebAssembly:

```console
Expand All @@ -153,9 +154,9 @@ This populates a `build/web` directory
with built files, including an `assets` directory,
which need to be served together.

To learn more about how to deploy these assets to the web, see
[Build and release a web app][].
For answers to other common questions, see the [Web FAQ][].
To learn more about how to deploy these assets to the web,
visit [Build and release a web app][].
For answers to other common questions, visit the [Web FAQ][].

## Debugging

Expand All @@ -174,7 +175,7 @@ Use [Chrome DevTools][] for the following tasks:
## Testing

Use [widget tests][Widget tests] or integration tests. To learn more about
running integration tests in a browser, see the [Integration testing][] page.
running integration tests in a browser, check out the [Integration testing][] page.

[Analyzing performance]: {{site.developers}}/web/tools/chrome-devtools/evaluate-performance
[Build and release a web app]: /deployment/web
Expand Down
94 changes: 54 additions & 40 deletions src/content/platform-integration/web/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
---
title: Web FAQ
description: Some gotchas and differences when writing or running web apps in Flutter.
description: >-
Some gotchas and differences when writing or running web apps in Flutter.
---

## Questions

### What scenarios are ideal for Flutter on the web?

Not every web page makes sense in Flutter, but we think Flutter is particularly
suited for app-centric experiences:
Not every web page makes sense in Flutter,
but we think Flutter is particularly suited for app-centric experiences:

* Progressive Web Apps
* Single Page Apps
Expand All @@ -25,33 +26,40 @@ see [Web support for Flutter][].

### Search Engine Optimization (SEO)

In general, Flutter is geared towards dynamic application experiences. Flutter's
web support is no exception. Flutter web prioritizes performance, fidelity, and
consistency. This means application output does not align with what search
engines need to properly index. For web content that is static or document-like,
we recommend using HTML—just like we do on [flutter.dev]({{site.main-url}}),
[dart.dev]({{site.dart-site}}), and [pub.dev]({{site.pub}}). You should also
consider separating your primary application experience—created in Flutter—from
your landing page, marketing content, and help content—created using
search-engine optimized HTML.

That said, as mentioned in the [roadmap][], the Flutter team plans to
investigate search engine indexability of Flutter web.
In general, Flutter is geared towards dynamic application experiences.
Flutter's web support is no exception.
Flutter web prioritizes performance, fidelity, and consistency.
This means application output doesn't align with what search
engines need to properly index.

However, a community-released Dart package, [Jaspr][] _does_
support static websites.
In fact, the [Dart documentation][] and [Flutter documentation][] and
[marketing][] websites were migrated to using the Jaspr package.

To summarize, for web content that is static or document-like,
we recommend _either_ using:

1. [Jaspr][], if you want to use Dart but want a more traditional
DOM-based website. Also note that Jaspr makes SEO work in the
same way a traditional website would.
1. HTML—in this case, consider separating your primary application
experience (created in Flutter), from your landing page,
marketing content, and help content (created using
search engine optimized HTML).

[Dart documentation]: {{site.dart-site}}
[Flutter documentation]: /
[Jaspr]: https://jaspr.site/
[marketing]: {{site.main-url}}

### Does hot reload work with a web app?

Yes! For more information, check out
[hot reload on the web][].
Yes! For more information,
check out [hot reload on the web][].

[hot reload on the web]: /platform-integration/web/building#hot-reload-web

Hot restart is a fast way of seeing your
changes without having to relaunch your web app and wait for it
to compile and load. This works similarly to
the hot reload feature for Flutter mobile development.
The difference is that hot reload remembers your state and hot
restart doesn't.

### Which web browsers are supported by Flutter?

Flutter web apps can run on the 8000 following browsers:
Expand All @@ -61,8 +69,9 @@ Flutter web apps can run on the following browsers:
* Edge (mobile & desktop)
* Firefox (mobile & desktop)

During development, Chrome (on macOS, Windows, and Linux) and Edge (on Windows)
are supported as the default browsers for debugging your app.
During development, Chrome (on macOS, Windows, and Linux),
and Edge (on Windows) are supported as the default browsers
for debugging your app.

### Can I build, run, and deploy web apps in any of the IDEs?

Expand Down Expand Up @@ -106,28 +115,31 @@ See [Preparing a web app for release][].

### Does `Platform.is` work on the web?

Not currently.
Not currently. Instead,
consider using the [`os_detect`][] package.
Copy link
Contributor
@abdallahshaban557 abdallahshaban557 Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think support exists for kIsWeb - if this is for platform detection would should perhaps update this question here.

Copy link
Contributor Author
@sfshaza2 sfshaza2 Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting, @jonasfj asked for this fix. I'll see what he says when we reviews.

Copy link
Member
@jonasfj jonasfj Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kIsWeb looks fine to use.

But this question is written because historically lots of code has been using Platform.isAndroid and Platform.isIOS, while these are decidedly not deprecated (one can dream I suppose).

Using Platform.isAndroid will not work when targeting web with.

It's sadly technically allowed to import 'dart:io' when compiling for web. This is and should be strongly discouraged. And if you import 'dart:io' calling any method from it will throw an UnsupportedError. It is possible to work around this with IOOverrides. This is not encouraged.

On pub.dev, we will score packages as not supporting web if they import dart:io (they may import it with conditional imports).

If you're coding a flutter app using kIsWeb, is fine. Maybe, even desirable, as it's right there.

If you are coding a package for use by others, you should probably prefer os_detect (unless you have a flutter dependency, then it probably doesn't matter).

I think it's important to mention os_detect, because:

  • Packages that don't have a flutter dependency should not add one to detect platform, instead they should use os_detect.
  • Packages with a flutter dependency may prefer os_detect, and it may be an easier migration path for packages that has been using Platform.isAndroid and friends.

I suspect the FAQ is here because dart:io can be imported when targeting web, it just becomes a runtime error to call Platform.isAndroid and friends. This is a bit of trap.

Sorry, for all the rambling. This is complex to put it mildly -- generally, I think we should tell users to avoid Platform.isXYZ, and instead prefer package:os_detect (or package:platform when the next PR lands).

Copy link
Contributor
@abdallahshaban557 abdallahshaban557 Mar 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it - appreciate the explanation here, @jonasfj! Since this is in the main FAQ for the web part of our docs, I think we should mention both then. kIsWeb for an app, and os_detect for a package. Does you agree?


### Why doesn't my app update immediately after it's deployed?

You might need to configure the `Cache-Control` header returned by your web server.
For example, if this header is set to 3600, then the browser
and CDN will cache the asset for 1 hour, and your users might see an out-of-date
version of your app up to 1 hour after you deploy a new version. For
more information about caching on the web,
For example, if this header is set to 3600,
then the browser and CDN will cache the asset for 1 hour,
and your users might see an out-of-date
version of your app up to 1 hour after you deploy a new version.
For more information about caching on the web,
check out [Prevent unnecessary network requests with the HTTP Cache][http-cache].

It is a good idea to be aware of this behavior to avoid an undesirable user experience.
It's a good idea to be aware of this behavior to avoid an undesirable user experience.
After you deploy your app, users might use a
cached version of your app (cached by the browser or CDN)
for the duration defined by your cache headers.
This can lead to users using a version of your app that
is incompatible with changes that have been deployed to backend services.

### How do I clear the web cache after a deployment and force an app download?
If you wish to defeat these cache headers after each deployment, a common
technique is to append a build ID of some sort to the links of your static
resources, or update the filenames themselves.

If you wish to defeat these cache headers after each deployment,
a common technique is to append a build ID of some sort to the links
of your static resources, or update the filenames themselves.
For example, `logo.png` might become `logo.v123.png`.

```html
Expand All @@ -138,16 +150,17 @@ For example, `logo.png` might become `logo.v123.png`.
<script src="flutter_bootstrap.v123.js" async></script>
```

Flutter does not currently support appending build IDs to resources
Flutter doesn't currently support appending build IDs to resources
automatically.

### How do I configure my cache headers?

If you are using Firebase Hosting,
the shared cache (CDN) is invalidated when you deploy a new version of your
app. But you might choose to configure your cache headers as follows,
so that the browser cache doesn't cache application scripts,
but the shared cache does.
the shared cache (CDN) is invalidated when you deploy a
new version of your app.
However, to make sure that the browser doesn't
cache application scripts but the shared cache does,
you can configure your cache headers as follows,

```json
{
Expand Down Expand Up @@ -214,3 +227,4 @@ the `Cache-Control` header to a small value such as 0 or 60 seconds.
[Web support for Flutter]: /platform-integration/web
[web workers]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
[workbox]: https://github.com/GoogleChrome/workbox
[`os_detect`]: {{site.pub}}/packages/os_detect
66 changes: 42 additions & 24 deletions src/content/platform-integration/web/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
---
title: Web support for Flutter
shortTitle: Web
description: Details of how Flutter supports the creation of web experiences.
description: >-
Details of how Flutter supports the creation of web experiences.
---

Flutter delivers the same experiences on the web as on mobile.

Building on the portability of Dart, the power of the web platform, the
flexibility of the Flutter framework, and the performance of WebAssembly,
Building on the portability of Dart, the power of the web platform,
the flexibility of the Flutter framework, and the performance of WebAssembly,
you can build apps for iOS, Android, and the browser from the same codebase.
The web is just another device target for your app.

Expand All @@ -21,23 +22,26 @@ a binary instruction format that enables fast apps on all major browsers.
For a glimpse into the benefits of using WebAssembly,
check out the following video.

<YouTubeEmbed id="lpnKWK-KEYs?start=1712" title="What's new in Flutter - WebAssembly"></YouTubeEmbed>
<YouTubeEmbed id="lpnKWK-KEYs?start=1712"
title="What's new in Flutter - WebAssembly"></YouTubeEmbed>

## How it works

Adding web support to Flutter involved implementing Flutter's
core drawing layer on top of standard browser APIs, in addition
to compiling Dart to JavaScript, instead of the ARM machine code that
is used for mobile applications. Using a combination of DOM, Canvas,
and WebAssembly, Flutter can provide a portable, high-quality,
core drawing layer on top of standard browser APIs,
in addition to compiling Dart to JavaScript,
instead of the ARM machine code that
is used for mobile applications.
Using a combination of DOM, Canvas, and WebAssembly,
Flutter can provide a portable, high-quality,
and performant user experience across modern browsers.
We implemented the core drawing layer completely in Dart
and used Dart's optimized JavaScript compiler to compile the
Flutter core and framework along with your application
into a single, minified source file that can be deployed to
any web server.
Flutter core and framework along with your application into a single,
minified source file that can be deployed to any web server.

<img src="/assets/images/docs/arch-overview/web-framework-diagram.png" alt="Flutter architecture for web" >
<img src="/assets/images/docs/arch-overview/web-framework-diagram.png"
alt="Flutter architecture for web" >

## What types of apps can I build?

Expand All @@ -61,25 +65,39 @@ rather than the app-centric services that a UI framework like Flutter
can deliver. However, you _can_ use Flutter to embed interactive
experiences into these websites.

However, if you want to use Dart and wish to implement a traditional
DOM-based website, a community-released Dart package,
[Jaspr][], supports static websites; in fact,
the [Dart documentation][] and [Flutter documentation][]
and [marketing][] websites were migrated to use the Jaspr package.
Note that Jaspr uses Dart (but not Flutter), and makes SEO work in the same
way a traditional website would.

[Dart documentation]: {{site.dart-site}}
[Flutter documentation]: {{site.main-url}}
[Jaspr]: https://jaspr.site/
[marketing]: {{site.main-url}}

## Get started

The following resources can help you get started:

* To add web support to an existing app, or to create a
new app that includes web support, see
[Building a web application with Flutter][].
* To configure web development server settings in a centralized file, see [Set up a web development configuration file][].
* To learn about Flutter's different web renderers (CanvasKit and Skwasm), see
[Web renderers][].
new app that includes web support,
visit [Building a web application with Flutter][].
* To configure web development server settings in a centralized file,
check out [Set up a web development configuration file][].
* To learn about Flutter's different web renderers (CanvasKit and Skwasm),
check out [Web renderers][].
* To learn how to create a responsive Flutter
app, see [Creating responsive apps][].
* To view commonly asked questions and answers, see the
[web FAQ][].
* To see code examples,
app, check out [Creating responsive apps][].
* To view commonly asked questions and answers,
visit the [web FAQ][].
* For code examples,
check out the [web samples for Flutter][].
* To see a Flutter web app demo, check out the [Wonderous app][].
* To learn about deploying a web app, see
[Preparing an app for web release][].
* For a Flutter web app demo, check out the [Wonderous app][].
* To learn about deploying a web app,
visit [Preparing an app for web release][].
* [File an issue][] on the main Flutter repo.
* You can chat and ask web-related questions on the
**#help** channel on [Discord][].
Expand Down
12 changes: 6 additions & 6 deletions src/content/platform-integration/web/initialization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,11 +137,11 @@ The `config` argument is an object that can have the following optional fields:
A boolean flag to force the Skia WebAssembly (skwasm) renderer
to run in **single-threaded mode**. This is useful if:

- Your environment does not support multi-threaded WASM (for example,
* Your environment doesn't support multi-threaded WASM. For example,
`SharedArrayBuffer` is not available or required security
headers are missing).
- You want maximum browser compatibility.
- Use `false` (default) to allow multi-threaded rendering when
headers are missing.
* You want maximum browser compatibility.
* Use `false` (default) to allow multi-threaded rendering when
supported, which improves performance.

## Example usage
Expand All @@ -159,7 +159,7 @@ _flutter.loader.load({

The following example shows a custom `flutter_bootstrap.js` that allows
the user to select a renderer by providing a `renderer` query parameter,
e.g. `?renderer=skwasm`, in the URL of their website:
such as `?renderer=skwasm`, in the URL of their website:

```js
{% raw %}{{flutter_js}}{% endraw %}
Expand Down Expand Up @@ -244,7 +244,7 @@ Warning: In index.html:37: Local variable for "serviceWorkerVersion" is deprecat
Use "{{flutter_service_worker_version}}" template token instead.
```

You can fix this by deleting the following line in the `web/index.html` file:
You can fix this by deleting the following line from the `web/index.html` file:

```html title="web/index.html"
var serviceWorkerVersion = null;
Expand Down
4 changes: 2 additions & 2 deletions src/content/platform-integration/web/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ to run, build, and deploy Flutter apps for the web platform.

:::note
If you haven't set up Flutter already,
visit and follow [Install Flutter][] first.
[install Flutter][] first.

If you've already installed Flutter,
ensure that it's [up to date][].
:::

[Install Flutter]: /install
[install Flutter]: /install
[up to date]: /install/upgrade

## Install a web browser {: #install}
Expand Down
Loading
0