Skip to content

[docs] Clarify config isn't forwarded with custom onEntrypointLoaded#13521

Open
StolarczykJakub wants to merge 2 commits into
flutter:mainfrom
StolarczykJakub:docs-web-init-config-forwarding
Open

[docs] Clarify config isn't forwarded with custom onEntrypointLoaded#13521
StolarczykJakub wants to merge 2 commits into
flutter:mainfrom
StolarczykJakub:docs-web-init-config-forwarding

Conversation

@StolarczykJakub

@StolarczykJakub StolarczykJakub commented Jun 19, 2026

Copy link
Copy Markdown

Description of what this PR is changing or adding, and why:

The web initialization docs imply that setting config in
_flutter.loader.load() is enough for it to reach the engine. That's only
true on the default auto-start path. When a custom onEntrypointLoaded
callback is supplied, the loader passes that callback only the engine
initializer — the config from load() is not forwarded, so it is
silently dropped unless it is passed to initializeEngine(config) directly.

The existing "Display a progress indicator" example calls
initializeEngine() with no arguments, which reinforces the
misunderstanding in the most commonly copied onEntrypointLoaded snippet.

Why this matters: the failure is silent and easy to hit in production. A
custom onEntrypointLoaded that sets canvasKitForceCpuOnly: true to work
around 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 rendering when CPU-only is
active, 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:

  • Adds a :::warning in the onEntrypointLoaded callback section stating
    that config from load() is not forwarded when a custom
    onEntrypointLoaded is used, with a short example that passes the config
    to initializeEngine().
  • Adds a clarifying comment to the no-argument initializeEngine() call in
    the progress-indicator example.

Verified against the engine's flutter.js loader source: the default
onEntrypointLoaded closure is the only place that captures config and
passes it to initializeEngine(config) (in the minified loader the default
callback is l => l.initializeEngine(t)). When a custom callback is
supplied, didCreateEngineInitializer forwards only the engine
initializer, 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

  • If you are unwilling, or unable, to sign the CLA, even for a tiny, one-word PR, please file an issue instead of a PR.
  • If this PR is not meant to land until a future stable release, mark it as draft with an explanation.
  • This PR follows the Google Developer Documentation Style Guidelines—for example, it doesn't use i.e. or e.g., and it avoids I and we (first-person pronouns).
  • This PR uses semantic line breaks
    of 80 characters or fewer.

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.
@StolarczykJakub StolarczykJakub requested review from a team and sfshaza2 as code owners June 19, 2026 22:17

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread sites/docs/src/content/platform-integration/web/initialization.md Outdated
@StolarczykJakub StolarczykJakub deleted the docs-web-init-config-forwarding branch June 19, 2026 22:19
@StolarczykJakub StolarczykJakub restored the docs-web-init-config-forwarding branch June 19, 2026 22:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant