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 your index.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

If your project was created in Flutter 2.10 or earlier, you can create a new index.html file with the latest initialization template by running flutter create as follows.

First, remove the files from your /web directory.

Then, from your project directory, run the following:

$ flutter create . --platforms=web