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

[jyameo]

I can take a look at this issue. I'll follow Srujan's suggestion to reuse parts of DWDS in Flutter tools to load the necessary files. will reach out if I have any questions or run into issues.

[kkoskenvirta]

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

I don't know how it works under the hood but i am running the web-server device commonly and using hot-reload on every time i save a file. Atleast that triggers the hot-reload, when running in debug I am also required to attach the debugger with the browser add-on.

[jyameo]

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

I don't know how it works under the hood but i am running the web-server device commonly and using hot-reload on every time i save a file. Atleast that triggers the hot-reload, when running in debug I am also required to attach the debugger with the browser add-on.

That's interesting... a couple of us were able to reproduce the issue consistently, so I'm surprised to hear that hot reload is working for you in this context. Could you share more details about the Flutter/Dart version you're using?

I'm currently rolling out a fix that will reuse parts of DWDS to handle source loading without requiring the injected client or DWDS debugging.

[agreaves]

Hey folks! Thanks so much for looking into this. Unfortunately this issue is still reproducible (via the original steps) even in the master or beta channels. Could we re-open the issue? It's quite an important use case for us.

[jyameo]

Hey folks! Thanks so much for looking into this. Unfortunately this issue is still reproducible (via the original steps) even in the master or beta channels. Could we re-open the issue? It's quite an important use case for us.

@agreaves Thanks for the follow-up! I’ll take a look and see what’s going on. Appreciate your patience.

[jyameo]

I took a look at the issue, and I noticed something interesting. When I run the app directly from VS Code using -d web-server --web-experimental-hot-reload, the page loads as expected. But when I run the same command from the terminal and manually open the app URL in the browser, the page appears blank.

The only difference I can see is that VS Code launches the browser automatically, whereas from the terminal, I have to open it manually. My hunch is that this might be related to how or when the bootstrap scripts are loaded; since the main entrypoint runs as soon as the scripts are loaded, maybe there's a timing issue or race condition at play.

@srujzs Do you have any thoughts on what might be causing this discrepancy between the two methods?

For reference, here's my launch.json configuration in VS Code:

{
  "name": "Web-server with Hot-reload ENABLED",
  "type": "dart",
  "request": "launch",
  "program": "lib/main.dart",
  "args": [
    "-d",
    "web-server",
    "--web-experimental-hot-reload"
  ]
}

[srujzs]

The difference between VS code and running it directly might be due to this: https://github.com/flutter/flutter/blob/07b09836576b48278774cda9084da1d451fc258f/packages/flutter_tools/lib/src/isolated/resident_web_runner.dart#L160

It looks like VS code starts Flutter with --start-paused for some reason. When using the web server, DWDS is only enabled when this flag is set: https://github.com/flutter/flutter/blob/07b09836576b48278774cda9084da1d451fc258f/packages/flutter_tools/lib/src/isolated/resident_web_runner.dart#L166

Without enabling DWDS, the scripts are never added to the bootstrap, and nothing runs.

flutter run -d web-server --web-experimental-hot-reload --start-paused makes this work. I'm not sure why --start-paused is needed though.

[bkonyi]

I'm not sure why --start-paused is needed though.

I'm 99% sure this is so VSCode can set breakpoints set before the application has run (@DanTup, can you confirm?).

[DanTup]

I'm 99% sure this is so VSCode can set breakpoints set before the application has run (@DanTup, can you confirm?).

This is correct. If we don't start the app paused and you have breakpoints in code that runs very early, then it may have already executed before we were able to add the breakpoint. So we must start the app paused, send breakpoints, and then resume.

Btw, when running from VS Code, it will also provide some other flags like --machine that may affect the code path taken in Flutter tools. Generally the web-server device is used in contexts where Chrome cannot be spawned (for example in a remote workspace or browser-based IDE with a remote container) and the Dart Debug extension is used as a proxy for the debugger (whereas when launching Chrome, flags are used to open a debug port instead).

[jyameo]

Thanks all! That makes a lot of sense. It's interesting because flutter run -d web-server seems to work without the --start-paused flag, while flutter run -d web-server --web-experimental-hot-reload appears to require it for the app to load properly. I’ll investigate further to understand exactly what’s going on in both cases, particularly whether --start-paused is strictly required to run on a web-server with the new DDC Library Bundle format. Will report back once I have more clarity.