How to Build, Deploy, and Debug Flutter Web Apps: A Complete Step‑by‑Step Guide

Flutter originated from Google Chrome and initially targeted Android and iOS, but its low learning curve and UI similarity to ComposeUI and SwiftUI have made it popular among client developers. However, Flutter Web was not a primary focus until Flutter 2 introduced a stable web version, prompting an analysis of its pros and cons.

Advantages and Disadvantages

Advantages

Zero learning cost for developers already familiar with Flutter; no need to master HTML, CSS, or JavaScript.

Cross‑platform capability: the same codebase can be deployed to web, reducing development effort.

Disadvantages

Compatibility issues when rendering with an HTML‑based approach.

Increased bundle size when using CanvasKit for better performance.

Given these points, pure web applications rarely benefit from Flutter Web, but the framework shines in three internal scenarios:

Internal web tools that complement client‑side workflows.

Simple, time‑critical web features (e.g., event pages) that do not require long‑term maintenance.

Cross‑platform projects where the same Flutter codebase serves both mobile and web.

Creating a Flutter Web Project

Using Android Studio with Flutter 3.10.5, select New Flutter Project and enable only the Web platform. The generated project contains a web folder with index.html, flutter.js, and main.dart.js. flutter create --platforms=web . Run the app with flutter run -d chrome to see it in the browser. The default index.html loads flutter.js, which in turn loads main.dart.js and other assets using relative paths.

Debugging

For desktop debugging, open the browser’s developer tools and use console.log or breakpoints. Mobile debugging can be done by connecting the device, enabling remote debugging in Safari (iOS) or Chrome (Android), and accessing the device’s IP address.

flutter run -d chrome --web-hostname 10.2.136.130 -t lib/main_test.dart --web-port 8080

Packaging and Deployment

Build the web bundle with flutter build web. To use environment‑specific entry points, specify the target file, e.g., flutter build web -t lib/main_dev.dart. If the build fails due to missing icons, add --no-tree-shake-icons.

flutter build web -t lib/main_dev.dart --no-tree-shake-icons

The output resides in build/web and includes index.html, flutter.js, main.dart.js, and the assets folder.

Configuring CDN Paths

Because the app may be served from different CDN hosts for dev, test, and production, replace relative URLs in index.html with absolute CDN URLs at runtime. Use JavaScript to detect the current origin and set the src attribute of flutter.js, manifest.json, favicon.png, and Icon-192.png. Also pass entrypointUrl and assetBase to _flutter.loader.loadEntrypoint for CDN loading.

window.addEventListener('load', function (ev) {
  var cdnHost = '';
  if (document.location.origin == DEV_HOST) cdnHost = DEV_CDN;
  else if (document.location.origin == TEST_HOST) cdnHost = TEST_CDN;
  else if (document.location.origin == PROD_HOST) cdnHost = PROD_CDN;

  document.getElementById('flutter_js').setAttribute('src', `${cdnHost}flutter.js`);
  document.getElementById('manifest').href = `${cdnHost}manifest.json`;
  document.getElementById('icon').href = `${cdnHost}favicon.png`;
  document.getElementById('apple-touch-icon').href = `${cdnHost}icons/Icon-192.png`;

  if (cdnHost == '') {
    _flutter.loader.loadEntrypoint().then(function (engineInitializer) {
      return engineInitializer.initializeEngine();
    }).then(function (appRunner) { appRunner.runApp(); });
  } else {
    _flutter.loader.loadEntrypoint({ entrypointUrl: `${cdnHost}main.dart.js` })
      .then(function (engineInitializer) {
        return engineInitializer.initializeEngine({ assetBase: `${cdnHost}` });
      })
      .then(function (appRunner) { appRunner.runApp(); });
  }
});

Common Pitfalls

Int ↔ Number conversion : Large integer IDs exceed JavaScript’s safe integer range ( 2^53‑1). Convert such fields to String in Dart to avoid data loss.

Platform‑specific imports : dart:html is only available on web. Guard imports with if (dart.library.io) and provide stub implementations for other platforms.

Routing : Flutter Web uses hash‑based routing, which hides query parameters. Store parameters in LocalStorage or rewrite the URL with window.history.replaceState to preserve them on refresh.

iPhone Safari back‑gesture : Add a touchstart listener on the flt‑glass‑pane element to ignore gestures near the screen edges and prevent the app from reloading.

Lottie animations : Some Lottie files use BlendMode.clear, which crashes on mobile browsers. Replace or modify the animations to avoid this blend mode.

CORS : During local development, disable web security in the Flutter Chrome runner by adding --disable-web-security to the Chrome launch arguments.

Conclusion

Flutter Web enables client teams to reuse existing Flutter code for lightweight web projects, offering fast development and easy CDN deployment. While it is not yet suited for large, long‑term web products, it provides a low‑cost way to extend mobile expertise to the web and can be a valuable part of a cross‑platform strategy.