How to use Skia / CanvasKit in Flutter Web?

As described in Web renderers documentation these are the valid commands to build/run web in canvaskit mode:

flutter build web --web-renderer canvaskit
flutter run -d chrome --web-renderer canvaskit

The --web-renderer command line option takes one of three values, auto, html, or canvaskit.

  • auto (default) - automatically chooses which renderer to use. This option chooses the HTML renderer when the app is running in a mobile browser, and CanvasKit renderer when the app is running in a desktop browser.
  • html - always use the HTML renderer.
  • canvaskit - always use the CanvasKit renderer.

You can enable CanvasKit / Skia in Flutter Web by supplying a Dart environment constant:

flutter run -d chrome --dart-define=FLUTTER_WEB_USE_SKIA=true

The flutter tools now have a good shortcut for it:

flutter run -d chrome --web-renderer canvaskit

The --dart-define=FLUTTER_WEB_USE_SKIA=true parameter will set the constant to use Skia. You will also need to supply it to flutter build web:

flutter build web --web-renderer canvaskit

Learn more about web renderers in Flutter.

Options

There are three options for --web-renderer:

  • auto (default) - automatically chooses which renderer to use. This option chooses the HTML renderer when the app is running in a mobile browser, and CanvasKit renderer when the app is running in a desktop browser.
  • html - always use the HTML renderer.
  • canvaskit - always use the CanvasKit renderer.

See Choosing which option to use to decide about which option you should be using.

Alternatives

What I described above can be found in the flutter/engine/initialization.dart file. Make sure to check the master branch to see if the information is still up-to-date.

In there, you can see other options of configuring Flutter Web to use CanvasKit:

FLUTTER_WEB_AUTO_DETECT

--dart-define=FLUTTER_WEB_AUTO_DETECT=true

This can now also be done using:

--web-renderer auto

Supplying this constant will enable auto detect for the renderer detection:

  • CanvasKit will be used on desktop devices.
  • HTML will be used on mobile devices.

This only holds true if you do not specify window.flutterWebRenderer.

window.flutterWebRenderer

Iff you enable auto detect (see above), you can specify the renderer in your JavaScript code / HTML file dynamically:

...

<script>
  // This sets the Flutter web renderer in auto detect mode.
  // See https://stackoverflow.com/a/64583462/6509751.
  window.flutterWebRenderer = 'canvaskit';
</script>

<!-- This script installs service_worker.js to provide PWA functionality to
     application. For more information, see:
     https://developers.google.com/web/fundamentals/primers/service-workers -->
<script>
  var serviceWorkerVersion = null;
  ...

Summary

After discovering the auto detect PR, I really appreciate the following summary of the current situation in there:

If auto detect is enabled (set by environment variable FLUTTER_WEB_AUTO_DETECT), developers will be allowed to set window.flutterWebRender to either canvaskit or html to select the rendering backend. If window.flutterWebRender is not set, flutter engine will use canvaskit for desktop device while using html for mobile device. If window.flutterWebRender is set to an invalid value (not canvaskit nor html), it will default to html.

If auto detect is disabled, it will check the value of environment variable FLUTTER_WEB_USE_SKIA. If true, use canvaksit. Otherwise, use html.