Web breaking change: deprecating and removing the HTML renderer
yjb...@google.com
In March 2024, we expressed our intent to deprecate and remove the HTML renderer from Flutter web in favor of the more modern CanvasKit and SkWasm renderers. Since then we received valuable feedback from the community, and identified issues we need to fix before CanvasKit is able to replace HTML for the vast majority of use-cases.
We already fixed more than half of those issues, and are on track to fix the rest by the end of 2024. It is now time to plan for the removal of the HTML renderer from the codebase. This means that options --web-renderer=html and --web-renderer=auto will stop working in new releases of the Flutter SDK.
We estimate that this change will happen in the first Flutter stable release of 2025. However, the master and beta channels will be affected earlier. Until then, the HTML renderer is still available to be used, although it is considered deprecated.
To prepare your app for this change, upgrade to Flutter 3.24 or later, and remove the --web-renderer option from your flutter build web command. This will pick CanvasKit by default. If the app, and all plugins and packages it uses, are compatible with WebAssembly, you could also try the --wasm option. More information about web renderers can be found here.
In most cases an app compiled to CanvasKit will just work. However, you should be aware of a few things as you transition to CanvasKit:
As of Flutter 3.24 Image.network does not support CORS images. A common workaround is to use an HtmlElementView and load the image into an <img> element. We plan to fix this before we completely remove the HTML renderer.
CanvasKit comes with a 1.5MB extra wasm file, and SkWasm comes with a 1.1MB extra wasm file. We will keep working on reducing this size. However, for now this is a trade-off we decided we should take.
HtmlElementView is essentially free in HTML because it simply adds more elements under Flutter's HTML tree. In CanvasKit there are situations where Flutter needs to create extra <canvas> elements to composite HTML content amongst Flutter content. If the app uses too many platform views at the same time, the extra canvases can get expensive and degrade performance. Common strategies for reducing the canvas count are:
Reduce your app's reliance on HTML content.
Group multiple HtmlElementViews into one.
Reduce overlap between HTML and Flutter widgets. When there's no overlap, Flutter can optimize by grouping pictures and platform views to minimize the number of extra canvases.
If your app renders mostly HTML content, consider embedding Flutter into HTML rather than embedding HTML into Flutter.
Watch out for code that relies on bugs in the HTML renderer. Sometimes a bug can accidentally become a feature.
More details on the differences between CanvasKit and HTML renderers can be found at https://flutter.dev/go/deprecate-html-renderer.
The HTML DOM produced by Flutter's HTML renderer has never been idiomatic. But perhaps that was enough for your app. If your app absolutely needs to produce HTML, consider other Dart web frameworks that are designed to output idiomatic HTML DOM.
Lastly, you can continue using older versions of the Flutter SDK, while you are evaluating longer term options.