Build and release a web app

During a typical development cycle, you test an app using flutter run -d chrome (for example) at the command line. This builds a debug version of your app.

This page helps you prepare a release version of your app and covers the following topics:

• Build the app for release
• Web content hashing and HTTP caching
• Deploy WebAssembly in production
• Deploy to the web
• Deploy to Firebase Hosting
• Handle images on the web
• Minification
• Mobile browser viewport and SafeArea
• Embed a Flutter app into an HTML page

Build the app for deployment using the flutter build web command.

flutter build web

To build your application with WebAssembly (Wasm), pass the --wasm flag:

flutter build web --wasm

This generates the app, including the assets, and places the files into the /build/web directory of the project.

To validate the release build of your app, launch a web server (for example, python -m http.server 8000, or by using the dhttpd package), and open the /build/web directory. Navigate to localhost:8000 in your browser (given the python SimpleHTTPServer example) to view the release version of your app.

Pass --release (default), --profile, or --debug to flutter build web depending on whether you are deploying to production, profiling in Chrome DevTools, or testing with assertions:

To override the default compiler optimization level, pass --optimization-level=LEVEL (-O0 through -O4 for dart2wasm; -O1 through -O4 for dart2js). For dart2wasm optimization details, refer to Dart WebAssembly compilation.

To generate source maps for symbolication in crash reporting services, pass the --source-maps flag:

flutter build web --source-maps

Generating source maps creates separate .js.map or .wasm.map files (or both, depending on your build target) in the build/web directory without adding binary overhead to the compiled output.

To enable automatic content-based cache busting across deployments, pass --web-content-hash to flutter build web:

flutter build web --wasm --web-content-hash

