Resolve contradictions about deferred loading between Dart and Flutter

[elliette]

Page URL

https://docs.flutter.dev/perf/deferred-components
https://dart.dev/language/libraries#lazily-loading-a-library

Page source

No response

Describe the problem

I'm pretty sure that deferred loading is supported in Flutter when running on web and when running on Android.

However, https://docs.flutter.dev/perf/deferred-components states:

Note: This feature is currently only available on Android, taking advantage of Android and Google Play Stores’ dynamic feature modules to deliver the deferred components packaged as Android modules. Deferred code does not impact other platforms, which continue to build as normal with all deferred components and assets included at initial install time.

And https://dart.dev/language/libraries#lazily-loading-a-library states:

Only dart2js supports deferred loading. Flutter, the Dart VM, and dartdevc don’t support deferred loading. For more information, see issue #33118 and issue #27776.

Expected fix

If deferred loading is supported on both platforms, I would expect both notes to say so. If these are separate features (ie, "deferred loading" is different than "different components") than I would expect that to be better documented. Thanks!

Additional context

No response

[rekire]

I just run into the same situation that I'm confused about the documentation.

What is the current status?

When you change the documentation, it might me worth to mention how to create that libraries. This is still a mystery for me.

Not sure if helpful, but that documentation is hosted here: https://github.com/dart-lang/site-www/blob/main/src/_guides/language/language-tour.md#lazily-loading-a-library

Based on git blame this part of the documentation was not touched for 3 years!

[churchianity]

I still don't understand where the web platform stands in regards to this feature.

It sounds like if you use dart compile js to turn your source into js then it is supported, but how exactly is that integrated into the flutter build process?

[sfshaza2]

@ditman, can you clarify?

[ditman]

AFAIK deferred loading is supported on the web. It is used extensively in the Gallery app:

• Some code examples: https://github.com/flutter/gallery/blob/main/lib/data/demos.dart#L20-L21C32
• Deployed app: https://gallery.flutter.dev (notice in the Network panel things like main.dart.js_160.part.js)

I am not an expert on this, but AFAIK there's nothing special needed to do when compiling a Flutter web app: flutter build should generate the production chunks.

[jacobsimionato]

I ran into the same issue as this bug! Thanks for filing, Elliott!

So how about updating https://dart.dev/language/libraries#lazily-loading-a-library to explain that web and Android both support deferred loading.

And then update https://docs.flutter.dev/perf/deferred-components to explain that Web and Android both support this in Dart, but the setup will be different for each platform.

[atsansone]

@munificent: Any ideas as to why Dart docs contradict in this case?

[munificent]

No idea. Deferred loading is mostly a mystery to me. Maybe @lrhn, @eernst, or @leafpetersen would know?

[ditman]

"why Dart docs contradict"

My bet is that the feature was released, and then we forgot to properly update this bit of documentation :)

[lrhn]

I have no idea what the status of deferred loading on the VM is. We should ask the VM people.
@mkustermann

From the language's perspective, deferred loading has no effect on program semantics, other than restricting what you can do with deferred types and constants (can't use than as such), and allowing accesses through the prefix to throw until prefix.loadLibrary has succeeded.
Eagerly loading everything is a valid implementation strategy.
I believe that was what the VM did at some point.

For AOT, deferred loading is a deployment issue, more than a compilation issue. If the runtime doesn't have a compiler, it needs some way to introduce the support for the already compiled accesses to deferred declarations. I guess Flutter has done that.

[mkustermann]

I have no idea what the status of deferred loading on the VM is. We should ask the VM people.
@mkustermann

AFAIK: The VM supports deferred loading. Our AOT compiler can be told to emit deferred components and our AOT runtime will then ask the embedder (e.g. flutter) to load those deferred components. If the compiler is not instructed to do that the code will be eagerly included in the main app. (@rmacnak-google has implemented this, see also go/dart-aot-deferred-loading).

As mentioned above, Flutter enables actual deferred components only on Android.

So I think this needs a documentation update in https://dart.dev/language/libraries#lazily-loading-a-library

[jarrodcolburn]

IMO, conversation on tickets #8659 and #5165 relevant here.

---

Also, looking at Dart (not Flutter) site for [Web apps > Deployment > Make your app smaller... ](https://dart.dev/web/deployment#make-your-app-smaller-faster-and-more-reliable) you'll see

---

As @ditman points out Flutter (web) Gallery, where you can see all the .js files generated by being deferred as main.dart_js__###_.part.js (where ### is a number)` in devtools