Web hot reload breaks app when running as Web Server (-d web-server)

[agreaves]

Steps to reproduce

1. Create an empty Flutter project
2. Run flutter run -d web-server --web-experimental-hot-reload

Notice that the served Flutter application fails to load and just renders a blank screen.

Failure Case

Running flutter run -d web-server --web-experimental-hot-reload and opening relevant localhost (http://localhost:53392):

WAI Cases

Running flutter run -d web-server and opening relevant localhost (http://localhost:53392):

Running flutter run -d chrome --web-experimental-hot-reload:

Code sample

N/A (always breaks regardless of app details)

Flutter version

Flutter version observing the above behavior.

Flutter 3.30.0-1.0.pre.520 • channel master • https://github.com/flutter/flutter.git
Framework • revision a7e276a20d (2 days ago) • 2025-03-07 18:43:08 -0800
Engine • revision a7e276a20d (2 days ago) • 2025-03-07 18:43:08 -0800
Tools • Dart 3.8.0 (build 3.8.0-149.0.dev) • DevTools 2.43.0

Side note: I tried upgrading to the latest version on master and running on chrome (with hot reload) but that failed entirely. I won't file another ticket as I'm guessing it will be fixed soon, but just in case here's the Flutter version for that:

Flutter 3.30.0-1.0.pre.525 • channel master • https://github.com/flutter/flutter.git
Framework • revision 93c8ed0775 (60 minutes ago) • 2025-03-09 12:36:24 -0400
Engine • revision 93c8ed0775 (60 minutes ago) • 2025-03-09 12:36:24 -0400
Tools • Dart 3.8.0 (build 3.8.0-149.0.dev) • DevTools 2.43.0

Second side note: This is extremely impressive work and such a major value add to the Flutter community! Congrats to all involved! 🎉

[nshahan]

Thanks for the report!

The docs here describe the web-server flag as a way to open the app in any browser of your choice. https://docs.flutter.dev/platform-integration/web/building#run-your-app

AFAIK the hot reload support is tightly coupled with Chrome DevTools to control the execution and synchronize events in the Dart tooling while libraries are being replaced in the browser at runtime. We don't have any plans to expand that to support developer tools in other browsers at this time.

@srujzs @jyameo
Is that assessment correct? Do you think we should print a warning or error if you try and pass
-d web-server --web-experimental-hot-reload? Would there be any way we could support a random chrome instance that loads the page that wasn't launched by flutter tools?

[biggs0125]

Can we confirm whether or not hot restart was working when running with the 'web-server' device? If so it seems like adding similar support for hot reload should be doable. But if not, I don't think we need to add it at the moment.

More generally though, even if hot reload isn't supported, this implies our new module system isn't working with this run configuration. I repro-ed this locally and didn't see any errors in the console. I think the main isn't getting invoked. I believe the bootstrap script it's producing is still referencing the loader for the old module system instead of the dartDevEmbedder:
https://github.com/flutter/flutter/blob/b16430b2fd57a5aa6b6c680cdbda5582506fe120/packages/flutter_tools/lib/src/web/bootstrap.dart#L485

[srujzs]

I do see us using the dartDevEmbedder with the given flags, but the issue is that we don't have any of the code that DWDS injects since we're not using Chrome.

With AMD, this doesn't seem to be an issue, because require.js implicitly handles the needed dependencies, but with the DDC library bundle format, we need DWDS (or something...) to load the necessary sources. Since we never call that load, main is never triggered.

Hot restart also requires a hard refresh of the page with the web server (probably because DWDS isn't there to handle it correctly).

[biggs0125]

It makes sense that a refresh is required given nothing is attached to the running browser. So in that case hot reload itself doesn't make sense in this context. I don't think there's a need to try to attach DWDS onto the Chrome process in this web-server case.

But we do need apps to run in this environment. We will need to figure out what should be loading the sources into the page for the dartDevEmbedder. More generally, we should decouple the initial sources loading from DWDS. Hot reload and hot restart will require a running debug service but the program should still run in environments where those features aren't supported.

Can we inject information into the bootstrap script that allows it to load the sources itself?

[srujzs]

Can we inject information into the bootstrap script that allows it to load the sources itself?

We could reuse some of the DWDS code to do that part: https://github.com/dart-lang/webdev/blob/8f146a15fba4d7c0dc76b51e083a5459216126cf/dwds/lib/src/handlers/injector.dart#L95 without needing the injected client or any of the code to set up DWDS debugging. Separating out that latter part so we don't try and include it and just setting up the right code to handle loading and fetching sources will require work in DWDS.

It's likely preferable to use DWDS for that purpose instead of reimplementing all the logic to parse module metadata and set up paths correctly.

FYI @bkonyi