Switching to Flutter 3.22 for Web
Introduction
Flutter 3.22 introduces significant enhancements for web development, focusing on customizable app initialization. If you’re migrating from an older version or starting fresh, this guide will walk you through the process. We’ll cover platform integration, web app initialization, and how to customize the initialization process using the flutter_bootstrap.js file.
Flutter Web App Initialization
Platform Integration
Integrating Flutter into your web platform involves setting up a proper initialization process to ensure smooth performance and functionality. Flutter 3.22 provides a more flexible way to customize this process, catering to different app requirements.
Web App Initialization Process
The initialization process for a Flutter web app is streamlined but customizable. It revolves around the flutter_bootstrap.js script, generated during the build process, which handles the app's startup sequence.
The flutter_bootstrap.js Script
When you build your Flutter web app using flutter build web, the process generates a script named flutter_bootstrap.js in the build/web directory. This script is essential for initializing and running your app.
To include this script in your index.html, add the following code:
<html>
<body>
<script src="flutter_bootstrap.js" async></script>
</body>
</html>Alternatively, you can inline the script by inserting the {{flutter_bootstrap_js}} token:
<html>
<body>
<script>
{{flutter_bootstrap_js}}
</script>
</body>
</html>Customizing Initialization
By default, the flutter build web command generates a basic flutter_bootstrap.js script. However, you may need to customize this initialization for various reasons, such as setting a custom configuration or modifying service worker settings.
To customize the initialization process, create your own flutter_bootstrap.js file in the web directory of your project. This custom script will replace the default one generated during the build.
Tokens for Customization
You can use several tokens in your custom flutter_bootstrap.js file:
{{flutter_js}}: Makes the_flutter.loaderobject available.{{flutter_build_config}}: Sets metadata for the FlutterLoader.{{flutter_service_worker_version}}: Represents the build version of the service worker.
Writing a Custom flutter_bootstrap.js
A custom flutter_bootstrap.js script needs three main components:
- A
{{flutter_js}}token. - A
{{flutter_build_config}}token. - A call to
_flutter.loader.load()to start the app.
A basic example looks like this:
{{flutter_js}}
{{flutter_build_config}}
_flutter.loader.load();The _flutter.loader.load() API
The _flutter.loader.load() function can accept optional arguments for more customized initialization:
config: Configuration object for your app.onEntrypointLoaded: Callback function called when the engine is ready to be initialized.serviceWorkerSettings: Configuration for the service worker.
Configuration Options
The config object can include various fields:
assetBase: Base URL for the assets directory.canvasKitBaseUrl: Base URL for downloadingcanvaskit.wasm.canvasKitVariant: Specifies the CanvasKit variant (auto,full, orchromium).canvasKitForceCpuOnly: Forces CPU-only rendering if set to true.canvasKitMaximumSurfaces: Maximum number of overlay surfaces.debugShowSemanticNodes: Renders the semantics tree onscreen for debugging.hostElement: HTML element where Flutter renders the app.renderer: Specifies the web renderer (canvaskitorhtml).
Customizing Flutter Configuration Based on URL Query Parameters
Here’s an example that customizes the configuration based on URL query parameters:
{{flutter_js}}
{{flutter_build_config}}
const searchParams = new URLSearchParams(window.location.search);
const forceCanvaskit = searchParams.get('force_canvaskit') === 'true';
const userConfig = forceCanvaskit ? {'renderer': 'canvaskit'} : {};
_flutter.loader.load({
config: userConfig,
serviceWorkerSettings: {
serviceWorkerVersion: {{flutter_service_worker_version}},
},
});Using the onEntrypointLoaded Callback
The onEntrypointLoaded callback allows you to perform custom logic at different stages of the initialization:
{{flutter_js}}
{{flutter_build_config}}
const loading = document.createElement('div');
document.body.appendChild(loading);
loading.textContent = "Loading Entrypoint...";
_flutter.loader.load({
onEntrypointLoaded: async function(engineInitializer) {
loading.textContent = "Initializing engine...";
const appRunner = await engineInitializer.initializeEngine();
loading.textContent = "Running app...";
await appRunner.runApp();
}
});Upgrading an Older Project
If you’re upgrading from Flutter 3.21 or earlier, follow these steps to create a new index.html file:
- Remove the existing files from your
/webdirectory. - Run the following command in your project directory:
flutter create . --platforms=webConclusion
Switching to Flutter 3.22 for web development offers enhanced flexibility and customization for app initialization. By understanding and leveraging the flutter_bootstrap.js script, you can fine-tune the startup process to meet your app's specific needs. Whether you're customizing configurations or upgrading an older project, this guide provides the detailed steps to get you started.
