
# Differences from Spring

Spring Boot has no Flutter counterpart, so most of this starter is new: widgets that receive beans, themes from YAML, a splash. Where it does take something from Spring Boot (the configuration files, profiles, `@ConfigurationProperties`, the lifecycle, DevTools' restart), it keeps Spring's names and behaviour. This page lists where a Flutter app behaves differently from a Spring Boot application, and why.

## Why

When you come from Spring, or share code with a Spring server, you need to know which habits carry over. Most differences come from three facts:

- **Dart is not Java.** There is no reflection at run time: the generator writes the application at build time.
- **A Flutter app is not a server.** It has a UI tree, a foreground and a background, a platform and a build mode, and no command line.
- **The app ships to users.** Everything in it can be read, and it must start fast behind a splash.

## Example

The same settings in both. The files are the same; the differences are in who reads what.

```yaml
# Spring Boot: src/main/resources/application.yml
# Flutter:     lib/resources/application.yml
spring:
  profiles:
    active: dev
shop:
  api-url: https://api.neon.books
```

## Starting the application

| Spring Boot | Here |
|---|---|
| `SpringApplication.run(App.class, args)` in `main` | `runApp(SpringApplicationWidget(application: () => springApplication))`; the context starts asynchronously behind a splash |
| `@SpringBootApplication` on a class | `@SpringBootApplication()` on the `main` function; the generator writes `springApplication` |
| The classpath is scanned at start | The generator scans `lib/` at build time; run `build_runner` after you change annotations |
| A failed start prints a report and exits | The report is logged and a failure screen shows; a hot reload that fixes it starts again |

## Configuration

- **Files** live in `lib/resources/` and are embedded into the generated code: no `flutter: assets:` entry, the same on every platform, at most 1 MB per file.
- **Platform and build profiles** are always active: `android` and `mobile`, `ios`, `web`, `macos` and `desktop`, ..., and `debug`, `profile` or `release`. Spring Boot has no such profiles.
- **No environment variables** by default: a phone's environment is noise. `--dart-define` values take their place, with the same relaxed names (`SHOP_API_URL`). A desktop build turns the environment on with `--dart-define=spring.flutter.scan-os-environment=true`.
- **Only known defines are seen.** A compiled app reads only the `--dart-define` names the generator found (placeholders, `@ConfigurationProperties` fields, keys of the files), because `String.fromEnvironment` needs constant names.
- **No secrets in the app.** Files, defines and assets all end up in the APK, the IPA or `main.dart.js`.
- **Remote configuration files** (`spring.config.import: https://...`) work because the start is asynchronous; Spring Boot reads such files through Spring Cloud Config instead.
- **Lists in two keys are single values.** `spring.flutter.app.locales` and `spring.messages.basename` must be one comma-separated value, also in YAML; a YAML list is not seen by the starter.

## Beans and widgets

- **Widgets are not beans.** Flutter creates them, so nothing is injected into them. They name their beans in their type (`SpringStatelessWidget<(Basket,)>`) or look them up (`context.bean<T>()`). A Java bean is never looked up from a UI tree.
- **A missing bean of a widget fails the start**, as a missing constructor dependency does in Spring, because the generator sees every widget's beans.
- **State beans notify by themselves.** `@ChangeNotifierComponent` and `@NotifyListeners` are advice around methods, like `@Transactional`; Spring has no counterpart.

## Lifecycle

- **The context pauses in the background**: `@Scheduled` tasks and WebSocket connections stop, and start again in the foreground. It is Spring Framework 7's `pause()` and `restart()`, driven by the app's lifecycle, which a server does not have.
- **`spring.main.register-shutdown-hook`** has no meaning in an app: the context closes when `SpringApplicationWidget` is removed.

## Hot reload

- **DevTools' restart** is built in and on by default: a hot reload that changed beans or files restarts the context, as Spring Boot DevTools restarts on a classpath change. `spring.devtools.restart.enabled=false` turns it off, with DevTools' own key. Runners do not run again unless `rerunRunnersOnReload: true`.
- Only the context restarts, not the app process.

## Design libraries

- **The starter has no design library.** Spring Boot has no UI to design. Material and Cupertino come with their own starters, `spring_boot_starter_flutter_material` and `spring_boot_starter_flutter_cupertino`, as a Spring Boot app gets Tomcat or Jetty from the starter it lists (see [Design libraries](design-libraries.md)).
- **The app type is a text naming a `SpringAppFactory` bean.** `spring.flutter.app.type: material` is the type of the Material starter's app factory; a type no bean has fails the start, naming the starter to add.
- **Not set, the app type is deduced, but two candidates are an error.** As Spring Boot deduces `spring.main.web-application-type` from the class path, the starters decide: one design starter (or one `SpringAppFactory` bean of the app's own type) makes the app of its type, none makes it `widgets`. Spring Boot, with both Spring MVC and WebFlux on the class path, picks servlet by a fixed priority; here app factories of several types fail the start, naming the property and the types. An app with both design starters is usually Material on some platforms and Cupertino on others, so the choice belongs in the configuration, per platform in profiles (`application-ios.properties`), not in a priority that would silently make every platform one of them. Set, the property always wins, as Spring Boot's does.
- **A design joins through `AutoConfigurationModule.factories`.** Its `ThemeDesign` is not a bean but a constant listed on its starter's module, because the themes are read for the splash before any bean exists. It is Spring Boot's `META-INF/spring.factories`, read by `SpringFactoriesLoader`; Dart has no class path to scan, so the generator copies the constants into `springApplication`.
- **Design properties are accepted unchecked without their starter.** Every theme key is checked, but `components`, `visual-density`, `tap-target-size`, a single-value `splash` and `cupertino` are accepted in an app without the starter that reads them: not shown, not checked, named once in the log. A theme library has values for apps of each design.
- **Page transitions are Flutter's by default.** Spring Boot has no screens to animate, so the default follows Flutter: `motion.page-transition` not set is `platform`, the app type's own (Material's per platform in a `MaterialApp`, the iOS slide in a `CupertinoApp`, none in an app without a design library). Before 0.8 it was none in every app type. One theme value, per theme and per profile, takes the place of Flutter's builders per platform (see [Transitions](../spring-boot-starter-flutter-navigation/transitions.md#as-in-flutter-and-where-it-differs)).

## Exports

- Boot's startup `Banner` is not exported, because Flutter has a `Banner` widget.
- The validation constraint `@Size` is exported as `SizeConstraint`, because `dart:ui` has `Size`.

## Known limits

- **`ThemeConfig` is not exported.** `SpringThemes.config` returns one and `SpringThemeData.of` takes one, but an app cannot name the type. Its values are readable (`themes.config.active`); to show a theme, use `SpringThemes.data(name)` and `ThemeSelection`.
- **Widgets with the same beans record share one binding.** When a bean is missing, the start fails naming one of the widgets that use the record, not each of them.
- **`SpringApplicationWidget` takes no bean overrides** for tests: a test that replaces beans and starts the whole app adds the overrides to a copy of `springApplication` itself.
- **The web has no SQLite directory yet**: nothing is set there.
- **The desktop window** has no position property, and does not restore the size and position the user left.

## See also

- [Overview](index.md)
- [Configuration in a Flutter app](configuration.md)
- [Differences of the generator](../spring-core-dart-generator/differences.md)
- [Differences of spring_boot_starter_web](../spring-boot-starter-web/differences.md)
