Skip to content

Commit 42e665c

Browse files
authored
Merge branch 'main' into blog-whats-new-flutter-3-50
2 parents 24d8b68 + 28e06c0 commit 42e665c

5 files changed

Lines changed: 531 additions & 162 deletions

File tree

‎sites/docs/src/content/deployment/web.md‎

Lines changed: 137 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,19 @@ This builds a _debug_ version of your app.
1212
This page helps you prepare a _release_ version
1313
of your app and covers the following topics:
1414

15-
* [Building the app for release](#building-the-app-for-release)
15+
* [Build the app for release](#building-the-app-for-release)
1616
* [Web content hashing and HTTP caching](#web-content-hashing)
17-
* [Deploying to the web](#deploying-to-the-web)
18-
* [Deploying to Firebase Hosting](#deploying-to-firebase-hosting)
19-
* [Handling images on the web](#handling-images-on-the-web)
20-
* [Opting-in to WebAssembly](#opting-in-to-webassembly)
17+
* [Deploy WebAssembly in production](#deploy-webassembly-in-production)
18+
* [Deploy to the web](#deploying-to-the-web)
19+
* [Deploy to Firebase Hosting](#deploying-to-firebase-hosting)
20+
* [Handle images on the web](#handling-images-on-the-web)
2121
* [Minification](#minification)
2222
* [Mobile browser viewport and SafeArea](#mobile-browser-viewport-and-safearea)
23+
* [Embed a Flutter app into an HTML page][embed-html]
2324

24-
## Building the app for release
25+
[embed-html]: #embedding-a-flutter-app-into-an-html-page
26+
27+
## Build the app for release {:#building-the-app-for-release}
2528

2629
Build the app for deployment using the `flutter build web` command.
2730

@@ -49,12 +52,24 @@ and open the /build/web directory. Navigate to
4952
to view the release version of your app.
5053

5154
## Additional build flags
52-
You might need to deploy a profile or debug build for testing.
53-
To do this, pass the `--profile` or `--debug` flag
54-
to the `flutter build web` command.
55-
Profile builds are specialized for performance profiling using Chrome DevTools,
56-
and debug builds can be used to configure dart2js
57-
to respect assertions and change the optimization level (using the `-O` flag.)
55+
56+
Pass `--release` (default), `--profile`, or `--debug` to `flutter build web`
57+
depending on whether you are deploying to production, profiling in Chrome
58+
DevTools, or testing with assertions:
59+
60+
| Build mode | WebAssembly (`--wasm`) | JavaScript (default) | Purpose |
61+
| :--- | :--- | :--- | :--- |
62+
| `--release` (default) | `-O2` (minified, stripped symbols) | `-O4` (minified) | Production deployment |
63+
| `--profile` | `-O2 --no-strip-wasm` (readable function and type names) | `-O4` (unminified symbols) | Performance and memory profiling |
64+
| `--debug` | `-O0` (assertions enabled) | `-O1` (assertions enabled) | Development testing |
65+
66+
{:.table .table-striped}
67+
68+
To override the default compiler optimization level, pass
69+
`--optimization-level=LEVEL` (`-O0` through `-O4` for `dart2wasm`; `-O1`
70+
through `-O4` for `dart2js`).
71+
For `dart2wasm` optimization details,
72+
refer to [Dart WebAssembly compilation][dart-wasm].
5873

5974
### Source maps
6075

@@ -99,20 +114,12 @@ SHA-256 content hash into compiled entrypoints and all files under
99114
`build/web/assets/**`, and records the hashed paths in `flutter_bootstrap.js`
100115
(`_flutter.buildConfig`):
101116

102-
* **Hashed immutable files (`Cache-Control: public, max-age=31536000, immutable`)**:
103-
* Compiled entrypoints: `main.dart.<hash>.js`, `main.dart.<hash>.wasm`, and
104-
`main.dart.<hash>.mjs` (plus `main.dart.<hash>.js.map` and
105-
`main.dart.<hash>.mjs.map` if `--source-maps` is enabled).
106-
* All files under `assets/**`: including `AssetManifest.<hash>.bin`,
107-
`AssetManifest.bin.<hash>.json`, `FontManifest.<hash>.json`,
108-
`NOTICES.<hash>`, fonts, images, and `shaders/**`.
109-
* **Unhashed bootstrap and root files (`Cache-Control: max-age=0, must-revalidate` or `no-cache`)**:
110-
* `index.html`, `flutter_bootstrap.js`, `flutter.js`, `manifest.json`,
111-
`version.json`, `404.html`, and `icons/**`.
112-
* Bundled `canvaskit/**` files when building with `--no-web-resources-cdn`.
113-
* `main.dart.wasm.map` when building with `--source-maps` (the `.wasm`
114-
binary's `sourceMappingURL` custom section references the unhashed
115-
`.wasm.map` filename).
117+
| Artifact group | Files in `build/web` | Recommended `Cache-Control` |
118+
| :--- | :--- | :--- |
119+
| **Hashed immutable files** | `main.dart.<hash>.js`, `main.dart.<hash>.wasm`, `main.dart.<hash>.mjs` (plus `.js.map` and `.mjs.map`), and all files under `assets/**` (`AssetManifest.<hash>.bin`, `FontManifest.<hash>.json`, `NOTICES.<hash>`, fonts, images, and `shaders/**`) | `public, max-age=31536000, immutable` |
120+
| **Unhashed bootstrap and root files** | `index.html`, `flutter_bootstrap.js`, `flutter.js`, `manifest.json`, `version.json`, `404.html`, `icons/**`, bundled `canvaskit/**` (with `--no-web-resources-cdn`), and `main.dart.wasm.map` (with `--source-maps`) | `no-cache` (or `max-age=0, must-revalidate`) |
121+
122+
{:.table .table-striped}
116123

117124
For a complete `firebase.json` example, refer to the [Web FAQ][web-faq-caching].
118125

@@ -168,22 +175,97 @@ Custom PWA service workers or [Workbox][] pipelines can consume
168175
`precache_manifest.json` directly (passing `revision: entry.urlHashed ? null : entry.hash`
169176
so URL-hashed files aren't double-cached with query parameters).
170177

171-
## Opting-in to WebAssembly
172-
173-
To compile and optimize your app for WebAssembly,
174-
use the `--wasm` flag when running or building.
175-
176-
For more information, see [Support for WebAssembly (Wasm)][Wasm support].
177-
178-
:::important Serving WebAssembly builds
179-
WebAssembly builds use multiple threads for improved rendering performance
180-
and require your web server to return specific COEP/COOP HTTP response headers
181-
(`Cross-Origin-Embedder-Policy: credentialless` and
182-
`Cross-Origin-Opener-Policy: same-origin`).
183-
For full details, see [Support for WebAssembly (Wasm)][Wasm support].
184-
:::
185-
186-
## Deploying to the web
178+
<a id="opting-in-to-webassembly" aria-hidden="true"></a>
179+
180+
## Deploy WebAssembly in production {:#deploy-webassembly-in-production}
181+
182+
Running `flutter build web --wasm` produces a dual-target release bundle
183+
in `build/web`:
184+
185+
* **WebAssembly target (`dart2wasm`)**:
186+
Emits `main.dart.wasm` and its JS runtime module `main.dart.mjs`,
187+
paired with Flutter's WebAssembly rendering engine.
188+
* **JavaScript fallback (`dart2js`)**:
189+
Emits `main.dart.js` for browsers without the required Wasm features.
190+
191+
At startup, `flutter_bootstrap.js` probes the browser's WebAssembly capabilities
192+
and automatically falls back to `main.dart.js` when a browser doesn't support
193+
the required Wasm features or isn't enabled in `wasmAllowList`.
194+
For browser compatibility details,
195+
refer to [Support for WebAssembly (Wasm)][Wasm support].
196+
For `dart2wasm` compiler flags and generic Wasm server configuration,
197+
refer to [Dart WebAssembly compilation][dart-wasm] and
198+
[Serve WebAssembly in production][dart-wasm-serving].
199+
200+
### Configure server headers and compression {:#server-headers-and-compression}
201+
202+
Configure the production web server or CDN with the following headers and
203+
compression settings:
204+
205+
* **Cross-origin isolation for multi-threaded rendering**:
206+
Return `Cross-Origin-Opener-Policy: same-origin` and
207+
`Cross-Origin-Embedder-Policy: credentialless` (or `require-corp`) on the
208+
document response to enable `SharedArrayBuffer` and multi-threaded
209+
WebAssembly rendering (refer to the [COOP and COEP guide on web.dev][coep]).
210+
* **Wasm MIME type and static pre-compression**:
211+
Serve all `.wasm` files (both `main.dart.wasm` and self-hosted engine
212+
binaries) with `Content-Type: application/wasm`, and pre-compress `.wasm`,
213+
`.mjs`, `.js`, fonts, and `assets/**` manifests with Brotli (`br`) and Gzip
214+
(`gzip`).
215+
For streaming compilation and compression details, refer to
216+
[Serve WebAssembly in production][dart-wasm-serving].
217+
218+
### Reduce cold-start latency {:#reduce-cold-start-latency}
219+
220+
To shorten time-to-first-frame on cold cache loads:
221+
222+
* **Inline the bootstrap script**:
223+
Replace the external `<script src="flutter_bootstrap.js" async></script>` tag
224+
in `web/index.html` with an inline `<script>` containing
225+
`{% raw %}{{flutter_bootstrap_js}}{% endraw %}`.
226+
Inlining eliminates an extra network round-trip before the browser begins
227+
downloading `main.dart.wasm` and the rendering engine.
228+
For template syntax details,
229+
refer to [Bootstrap the app][web-init-bootstrapping].
230+
* **Trim initial bundle weight**:
231+
Release builds enable font icon tree shaking automatically
232+
(pass `--no-tree-shake-icons` only when debugging dynamic icon code points).
233+
To split large features into on-demand `.wasm` chunks,
234+
build with the `--enable-wasm-deferred-loading` flag.
235+
Keep in mind that `--enable-wasm-deferred-loading` is incompatible with
236+
`--web-content-hash`.
237+
* **Render an HTML loading shell**:
238+
Include lightweight HTML and CSS inside `web/index.html`
239+
(or update DOM state from the `onEntrypointLoaded` callback in
240+
`flutter_bootstrap.js`) so your app's users receive visual feedback while the
241+
engine initializes.
242+
243+
### Serve assets from a CDN or self-hosted origin {:#multi-asset-and-cdn-loading}
244+
245+
Customize where engine binaries, compiled modules, and assets load from to
246+
match the hosting architecture and privacy requirements:
247+
248+
* **Self-host engine binaries and fallback fonts**:
249+
Pass `--no-web-resources-cdn` to bundle Flutter's rendering engine files
250+
directly into `build/web/canvaskit/` instead of fetching them from
251+
`gstatic.com` at runtime.
252+
When you build with the `--web-content-hash` flag, bundled files under
253+
`canvaskit/**` remain unhashed and require revalidating cache headers.
254+
* **Serve static assets from a dedicated CDN**:
255+
Configure the `assetBase` and `entrypointBaseUrl` options in
256+
`_flutter.loader.load({ config: ... })` (and `canvasKitBaseUrl` when
257+
self-hosting engine binaries on a CDN).
258+
To inject a CDN prefix into `web/index.html` at build time, reference the
259+
`$FLUTTER_STATIC_ASSETS_URL` placeholder in `web/index.html` and pass
260+
`--static-assets-url=https://cdn.example.com/` (including the trailing `/`)
261+
to `flutter build web`.
262+
When you build with the `--enable-wasm-deferred-loading` flag and custom asset
263+
routing, provide a `wasmDeferredModulesLoader` callback to fetch deferred
264+
`.wasm` modules from the CDN.
265+
For configuration details,
266+
refer to [Customize the Flutter loader][web-init-loader].
267+
268+
## Deploy to the web {:#deploying-to-the-web}
187269

188270
When you are ready to deploy your app,
189271
upload the release bundle
@@ -195,7 +277,7 @@ many others:
195277
* [GitHub Pages][]
196278
* [Google Cloud Hosting][]
197279

198-
## Deploying to Firebase Hosting
280+
## Deploy to Firebase Hosting {:#deploying-to-firebase-hosting}
199281

200282
You can use the Firebase CLI to build and release your Flutter app with Firebase
201283
Hosting.
@@ -246,13 +328,13 @@ command:
246328
To learn more, visit the official [Firebase Hosting][] documentation for
247329
Flutter on the web.
248330

249-
## Handling images on the web
331+
## Handle images on the web {:#handling-images-on-the-web}
250332

251333
The web supports the standard `Image` widget to display images.
252334
By design, web browsers run untrusted code without harming the host computer.
253335
This limits what you can do with images compared to mobile and desktop platforms.
254336

255-
For more information, see [Displaying images on the web][].
337+
To learn more, refer to [Displaying images on the web][].
256338

257339
## Minification
258340

@@ -267,6 +349,8 @@ shorter strings (e.g. by renaming `AlignmentGeometryTween` to something like
267349
| profile | No | Yes |
268350
| release | Yes | Yes |
269351

352+
{:.table .table-striped}
353+
270354
## Mobile browser viewport and SafeArea {:#mobile-browser-viewport-and-safearea}
271355

272356
:::version-note
@@ -303,12 +387,16 @@ In Flutter 3.50 and later, route strings passed to
303387
(such as `%2F`, `%26`, `%23`, and `%20`) when written to the browser's URL bar
304388
and history, rather than decoding them using `Uri.decodeComponent`.
305389

306-
## Embedding a Flutter app into an HTML page
390+
## Embed a Flutter app into an HTML page {:#embedding-a-flutter-app-into-an-html-page}
307391

308-
See [Embedding Flutter web][].
392+
To embed Flutter into an existing web page,
393+
refer to [Add Flutter to any web application][Embedding Flutter web].
309394

310395
[Embedding Flutter web]: /platform-integration/web/embedding-flutter-web
311396

397+
[coep]: https://web.dev/articles/coop-coep
398+
[dart-wasm]: {{site.dart-site}}/web/wasm
399+
[dart-wasm-serving]: {{site.dart-site}}/web/deployment#serving-wasm-in-production
312400
[dhttpd]: {{site.pub}}/packages/dhttpd
313401
[Displaying images on the web]: /platform-integration/web/web-images
314402
[Firebase Hosting]: {{site.firebase}}/docs/hosting/frameworks/flutter
@@ -322,4 +410,6 @@ See [Embedding Flutter web][].
322410
[viewport-fit-breaking]: /release/breaking-changes/viewport-fit-cover-safe-area
323411
[Wasm support]: /platform-integration/web/wasm
324412
[web-faq-caching]: /platform-integration/web/faq#how-do-i-configure-my-cache-headers
413+
[web-init-bootstrapping]: /platform-integration/web/initialization#bootstrapping
414+
[web-init-loader]: /platform-integration/web/initialization#customize-the-flutter-loader
325415
[Workbox]: https://github.com/GoogleChrome/workbox

0 commit comments

Comments
 (0)