From af2b5c22e996d47d061a3527823973d10914f014 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Mon, 9 Mar 2026 12:40:45 -0700 Subject: [PATCH 1/5] Dusting and cleaning. --- .../platform-integration/web/building.md | 15 ++-- src/content/platform-integration/web/faq.md | 90 +++++++++++-------- src/content/platform-integration/web/index.md | 63 ++++++++----- .../web/initialization.md | 12 +-- src/content/platform-integration/web/setup.md | 4 +- 5 files changed, 106 insertions(+), 78 deletions(-) diff --git a/src/content/platform-integration/web/building.md b/src/content/platform-integration/web/building.md index ee0d196d763..f3f28caaca2 100644 --- a/src/content/platform-integration/web/building.md +++ b/src/content/platform-integration/web/building.md @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/src/content/platform-integration/web/faq.md b/src/content/platform-integration/web/faq.md index b0b25f56414..f9cb035e5aa 100644 --- a/src/content/platform-integration/web/faq.md +++ b/src/content/platform-integration/web/faq.md @@ -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 @@ -25,33 +26,38 @@ 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. +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. -That said, as mentioned in the [roadmap][], the Flutter team plans to -investigate search engine indexability of Flutter web. +However, a recently released Dart package, [Jaspr][] _does_ +support static websites. +In fact, both the [Dart][] and [Flutter][] documentation +websites were recently 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. +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]: {{site.dart-site}} +[Flutter]: {{site.main-url}} +[Jaspr]: https://jaspr.site/ ### 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 following browsers: @@ -61,8 +67,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? @@ -106,18 +113,20 @@ 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. ### 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. @@ -125,9 +134,10 @@ 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 @@ -138,16 +148,17 @@ For example, `logo.png` might become `logo.v123.png`. ``` -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 { @@ -214,3 +225,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 diff --git a/src/content/platform-integration/web/index.md b/src/content/platform-integration/web/index.md index 915f005491d..3d9d2825b68 100644 --- a/src/content/platform-integration/web/index.md +++ b/src/content/platform-integration/web/index.md @@ -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. @@ -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. - + ## 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. -Flutter architecture for web +Flutter architecture for web ## What types of apps can I build? @@ -61,25 +65,36 @@ 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 recently released Dart package, +[Jaspr][], supports static websites; in fact, +the [Dart][] and [Flutter][] websites were migrated to use the Jaspr package. +Note that Jaspr uses Dart, but not Flutter. + +[Dart]: {{site.dart-site}} +[Flutter]: {{site.main-url}} +[Jaspr]: https://jaspr.site/ + ## 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][]. diff --git a/src/content/platform-integration/web/initialization.md b/src/content/platform-integration/web/initialization.md index 4b16b95fcf7..7b2ee829834 100644 --- a/src/content/platform-integration/web/initialization.md +++ b/src/content/platform-integration/web/initialization.md @@ -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 @@ -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 %} @@ -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; diff --git a/src/content/platform-integration/web/setup.md b/src/content/platform-integration/web/setup.md index 7514a590553..f80d5244e7d 100644 --- a/src/content/platform-integration/web/setup.md +++ b/src/content/platform-integration/web/setup.md @@ -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} From 11f88cafb6bde2327bff05c64d81b7c96801328e Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Mon, 9 Mar 2026 12:47:35 -0700 Subject: [PATCH 2/5] adding info about SEO --- src/content/platform-integration/web/faq.md | 3 ++- src/content/platform-integration/web/index.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/platform-integration/web/faq.md b/src/content/platform-integration/web/faq.md index f9cb035e5aa..61c472d38be 100644 --- a/src/content/platform-integration/web/faq.md +++ b/src/content/platform-integration/web/faq.md @@ -41,7 +41,8 @@ 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. + DOM-based website. Also note that Jaspr makes SEO work 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 diff --git a/src/content/platform-integration/web/index.md b/src/content/platform-integration/web/index.md index 3d9d2825b68..ccb63e6c5ca 100644 --- a/src/content/platform-integration/web/index.md +++ b/src/content/platform-integration/web/index.md @@ -69,7 +69,8 @@ However, if you want to use Dart and wish to implement a traditional DOM-based website, a recently released Dart package, [Jaspr][], supports static websites; in fact, the [Dart][] and [Flutter][] websites were migrated to use the Jaspr package. -Note that Jaspr uses Dart, but not Flutter. +Note that Jaspr uses Dart (but not Flutter), and makes SEO work the same +way a traditional website would.. [Dart]: {{site.dart-site}} [Flutter]: {{site.main-url}} From 2e3f920d6a6a7d58f03ca121644b6a06e6b85da0 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Mon, 9 Mar 2026 13:06:32 -0700 Subject: [PATCH 3/5] Tweaking and incorporating feedback --- src/content/platform-integration/web/faq.md | 17 ++++++++-------- src/content/platform-integration/web/index.md | 20 ++++++++++--------- 2 files changed, 20 insertions(+), 17 deletions(-) diff --git a/src/content/platform-integration/web/faq.md b/src/content/platform-integration/web/faq.md index 61c472d38be..a1026bab555 100644 --- a/src/content/platform-integration/web/faq.md +++ b/src/content/platform-integration/web/faq.md @@ -32,25 +32,26 @@ Flutter web prioritizes performance, fidelity, and consistency. This means application output doesn't align with what search engines need to properly index. -However, a recently released Dart package, [Jaspr][] _does_ +However, a community-released Dart package, [Jaspr][] _does_ support static websites. -In fact, both the [Dart][] and [Flutter][] documentation -websites were recently migrated to using the Jaspr package. +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 the - same way a traditional website would. + 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]: {{site.dart-site}} -[Flutter]: {{site.main-url}} -[Jaspr]: https://jaspr.site/ +[Dart documentation]: {{site.dart-site}} +[Flutter documentation]: / +[Jaspr]: {{site.pub-pkg}}/jaspr +[marketing]: {{site.main-url}} ### Does hot reload work with a web app? diff --git a/src/content/platform-integration/web/index.md b/src/content/platform-integration/web/index.md index ccb63e6c5ca..1a52db879da 100644 --- a/src/content/platform-integration/web/index.md +++ b/src/content/platform-integration/web/index.md @@ -28,7 +28,7 @@ check out the following video. ## How it works Adding web support to Flutter involved implementing Flutter's -core drawing layer on top of standard browser APIs; +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. @@ -66,15 +66,17 @@ 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 recently released Dart package, +DOM-based website, a community-released Dart package, [Jaspr][], supports static websites; in fact, -the [Dart][] and [Flutter][] websites were migrated to use the Jaspr package. -Note that Jaspr uses Dart (but not Flutter), and makes SEO work the same -way a traditional website would.. - -[Dart]: {{site.dart-site}} -[Flutter]: {{site.main-url}} -[Jaspr]: https://jaspr.site/ +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]: {{site.pub-pkg}}/jaspr +[marketing]: {{site.main-url}} ## Get started From 193700c3b9df24f6a3860bc3005b86a64432bd93 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Mon, 9 Mar 2026 13:14:41 -0700 Subject: [PATCH 4/5] Putting the Jaspr site back as the URL --- src/content/platform-integration/web/faq.md | 2 +- src/content/platform-integration/web/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/platform-integration/web/faq.md b/src/content/platform-integration/web/faq.md index a1026bab555..37d99ea7b86 100644 --- a/src/content/platform-integration/web/faq.md +++ b/src/content/platform-integration/web/faq.md @@ -50,7 +50,7 @@ we recommend _either_ using: [Dart documentation]: {{site.dart-site}} [Flutter documentation]: / -[Jaspr]: {{site.pub-pkg}}/jaspr +[Jaspr]: https://jaspr.site/ [marketing]: {{site.main-url}} ### Does hot reload work with a web app? diff --git a/src/content/platform-integration/web/index.md b/src/content/platform-integration/web/index.md index 1a52db879da..a88f7b62b44 100644 --- a/src/content/platform-integration/web/index.md +++ b/src/content/platform-integration/web/index.md @@ -75,7 +75,7 @@ way a traditional website would. [Dart documentation]: {{site.dart-site}} [Flutter documentation]: {{site.main-url}} -[Jaspr]: {{site.pub-pkg}}/jaspr +[Jaspr]: https://jaspr.site/ [marketing]: {{site.main-url}} ## Get started From d06580c4118d4735262559f6bf300032b04a8a68 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Fri, 13 Mar 2026 13:54:48 -0700 Subject: [PATCH 5/5] Incorporating feedback --- src/content/platform-integration/web/faq.md | 39 ++++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/src/content/platform-integration/web/faq.md b/src/content/platform-integration/web/faq.md index 37d99ea7b86..9413ff3039d 100644 --- a/src/content/platform-integration/web/faq.md +++ b/src/content/platform-integration/web/faq.md @@ -34,8 +34,8 @@ 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. +In fact, the [Dart documentation][], [Flutter documentation][], and +[Flutter marketing][] websites were migrated to using the Jaspr package. To summarize, for web content that is static or document-like, we recommend _either_ using: @@ -50,8 +50,8 @@ we recommend _either_ using: [Dart documentation]: {{site.dart-site}} [Flutter documentation]: / +[Flutter marketing]: {{site.main-url}} [Jaspr]: https://jaspr.site/ -[marketing]: {{site.main-url}} ### Does hot reload work with a web app? @@ -102,12 +102,12 @@ on [dart.dev]({{site.dart-site}}). ### Does Flutter web support concurrency? -Dart's concurrency support via [isolates][] +Dart's concurrency support that uses [isolates][] is not currently supported in Flutter web. Flutter web apps can potentially work around this by using [web workers][], -although no such support is built in. +although such support isn't built in. ### How do I deploy a web app? @@ -115,25 +115,38 @@ See [Preparing a web app for release][]. ### Does `Platform.is` work on the web? -Not currently. Instead, -consider using the [`os_detect`][] package. +No. While you can technically import `dart:io` when compiling for the web, +calling any `Platform.isXYZ` method throws an `UnsupportedError`. +Furthermore, importing `dart:io` in a package +(except through conditional imports) causes pub.dev +to score the package as not supporting the web. + +* If you are developing a Flutter app, consider using [`kIsWeb`][]. +* If you are developing a package + (especially one without a Flutter dependency), + consider using the [`os_detect`][] package. + +[`kIsWeb`]: {{site.api}}/flutter/foundation/kIsWeb-constant.html ### 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. +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, -check out [Prevent unnecessary network requests with the HTTP Cache][http-cache]. +For more information about caching on the web, check out +[Prevent unnecessary network requests with the HTTP Cache][http-cache]. -It's 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. +This can lead to 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?