Update documentation for new flutter bootstrapping APIs. #10256
Conversation
|
Visit the preview URL for this PR (updated for commit 2b47b70): https://flutter-docs-prod--pr10256-flutter-bootstrap-documenta-b12b9apw.web.app |
| produced by the build step, you can place a `flutter_bootstrap.js` file in the | ||
| `web` subdirectory of your project, which will be copied over and used in lieu | ||
| of the default script produced by the build. This file is also templated, and | ||
| you can insert several special tokens which the build step will substitute at |
There was a problem hiding this comment.
Is it "can" or "should"? Can one write a working flutter_bootstrap.js script without including of tokens at all? Or are some of them required?
There was a problem hiding this comment.
You potentially can add the tokens to the flutter_bootstrap.js, or inline in the index.html.
| |`serviceWorkerVersion`| Pass *the `serviceWorkerVersion` variable* set by the build process in your **`index.html`** file. |`String`| | ||
| |`timeoutMillis`| The timeout value for the service worker load. Defaults to `4000`. |`Number`| | ||
| |`config`| The user configuration of your Flutter app. |`Object`| | ||
| |`onEntrypointLoaded`| The function called when the engine is ready to be initialized. Receives an `engineInitializer` object as its only parameter. |`Function`| |
There was a problem hiding this comment.
I think it would be useful to explain why this function exists. IIRC, it's so you can be notified when engine resources are fetched over the network, but the engine is not yet rendering anything. The function can be used to kick off pre-caching of resources while the user is interacting with the landing page, but delay engine initialization until the user asks to start the app.
| Your Flutter app should target an HTML element with `id="flutter_app"` and | ||
| use the `canvaskit` renderer. The resulting JavaScript code would resemble | ||
| the following: | ||
| In some cases, one might want to allow the user to force the use of the |
There was a problem hiding this comment.
Summoning my inner @sfshaza2: I'd remove "In some cases, one might want to" and shorten the text. For example: "Here's an example of a custom flutter_bootstrap.js script that allows the user to force the CanvasKit renderer by providing ..."
| ## The `onEntrypointLoaded` callback | ||
|
|
||
| #### Skipping this step | ||
| You can also pass an `onEntrypointLoaded` callback into the `load` API in order |
There was a problem hiding this comment.
Consider removing "You can also" and start with "Pass an..."
|
/gcbrun |
|
Just some notes on the column sizes, otherwise LGTM! |
sfshaza2
left a comment
There was a problem hiding this comment.
@eyebrowsoffire, thanks for this thorough PR!
I'm wondering... maybe we should add this page to the sidenav? Currently the sidebar lists, under Platform integration -> Web only the older version of this doc. Now, it's true that the early in the page that it suggests they click over if they are using 3.21 or later, but we could put both in the sidenav. Like. "Custom app initialization (before 3.22)" and "Flutter app initialization (3.22 or later)".
ALSO, this sounds like a breaking change. We usually provide a page under breaking changes. In this case, perhaps you could create a very basic breaking change page that then links to THIS page.
Thoughts?
|
@sfshaza2 Thanks for the review!
Currently the wasm page is also not listed in the side-nav. I figured maybe we should leave this off the sidebar until it lands in stable, then we can remove the old page and replace it with this one (which will be linked in the sidebar). I'm open to other ideas, but having more than one sidebar option for "web app initialization" seemed a bit more confusing, so I figured it might make more sense to just let people come to the existing page, and click through to the new page based on the note at the top.
This is actually not a breaking change. The old APIs ( |
Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>
ditman
left a comment
There was a problem hiding this comment.
LGTM! Thanks for documenting this!
|
Are we ready to land this? |
sfshaza2
left a comment
There was a problem hiding this comment.
Thanks for fixing the tables! This looks great! lgtm
This updates the documentation to be in line with the new changes to bootstrapping that are coming in this PR: flutter/flutter#144434