
# Hot reload

A hot reload swaps method bodies in place but does not run `main` again, so a running context would keep the beans it was built with. `spring_boot_dart` compares a fingerprint of the generated code and decides (the fingerprint and `reloadApplication` are in `main.spring.debug.dart`, which a release build does not compile): keep the context when only method bodies changed, restart it when beans, annotations or `lib/resources/` changed. It is the counterpart of Spring Boot DevTools' restart.

## Why

During development you change code all the time. A changed method body should take effect at once, with the beans' state kept. A new bean, a new `@GetMapping` or another `server.port` needs a new context, and restarting the whole program for it is slow. The fingerprint tells the two cases apart.

## Example

In Flutter, call the generated `reloadApplication` from `reassemble()` of the root widget's `State`, which Flutter calls on every hot reload:

```dart
late ConfigurableApplicationContext context;

@SpringBootApplication()
Future<void> main() async {
  context = await runApplicationAsync(const []);
  runApp(const App());
}

class _AppState extends State<App> {
  @override
  void reassemble() {
    super.reassemble();
    context = reloadApplication(context, runners: false);
  }

  @override
  Widget build(BuildContext context) => ...; // look beans up here, not in initState
}
```

`spring_boot_starter_flutter`'s `SpringApplicationWidget` does this for you.

## What happens on a reload

| What changed | Result |
|---|---|
| Only method bodies (same fingerprint) | The context is kept; the beans keep their state and already run the new code |
| Beans, annotations or `lib/resources/` (with `build_runner watch` running) | The context is closed and started again with the same arguments and profiles |

Objects kept in fields (a bean fetched once in `initState`) still point to the old context after a restart; look beans up in `build` or after `reassemble`. A hot restart always starts from scratch.

## Runners after a restart

When a reload restarts the context, it starts like a fresh launch, so by default the runners run again, as after a DevTools restart. Pass `runners: false` to restart the beans without repeating the start-up work:

| | `runners: true` (default) | `runners: false` |
|---|---|---|
| Beans after a restart | new | new |
| `CommandLineRunner`, `ApplicationRunner` | run again | skipped |
| Good for | runners that only prepare in-memory state | migrations, analytics events, notifications, network calls |

When only method bodies changed, runners never run, whatever the flag says. `runApplication` and `runApplicationAsync` (a real start) always run them. `reloadApplicationAsync` reads config files asynchronously.

## Servers and command-line tools

A program on the Dart VM hot reloads too. The generated `runApplication` registers its context. After the VM has reloaded the code (`reloadSources`, called by a tool), the tool calls the VM service extension `ext.spring_boot.reload` (`SpringHotReload.extensionName`):

- only method bodies changed: the context keeps running with the new code;
- the generated code changed (a new `@GetMapping`, another `server.port`): the context is closed and starts again, so the web server stops and listens again. If that start fails, the extension answers with the error, and the next reload starts the application again.

```bash
# What a tool does, by hand:
dart run --enable-vm-service bin/main.dart
# on save: build_runner build, then reloadSources and ext.spring_boot.reload over the VM service
```

The `dart run` tasks of the Flutter tools Zed extension do this on save.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.devtools.restart.enabled` | bool | `true` | `false` keeps the context (the server, its connections, the beans' state) running whatever changed; new beans and config take effect when the program restarts |

Hot reload works only in debug runs: not in AOT or product builds, and not on the web.

When a reload restarts the context of a server with a [pool of isolates](../spring-boot-starter-web/server/isolates.md), the pool stops with it and the new context starts the isolates again. How the application was started (`ApplicationLaunch`) is kept across the reload.

## In Spring (Java)

Spring Boot DevTools restarts the application when class files change, and reruns the runners. Here the fingerprint of the generated code decides, so a change of method bodies keeps the state; `runners: false` has no DevTools counterpart.

## See also

- [SpringApplication](spring-application.md)
- [Runners](runners.md)
- [The generator: @SpringBootApplication](../spring-core-dart-generator/spring-boot-application.md)
