[docs] Clarify config isn't forwarded with custom onEntrypointLoaded#13521
Open
StolarczykJakub wants to merge 2 commits into
Open
[docs] Clarify config isn't forwarded with custom onEntrypointLoaded#13521StolarczykJakub wants to merge 2 commits into
StolarczykJakub wants to merge 2 commits into
Conversation
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.
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the Flutter Web initialization documentation to warn users that configuration is not automatically forwarded to the engine when using a custom onEntrypointLoaded callback. The reviewer suggested clarifying a comment in the example code to make it clear that passing the configuration is conditional, as no configuration is defined in that specific example.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description of what this PR is changing or adding, and why:
The web initialization docs imply that setting
configin_flutter.loader.load()is enough for it to reach the engine. That's onlytrue on the default auto-start path. When a custom
onEntrypointLoadedcallback is supplied, the loader passes that callback only the engine
initializer — the
configfromload()is not forwarded, so it issilently dropped unless it is passed to
initializeEngine(config)directly.The existing "Display a progress indicator" example calls
initializeEngine()with no arguments, which reinforces themisunderstanding in the most commonly copied
onEntrypointLoadedsnippet.Why this matters: the failure is silent and easy to hit in production. A
custom
onEntrypointLoadedthat setscanvasKitForceCpuOnly: trueto workaround a CanvasKit rendering bug in an Android in-app browser has no effect,
and produces no error or warning. The only tell is an absent signal: the
engine always logs
Falling back to CPU-only renderingwhen CPU-only isactive, so the missing log line is the sole hint that the config never
reached the engine. Because this failure mode is completely silent, a doc
note is the only thing that surfaces it.
This PR makes two changes to
platform-integration/web/initialization.md::::warningin the onEntrypointLoaded callback section statingthat
configfromload()is not forwarded when a customonEntrypointLoadedis used, with a short example that passes the configto
initializeEngine().initializeEngine()call inthe progress-indicator example.
Verified against the engine's
flutter.jsloader source: the defaultonEntrypointLoadedclosure is the only place that capturesconfigandpasses it to
initializeEngine(config)(in the minified loader the defaultcallback is
l => l.initializeEngine(t)). When a custom callback issupplied,
didCreateEngineInitializerforwards only the engineinitializer, so the config never reaches the engine automatically. Scope is
a single Markdown file, with no code or config changes.
Issues fixed by this PR (if any):
None.
PRs or commits this PR depends on (if any):
None.
Presubmit checklist
of 80 characters or fewer.