
# spring_boot_starter_flutter

`spring_boot_starter_flutter` brings Spring Boot into a Flutter app. You write your services and your app state as plain classes marked `@Component()`. The framework creates one object of each, a **bean**, and connects them: a bean that needs another one asks for it in its constructor. All beans live in the **application context**, which starts when the app starts. The starter puts that context into the widget tree, so any widget can get the beans it needs, and widgets that show a bean's state rebuild when it changes.

You do not need to know Spring to use it. If you do, you will find the same model: `@Component`, `@Value`, `@ConfigurationProperties`, profiles, events and `application.yml`.

## Why

A Flutter app has no standard place for its services and its shared state. Each app picks a state library, passes objects through constructors, and keeps its settings in Dart code. The starter gives one model for all of it:

- **State and services are beans.** A widget lists the beans it needs in its type and gets them in `build`. No `Provider` tree, no constructor chains.
- **State beans notify by themselves.** A class marked `@ChangeNotifierComponent()` needs no `notifyListeners()` call: its generated proxy makes it after every method.
- **The app is configuration.** The app widget (`WidgetsApp`, or `MaterialApp` and `CupertinoApp` with their design starters), its title, languages, themes, splash screen and keyboard shortcuts are written in `application.yml`, not in code.
- **The platform is a profile.** `application-ios.yml` is read on iPhones only, `application-release.yml` in release builds only, and a bean marked `@Profile(['android'])` exists on Android only.
- **The app follows its lifecycle.** In the background, `@Scheduled` tasks and WebSocket connections stop; they start again when the app comes back.
- **A hot reload that changed beans restarts the context** with the new code.

## Setup

```yaml
# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  spring_boot_starter_flutter: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0   # required: it writes the application
  flutter_test:
    sdk: flutter
  spring_boot_starter_test: ^0.9.0     # springBootTest and BeanOverride, for tests
```

Then:

1. Put `@SpringBootApplication()` on `main` in `lib/main.dart`.
2. Run `dart run build_runner watch` (or `build`). The generator writes `lib/spring_gen/main.spring.dart`, with `springApplication`: the application, with every bean found under `lib/`. Keep `watch` running while you work.
3. Put configuration files and message files into `lib/resources/`. The generator embeds them into the generated code, so they need no `flutter: assets:` entry.

The Flutter packages need Flutter 3.50 or later (Dart 3.14).

The starter has no design library: it imports `package:flutter/widgets.dart` only, and an app of the default type `widgets` has neither Material nor Cupertino in its build. An app with Material or Cupertino widgets adds [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md) or [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md), and `material_ui` or `cupertino_ui`. See [Design libraries](design-libraries.md).

One import is enough. `package:spring_boot_starter_flutter/spring_boot_starter_flutter.dart` also exports `spring_core_dart`, `spring_boot_dart`, `spring_web_dart` (the HTTP clients) and `spring_boot_starter_logging`. Two names are left out because Flutter has its own: Boot's startup `Banner` (Flutter has a `Banner` widget) and the validation constraint `Size` (`dart:ui` has `Size`), which is exported as `SizeConstraint`.

## Example

A complete counter app. It uses Material's `Scaffold`, `FloatingActionButton` and `Icons`, so it adds the Material starter and `material_ui`:

```yaml
# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  material_ui: ^1.11.0
  spring_boot_starter_flutter_material: ^0.9.0   # brings spring_boot_starter_flutter
```

```dart
// lib/main.dart
import 'package:material_ui/material_ui.dart';
import 'package:spring_boot_starter_flutter_material/spring_boot_starter_flutter_material.dart';

import 'spring_gen/main.spring.dart'; // written by the generator

@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    application: () => springApplication,
    // The app widget around it is built from spring.flutter.app.*.
    home: const CounterPage(),
  ),
);

// The count is a bean, not a State: any widget or service can read and
// change it. The generated proxy notifies the listeners after every method.
@ChangeNotifierComponent()
class Counter {
  int value = 0;
  void increment() => value++;
}

// Lists the bean it needs in its type and gets it as `beans`.
class CounterPage extends SpringStatelessWidget<(Counter,)> {
  const CounterPage({super.key});

  @override
  Widget build(BuildContext context) {
    final (counter,) = beans;
    return Scaffold(
      body: const Center(child: CounterText()),
      // Only calls a method, so a tap does not rebuild the page.
      floatingActionButton: FloatingActionButton(
        onPressed: counter.increment,
        child: const Icon(Icons.add),
      ),
    );
  }
}

// Reads counter.value in build, so it rebuilds after every increment.
class CounterText extends SpringStatelessWidget<(Counter,)> {
  const CounterText({super.key});

  @override
  Widget build(BuildContext context) {
    final (counter,) = beans;
    return Text('${counter.value}');
  }
}
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    app:
      # No type: Scaffold needs a MaterialApp, and spring_boot_starter_flutter_material,
      # the one design starter, makes the app one
      title: Counter
    theme:
      seed-color: deepPurple
```

