From 5269282c0d67307144f7c2974cef9d4d671961dc Mon Sep 17 00:00:00 2001 From: Jakub Stolarczyk Date: Sat, 20 Jun 2026 00:16:00 +0200 Subject: [PATCH 1/2] [docs] Clarify config isn't forwarded with custom onEntrypointLoaded The `config` passed to `_flutter.loader.load()` is only applied to the engine automatically in the default auto-start path. When a custom `onEntrypointLoaded` callback is supplied, the loader hands over only the engine initializer, so the config must be passed to `initializeEngine()` manually. Add a warning documenting this and clarify the existing no-argument `initializeEngine()` example. --- .../web/initialization.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/sites/docs/src/content/platform-integration/web/initialization.md b/sites/docs/src/content/platform-integration/web/initialization.md index 7b2ee829834..3b41dcf21de 100644 --- a/sites/docs/src/content/platform-integration/web/initialization.md +++ b/sites/docs/src/content/platform-integration/web/initialization.md @@ -211,6 +211,29 @@ The initialization process is split into the following stages: [embedded-mode]: {{site.docs}}/platform-integration/web/embedding-flutter-web/#embedded-mode [js-promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise +:::warning +When you provide your own `onEntrypointLoaded` callback, the `config` +that you pass to `_flutter.loader.load()` is **not** forwarded to the +engine automatically. Flutter only applies that `config` for you when +you omit `onEntrypointLoaded` and let the loader start the app. + +In a custom callback, pass the configuration to `initializeEngine()` +yourself, otherwise it's silently ignored: + +```js +_flutter.loader.load({ + onEntrypointLoaded: async function(engineInitializer) { + const appRunner = await engineInitializer.initializeEngine({ + // Set your run-time configuration here. + renderer: 'canvaskit', + }); + await appRunner.runApp(); + }, +}); +``` + +::: + ## Example: Display a progress indicator To give the user of your application feedback @@ -227,6 +250,8 @@ loading.textContent = "Loading Entrypoint..."; _flutter.loader.load({ onEntrypointLoaded: async function(engineInitializer) { loading.textContent = "Initializing engine..."; + // Pass your `config` here. Any config given to `load()` is not + // forwarded when you supply your own `onEntrypointLoaded` callback. const appRunner = await engineInitializer.initializeEngine(); loading.textContent = "Running app..."; From 1e1a526e7f4c4e8438e05594880c466b09d78d5b Mon Sep 17 00:00:00 2001 From: Jakub Stolarczyk Date: Sat, 20 Jun 2026 01:08:18 +0200 Subject: [PATCH 2/2] [docs] Address review: make config comment conditional --- .../src/content/platform-integration/web/initialization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sites/docs/src/content/platform-integration/web/initialization.md b/sites/docs/src/content/platform-integration/web/initialization.md index 3b41dcf21de..5af317ffcdf 100644 --- a/sites/docs/src/content/platform-integration/web/initialization.md +++ b/sites/docs/src/content/platform-integration/web/initialization.md @@ -250,8 +250,8 @@ loading.textContent = "Loading Entrypoint..."; _flutter.loader.load({ onEntrypointLoaded: async function(engineInitializer) { loading.textContent = "Initializing engine..."; - // Pass your `config` here. Any config given to `load()` is not - // forwarded when you supply your own `onEntrypointLoaded` callback. + // If you have a `config`, pass it here. The config given to `load()` + // is not forwarded when you supply your own `onEntrypointLoaded`. const appRunner = await engineInitializer.initializeEngine(); loading.textContent = "Running app...";