Migrating from FlutterLoader.loadEntrypoint to load in Flutter 3.22+
Problem Statement
When upgrading to Flutter 3.22.0 or later, developers encounter a deprecation warning: "The use of 'FlutterLoader.loadEntrypoint' is deprecated. Please use 'FlutterLoader.load' instead." After replacing loadEntrypoint with load, a new error appears: "FlutterLoader.load requires _flutter.buildConfig to be set." This occurs because the updated load method requires additional configuration parameters and project setup that differs from the previous implementation.
Recommended Solutions
There are two recommended approaches to resolve this issue:
Solution 1: Regenerate Web Files (Best for Most Projects)
For existing projects, the simplest solution is to regenerate your web platform files:
Delete existing web files:
bashrm -rf web/Regenerate web platform files:
bashflutter create . --platforms=webReapply customizations (if any): Copy back any custom assets or configurations you had in your
webdirectory.
This approach ensures compatibility with the latest Flutter web bootstrapping process without manual configuration.
Solution 2: Manual Configuration Update (Advanced)
For projects needing custom initialization (e.g., splash screens), manually update your index.html:
- Add Flutter's bootstrapping libraries:
<script>
window.addEventListener('load', function(ev) {
{{flutter_js}}
{{flutter_build_config}}
_flutter.loader.load({
serviceWorker: {
serviceWorkerVersion: {{flutter_service_worker_version}},
},
onEntrypointLoaded: function(engineInitializer) {
engineInitializer.initializeEngine().then(function(appRunner) {
// Add custom initialization logic here
appRunner.runApp();
});
}
});
});
</script>- Add splash screen elements:
<picture id="splash">
<source srcset="splash/light.png" media="(prefers-color-scheme: light)">
<source srcset="splash/dark.png" media="(prefers-color-scheme: dark)">
<img src="splash/default.png" alt="Loading..."/>
</picture>- Remove splash screen after initialization:
if(document.getElementById('splash'))
document.getElementById('splash').remove();Key Changes Explained
_flutter.buildConfigrequirement: The newloadmethod requires configuration objects generated during build (flutter_js,flutter_build_config)- Automatic placeholders:
{{flutter_js}}and{{flutter_build_config}}are automatically replaced duringflutter build web - Service worker configuration: The updated API requires explicit service worker version specification
- Initialization sequence: Engine initialization is now explicit through
initializeEngine()
Best Practices
- Update existing projects: Use the regeneration method unless your project has complex web customizations
- Check documentation: Refer to Flutter's official Web Bootstrapping documentation for updates
- Verify deployment: Test your web build locally before deploying:bash
flutter build web flutter run -d chrome - Preserve entrypoints: Migration maintains application entrypoints, ensuring your app starts correctly
Update Strategy
For new projects created with Flutter 3.22+, the default template already uses the correct implementation:
<body>
<script src="flutter_bootstrap.js" async></script>
</body>Custom Project Considerations
Heavily customized web implementations should use manual configuration approach. Always back up your web directory before regeneration.