When --web-content-hash is enabled, Flutter embeds an 8-character truncated SHA-256 content hash into compiled entrypoints and all files under build/web/assets/**, and records the hashed paths in flutter_bootstrap.js (_flutter.buildConfig):

For a complete firebase.json example, refer to the Web FAQ.

When you deploy a new release (N), users with an already-open browser tab running the previous release (N-1) might lazily fetch an asset, font, or image whose filename carries release N-1's content hash.

To avoid mid-session 404 errors during rollouts, use an overlay deployment strategy:

• Retain at least the previous release's (N-1) hashed main.dart.* and assets/** files in your CDN or storage bucket alongside release N's hashed files (or prune old hashes after a 24–72 hour grace window).
• Update index.html and flutter_bootstrap.js atomically last.
• Exclude /assets/**, /canvaskit/**, /icons/**, and /main.dart.* from single-page application (SPA) /index.html catch-all rewrites so missing assets return a genuine 404 instead of 200 text/html.

When --web-content-hash is enabled, flutter build web writes a bill of materials to build/web/precache_manifest.json:

{
  "version": 1,
  "entries": [
    {
      "url": "flutter_bootstrap.js",
      "hash": "a1b2c3d4",
      "size": 10432,
      "urlHashed": false
    },
    {
      "url": "main.dart.f215ce97.wasm",
      "hash": "f215ce97",
      "size": 1842104,
      "urlHashed": true
    }
  ]
}

Custom PWA service workers or Workbox pipelines can consume precache_manifest.json directly (passing revision: entry.urlHashed ? null : entry.hash so URL-hashed files aren't double-cached with query parameters).

Running flutter build web --wasm produces a dual-target release bundle in build/web:

• WebAssembly target (dart2wasm): Emits main.dart.wasm and its JS runtime module main.dart.mjs, paired with Flutter's WebAssembly rendering engine.
• JavaScript fallback (dart2js): Emits main.dart.js for browsers without the required Wasm features.

At startup, flutter_bootstrap.js probes the browser's WebAssembly capabilities and automatically falls back to main.dart.js when a browser doesn't support the required Wasm features or isn't enabled in wasmAllowList. For browser compatibility details, refer to Support for WebAssembly (Wasm). For dart2wasm compiler flags and generic Wasm server configuration, refer to Dart WebAssembly compilation and Serve WebAssembly in production.

Configure the production web server or CDN with the following headers and compression settings:

• Cross-origin isolation for multi-threaded rendering: Return Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: credentialless (or require-corp) on the document response to enable SharedArrayBuffer and multi-threaded WebAssembly rendering (refer to the COOP and COEP guide on web.dev).
• Wasm MIME type and static pre-compression: Serve all .wasm files (both main.dart.wasm and self-hosted engine binaries) with Content-Type: application/wasm, and pre-compress .wasm, .mjs, .js, fonts, and assets/** manifests with Brotli (br) and Gzip (gzip). For streaming compilation and compression details, refer to Serve WebAssembly in production.

To shorten time-to-first-frame on cold cache loads:

• Inline the bootstrap script: Replace the external <script src="flutter_bootstrap.js" async></script> tag in web/index.html with an inline <script> containing {{flutter_bootstrap_js}}. Inlining eliminates an extra network round-trip before the browser begins downloading main.dart.wasm and the rendering engine. For template syntax details, refer to Bootstrap the app.
• Trim initial bundle weight: Release builds enable font icon tree shaking automatically (pass --no-tree-shake-icons only when debugging dynamic icon code points). To split large features into on-demand .wasm chunks, build with the --enable-wasm-deferred-loading flag. Keep in mind that --enable-wasm-deferred-loading is incompatible with --web-content-hash.
• Render an HTML loading shell: Include lightweight HTML and CSS inside web/index.html (or update DOM state from the onEntrypointLoaded callback in flutter_bootstrap.js) so your app's users receive visual feedback while the engine initializes.

Customize where engine binaries, compiled modules, and assets load from to match the hosting architecture and privacy requirements:

• Self-host engine binaries and fallback fonts: Pass --no-web-resources-cdn to bundle Flutter's rendering engine files directly into build/web/canvaskit/ instead of fetching them from gstatic.com at runtime. When you build with the --web-content-hash flag, bundled files under canvaskit/** remain unhashed and require revalidating cache headers.
• Serve static assets from a dedicated CDN: Configure the assetBase and entrypointBaseUrl options in _flutter.loader.load({ config: ... }) (and canvasKitBaseUrl when self-hosting engine binaries on a CDN). To inject a CDN prefix into web/index.html at build time, reference the $FLUTTER_STATIC_ASSETS_URL placeholder in web/index.html and pass --static-assets-url=https://cdn.example.com/ (including the trailing /) to flutter build web. When you build with the --enable-wasm-deferred-loading flag and custom asset routing, provide a wasmDeferredModulesLoader callback to fetch deferred .wasm modules from the CDN. For configuration details, refer to Customize the Flutter loader.

When you are ready to deploy your app, upload the release bundle to Firebase, the cloud, or a similar service. Here are a few possibilities, but there are many others:

• Firebase Hosting
• GitHub Pages
• Google Cloud Hosting

You can use the Firebase CLI to build and release your Flutter app with Firebase Hosting.

To get started, install or update the Firebase CLI:

npm install -g firebase-tools

1. Enable the web frameworks preview to the Firebase framework-aware CLI:

   firebase experiments:enable webframeworks
   

   content_copy

2. In an empty directory or an existing Flutter project, run the initialization command:

   firebase init hosting
   

   content_copy

3. Answer yes when asked if you want to use a web framework.

4. If you're in an empty directory, you'll be asked to choose your web framework. Choose Flutter Web.

5. Choose your hosting source directory; this could be an existing flutter app.

6. Select a region to host your files.

7. Choose whether to set up automatic builds and deploys with GitHub.

8. Deploy the app to Firebase Hosting:

   firebase deploy
   

   content_copy

   Running this command automatically runs flutter build web --release, so you don't have to build your app in a separate step.

To learn more, visit the official Firebase Hosting documentation for Flutter on the web.

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

To learn more, refer to Displaying images on the web.

To improve app start-up the compiler reduces the size of the compiled code by removing unused code (known as tree shaking), and by renaming code symbols to shorter strings (e.g. by renaming AlignmentGeometryTween to something like ab). Which of these two optimizations are applied depends on the build mode:

On mobile browsers (such as iOS Safari and Android Chrome) with display cutouts, notches, or home indicators, Flutter web defaults to rendering within the browser's safe area (viewport-fit=contain).

To render edge-to-edge across the entire screen and populate Flutter's SafeArea and MediaQuery.paddingOf with the browser's CSS env(safe-area-inset-*) insets, add a <meta name="viewport"> tag with viewport-fit=cover inside the <head> of your web/index.html file (included as a commented-out option in newly created web/index.html templates):

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">

In Flutter 3.50 and later, route strings passed to SystemNavigator.routeInformationUpdated preserve percent-encoded sequences (such as %2F, %26, %23, and %20) when written to the browser's URL bar and history, rather than decoding them using Uri.decodeComponent.

To embed Flutter into an existing web page, refer to Add Flutter to any web application.