Customizing web app initialization
You can customize how a Flutter app is initialized on the web
using the _flutter.loader
JavaScript API.
This API can be used to display a loading indicator in CSS,
prevent the app from loading based on a condition,
or wait until the user presses a button before showing the app.
The initialization process is split into the following stages:
- Loading the entrypoint script
- Fetches the
main.dart.js
script and initializes the service worker. - Initializing the Flutter engine
- Initializes Flutter’s web engine by downloading required resources such as assets, fonts, and CanvasKit.
- Running the app
- Prepares the DOM for your Flutter app and runs it.
This page shows how to customize the behavior at each stage of the initialization process.
Getting started
By default, the index.html
file
generated by the flutter create
command
contains a script tag
that calls loadEntrypoint
from the flutter.js
file:
<html>
<head>
<!-- ... -->
<script src="flutter.js" defer></script>
</head>
<body>
<script>
window.addEventListener('load', function (ev) {
// Download main.dart.js
_flutter.loader.loadEntrypoint({
serviceWorker: {
serviceWorkerVersion: serviceWorkerVersion,
}
}).then(function (engineInitializer) {
// Initialize the Flutter engine
return engineInitializer.initializeEngine();
}).then(function (appRunner) {
// Run the app
return appRunner.runApp();
});
});
</script>
</body>
</html>
The loadEntrypoint
function returns a JavaScript Promise
that resolves when the Service Worker is initialized
and the main.dart.js
entrypoint has been downloaded by the browser.
It resolves with an engine initializer object
that initializes the Flutter Web engine.
The initializeEngine()
function returns a promise
that resolves with an app runner object
that has a single method runApp()
that runs the Flutter app.
Customizing web app initialization
In this section, learn how to customize each stage of your app’s initialization.
Loading the entrypoint
The loadEntrypoint
method accepts these parameters:
entrypointUrl
- The URL of your Flutter app’s entrypoint. Defaults to
main.dart.js
. serviceWorker
- The configuration of the
flutter_service_worker.js
file. If this isn’t set, the service worker won’t be used. serviceWorkerVersion
- Pass the
serviceWorkerVersion
var set by the build process in yourindex.html
file. timeoutMillis
- The timeout value for the service worker load.
Defaults to
4000ms
.
Initializing the engine
Instead of calling initializeEngine()
on the engine initializer,
you can call autoStart()
to immediately start the app
with the default configuration
instead of using the app runner to call runApp()
:
_flutter.loader.loadEntrypoint({
serviceWorker: {
serviceWorkerVersion: serviceWorkerVersion,
}
}).then(function(engineInitializer) {
return engineInitializer.autoStart();
});
Example: Display a progress indicator
To give the user of your application feedback during the initialization process, use the hooks provided for each stage to update the DOM:
<html>
<head>
<!-- ... -->
<script src="flutter.js" defer></script>
</head>
<body>
<div id="loading"></div>
<script>
window.addEventListener('load', function(ev) {
var loading = document.querySelector('#loading');
loading.textContent = "Loading entrypoint...";
_flutter.loader.loadEntrypoint({
serviceWorker: {
serviceWorkerVersion: serviceWorkerVersion,
}
}).then(function(engineInitializer) {
loading.textContent = "Initializing engine...";
return engineInitializer.initializeEngine();
}).then(function(appRunner) {
loading.textContent = "Running app...";
return appRunner.runApp();
});
});
</script>
</body>
</html>
For a more practical example using CSS animations, see the initialization code for the Flutter Gallery.
Upgrading an older project
You can create a new index.html
file
with the latest template by deleting the old files
from the web
directory and running flutter create
.
From your project directory, run the following:
$ flutter create . --platforms=web