## Running it

```bash
dart run build_runner watch   # writes lib/spring_gen/main.spring.dart
flutter run
```

What happens at the start:

- `SpringApplicationWidget` shows the splash, reads the configuration files, adds the platform's and the build's profiles, loads the fonts among the assets and creates the beans.
- It checks that every bean a Spring widget needs exists, so a missing bean fails the start instead of a later build.
- Once the context is ready it builds the app widget from `spring.flutter.app.*` and the theme from `spring.flutter.theme.*`, and shows `home`.
- Logging is on from the start, in Spring Boot's format, to the console and to an in-memory `LogBuffer` bean:

```text
INFO 82749 --- [main] spring_boot_dart.SpringApplication : The following 3 profiles are active: "desktop", "macos", "debug"
```

## What is inside

Getting started:

- [Configuration in a Flutter app](configuration.md): files, platform and build profiles, imports, `--dart-define`, remote files.
- [SpringApplicationWidget](application-widget.md): the root widget that starts the application.
- [The app widget](app-widget.md): `WidgetsApp`, `MaterialApp` or `CupertinoApp` from `spring.flutter.app.*`.
- [Design libraries](design-libraries.md): an app without a design library, and Material or Cupertino with their starters.

Beans and state:

- [Beans in widgets](beans-in-widgets.md): `SpringStatelessWidget`, `SpringStatefulWidget`, `context.bean` and `@BuildContextAccess`.
- [State beans](state-beans.md): `@ChangeNotifierComponent` and `@NotifyListeners`.
- [Messages and languages](messages.md): `context.message`, typed `context.messages` and the app's locales.
- [The app lifecycle](lifecycle.md): lifecycle events and the pause in the background.
- [Hot reload](hot-reload.md): when the context restarts and when it stays.

Themes:

- [Themes](themes/index.md): the whole look of the app in YAML, with its own pages for colors, typography, components, states, motion, backgrounds, images, loaders and Cupertino.

The start and tools:

- [The splash and the start](splash.md): stages, splash tasks, frames during the start, font warm-up, tracing.
- [Keyboard shortcuts and taps](shortcuts.md): actions bound to keys or tap patterns in the configuration.
- [The debug panel](debug-panel.md): logs, frames, configuration, beans, themes and the start of the running app.
- [The frame meter](frame-meter.md): the frames a second the app really draws.

Content and files:

- [MarkdownView](markdown.md): GitHub Markdown with the theme's colors, tables, code blocks and callouts.
- [Assets and fonts](assets-and-fonts.md): `asset:` resources and fonts loaded from the assets.
- [Files of the app](files.md): `FileTemplate` for the app's own files.
- [SQLite databases](sqlite.md): databases in the app's directory, on an isolate of their own.

Platforms:

- [The desktop window](desktop-window.md): title, title bar and sizes of the window.
- [The web](web.md): the page around the app, the page loader, the dev server, fonts, assets and WebAssembly.
- [SEO](seo.md): a page per address for search engines and link previews, the sitemap and llms.txt.

Reference:

- [Testing](testing.md): `springBootTest` under `flutter_test`, fakes and goldens.
- [All properties](properties.md): every key of the starter.
- [Differences from Spring](differences.md): what works differently than in Spring Boot.
- [Moving to 0.8](moving-to-0-8.md): Flutter 3.50, the design starters and what changed for an app.

## In Spring (Java)

Spring has no widget tree. The nearest thing to `SpringApplicationWidget` is the `main` method of a Spring Boot app:

```java
@SpringBootApplication
class ShopApplication {
  public static void main(String[] args) {
    SpringApplication.run(ShopApplication.class, args);
  }
}
```

Differences that matter:

- `@SpringBootApplication()` goes on the `main` function, and the generator writes the application at build time. Run `build_runner` after you change annotations.
- Widgets are not beans: Flutter creates them. They receive beans through their type (`SpringStatelessWidget<(Basket,)>`) instead of injection.
- The platform and the build mode are active profiles by themselves.
- The full list is on [Differences from Spring](differences.md).

## See also

- [spring_core_dart](../spring-core-dart/index.md)
- [Configuration](../spring-core-dart/config/index.md)
- [The generator for Flutter](../spring-core-dart-generator/flutter/index.md)
- [spring_boot_starter_flutter_material](../spring-boot-starter-flutter-material/index.md)
- [spring_boot_starter_flutter_cupertino](../spring-boot-starter-flutter-cupertino/index.md)
- [spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md)
- [spring_boot_starter_flutter_security](../spring-boot-starter-flutter-security/index.md)
- [What a build contains](optimizations.md)
