
# The starters

A **starter** is a package that adds a feature to your application when you add it to `pubspec.yaml`: a web server, a cache, scheduled tasks, security. It brings ready-made beans with defaults, configured by properties, and each of them steps aside when you declare your own bean of the same type. Run `dart run build_runner build` after adding one: the generator finds it and adds its beans (see [One context for all starters](shared-context.md)).

## One dependency per feature

A starter brings and re-exports the packages it is built on, so one import of the starter gives you its feature, Spring's annotations, `@SpringBootApplication` and the logger. A web server lists `spring_boot_starter_web` alone, not `spring_core_dart`, `spring_boot_dart` or the logging starter it brings.

The rules:

1. **List every starter whose feature your code uses**, even when another starter brings it. The security starter brings the web starter, but a server with controllers lists both: what a starter depends on may change between versions.
2. **Do not list a package only because a starter brings it.**
3. **Tests take `spring_boot_starter_test`** as a dev dependency, and every application takes `build_runner` and `spring_core_dart_generator` as dev dependencies.

```yaml
# A server with a REST API, a cache and scheduled tasks.
dependencies:
  spring_boot_starter_web: ^0.9.0
  spring_boot_starter_cache: ^0.9.0
  spring_boot_starter_scheduling: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
  spring_boot_starter_test: ^0.9.0
  test: ^1.33.0
```

No starter needs an `@Enable...` annotation: there is no `@EnableCaching`, `@EnableScheduling` or `@EnableFeignClients`. Listing the dependency switches the feature on.

## Core

### spring_core_dart

The container: beans and their injection, configuration and profiles, events, messages, resources, type conversion, SpEL (an expression language), validation, JSON with the `ObjectMapper`, and AOP (code that runs around the methods of other beans). Every other package builds on it. It depends only on the Dart team's `package:yaml`.

```yaml
spring_core_dart: ^0.9.0
```

Use it directly only without Spring Boot, starting the context yourself with `ApplicationContext.run`. Documentation: [spring_core_dart](../components/spring-core-dart/index.md).

### spring_boot_dart

Starts an application from `@SpringBootApplication()` on `main`: reads `application.properties` or `application.yml` with profiles, environment variables and arguments; creates the context with your beans and those of every starter; binds `@ConfigurationProperties`; runs `ApplicationRunner` and `CommandLineRunner` beans; and explains a failed start. It adds the `ObjectMapper` bean, validation and the `messageSource`.

```yaml
spring_boot_dart: ^0.9.0
```

```dart
@SpringBootApplication()
void main(List<String> args) => runApplication(args);
```

Every starter brings it, so applications rarely list it. Documentation: [spring_boot_dart](../components/spring-boot-dart/index.md).

### spring_core_dart_generator

The `build_runner` builder. It reads the annotations and writes the `*.spring.dart` files: bean definitions, routes, AOP proxies, the embedded resources of `lib/resources/`, the list of starters. It also checks the code at build time and writes metadata that editors use to complete property names. A dev dependency of every application and every starter.

```yaml
dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
```

Documentation: [spring_core_dart_generator](../components/spring-core-dart-generator/index.md).

## Server

### spring_boot_starter_web

An HTTP server (Spring MVC): `@RestController` classes served by `dart:io`'s `HttpServer`, JSON bodies, `@Valid` request bodies, errors as `ProblemDetail`, server-sent events, uploads and downloads, static files, filters, CORS, sessions, and `server.*` properties. It also runs inside a Flutter app on mobile or desktop, as a local server.

```yaml
spring_boot_starter_web: ^0.9.0
```

```dart
@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books);

  final BookService books;

  @GetMapping('/{isbn}')
  Book find(@PathVariable() String isbn) =>
      books.find(isbn) ??
      (throw ResponseStatusException(HttpStatus.notFound, 'No book $isbn'));
}
```

Documentation: [spring_boot_starter_web](../components/spring-boot-starter-web/index.md).

### spring_boot_starter_websocket

WebSocket clients and endpoints. A client is an abstract class with `@WebSocketClient`: the generator implements it, with JSON messages, one shared connection opened on demand and reconnection. With the web starter, `@WebSocketEndpoint` beans answer on the same port.

```yaml
spring_boot_starter_websocket: ^0.9.0
```

```dart
@WebSocketClient('chat', url: r'${chat.url}')
abstract interface class ChatSocket {
  @OnMessage()
  Stream<ChatMessage> messages();         // incoming messages, read from JSON

  @SendMessage()
  Future<void> send(ChatMessage message); // sent as JSON
}
```

Documentation: [spring_boot_starter_websocket](../components/spring-boot-starter-websocket/index.md), and [WebSocket](../components/spring-boot-starter-web/server/websocket.md) for endpoints on the web starter.

### spring_boot_starter_data

Spring Data on Spring Data JDBC's model: `@Table` classes, repository interfaces the generator implements (CRUD, paging and sorting, derived queries such as `findByTitleContainingIgnoreCase`, `@Query` with SQL), `@Transactional`, optimistic locking, `JdbcTemplate`, migrations. In memory by default, or on SQLite and PostgreSQL from `spring.datasource.*`; the driver (`sqlite3`, `postgres`) is the application's own dependency.

```yaml
spring_boot_starter_data: ^0.9.0
```

```dart
@Table('books')
class Book {
  Book({this.id, required this.title, this.year});

  @Id()
  int? id;
  String title;
  int? year;
}

// No implementation to write: the generator writes it.
abstract interface class BookRepository implements ListCrudRepository<Book, int> {
  Future<List<Book>> findByTitleContainingIgnoreCase(String text);
}
```

Documentation: [spring_boot_starter_data](../components/spring-boot-starter-data/index.md), and [Data: entities, repositories, queries](../components/spring-core-dart-generator/data.md) for what the generator writes.

### spring_boot_starter_cache

Caching of method results with `@Cacheable`, `@CachePut`, `@CacheEvict` and `@Caching`, for sync and async methods, with keys and conditions in SpEL. An in-memory `CacheManager` with time-to-live and size limits from `spring.cache.*`.

```yaml
spring_boot_starter_cache: ^0.9.0
```

```dart
@Service()
class Books {
  Books(this.api);

  final CatalogApi api;

  // The API is called once per isbn; later calls read the cache.
  @Cacheable('books')
  Future<Book> find(String isbn) => api.load(isbn);

  @CacheEvict('books', key: '#isbn')
  Future<void> delete(String isbn) => api.delete(isbn);
}
```

Documentation: [spring_boot_starter_cache](../components/spring-boot-starter-cache/index.md).

### spring_boot_starter_scheduling

`@Scheduled` methods that run at a fixed rate, with a fixed delay, or on a cron expression (which can come from properties), and a `TaskScheduler` bean. The tasks stop when the application closes, and pause while a Flutter app is in the background.

```yaml
spring_boot_starter_scheduling: ^0.9.0
```

```dart
@Component()
class Reports {
  Reports(this.repository);

  final ReportRepository repository;

  @Scheduled(fixedRate: Duration(minutes: 5))
  void refreshCache() => repository.refresh();

  @Scheduled(cron: '0 0 9 * * MON-FRI') // 9:00 on working days
  void morningDigest() => repository.sendDigest();
}
```

Documentation: [spring_boot_starter_scheduling](../components/spring-boot-starter-scheduling/index.md).

### spring_boot_starter_feign

HTTP clients without HTTP code: an abstract class with `@FeignClient` and mapping annotations becomes an injectable client. JSON through the application's `ObjectMapper`, interceptors, retries, fallbacks, per-client settings in `spring.feign.client.config.*`. Works on the VM, in Flutter and on the web.

```yaml
spring_boot_starter_feign: ^0.9.0
```

```dart
@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogClient {
  @GetMapping('/books/{isbn}')
  Future<Book> find(@PathVariable() String isbn);

  @PostMapping('/books')
  Future<ResponseEntity<Book>> create(@RequestBody() Book book);
}
```

Documentation: [spring_boot_starter_feign](../components/spring-boot-starter-feign/index.md).

### spring_boot_starter_security

Security for the web starter, secure by default: with the dependency listed and nothing configured, every request needs a login. A `SecurityFilterChain` bean, built with `HttpSecurity`, sets the rules: HTTP Basic, form login, single sign-on with OAuth 2.0 / OpenID Connect (`oauth2Login()`), JWT resource servers, sessions, CSRF, CORS and security headers. It brings `spring_security_core` (users, password hashing, `@PreAuthorize` on bean methods) and the OAuth 2.0 client.

```yaml
spring_boot_starter_web: ^0.9.0
spring_boot_starter_security: ^0.9.0
```

```dart
@Configuration()
class SecurityConfig {
  @Bean()
  SecurityFilterChain filterChain(HttpSecurity http) => http
      .authorizeHttpRequests((auth) => auth
          .requestMatchers('/public/**').permitAll()
          .requestMatchers('/api/admin/**').hasRole('ADMIN')
          .anyRequest().authenticated())
      .formLogin()
      .httpBasic()
      .build();
}
```

Documentation: [spring_boot_starter_security](../components/spring-boot-starter-security/index.md).

### spring_boot_starter_oauth2_client

Spring Security's OAuth 2.0 / OpenID Connect client, from Spring Boot's `spring.security.oauth2.client.*` properties: registrations (Google, GitHub, Facebook, Okta built in, any provider by its issuer), the token requests of the authorization code (with PKCE), client credentials and refresh grants, tokens refreshed before they expire, and the token on every Feign call. The security starter's `oauth2Login()` and the Flutter app login build on it.

```yaml
spring_boot_starter_oauth2_client: ^0.9.0
```

```properties
spring.security.oauth2.client.registration.partner.client-id=shop
spring.security.oauth2.client.registration.partner.client-secret=${PARTNER_SECRET}
spring.security.oauth2.client.registration.partner.authorization-grant-type=client_credentials
spring.security.oauth2.client.provider.partner.token-uri=https://id.partner.example/oauth2/token

# Every Feign call carries the token (with spring_boot_starter_feign).
spring.feign.oauth2.enabled=true
spring.feign.oauth2.client-registration-id=partner
```

Documentation: [spring_boot_starter_oauth2_client](../components/spring-boot-starter-oauth2-client/index.md).

### spring_boot_starter_actuator

Spring Boot Actuator's endpoints over HTTP, under `/actuator`: the health report (with every `HealthIndicator` bean), the info and the mappings, with Spring Boot's names, properties and JSON. It brings the web starter and `spring_boot_actuator`, the endpoints without HTTP that other libraries build on.

```yaml
spring_boot_starter_actuator: ^0.9.0
```

```properties
management.endpoints.web.exposure.include=health,info,mappings
management.endpoint.health.show-details=always
```

Documentation: [spring_boot_starter_actuator](../components/spring-boot-actuator/index.md).

### spring_boot_starter_logging

Where log lines go: the console with Spring Boot's patterns and colours, log files with rollover, levels from `logging.level.*`, and an in-memory `LogBuffer` for a log screen in an app. Every feature starter brings it, so a command-line tool lists it and nothing else.

```yaml
spring_boot_starter_logging: ^0.9.0
```

```dart
// A logger for this file, named `checkout`.
const log = SpringLog('checkout');

@Service()
class Checkout {
  void pay(int order, double amount) =>
      log.info('paid $amount', fields: {'order': order});
}
```

```properties
logging.level.checkout=debug
logging.file.name=logs/shop.log
```

Documentation: [spring_boot_starter_logging](../components/spring-boot-starter-logging/index.md), and [Logging](../components/spring-core-dart/logging/index.md) for the `SpringLog` API.

### spring_boot_starter_test

Tests, as a dev dependency: `springBootTest` starts the real application (Spring's `@SpringBootTest`), `BeanOverride` replaces beans with fakes, `MockMvc` tests the web layer in memory, `ApplicationContextRunner` tests a starter's auto-configuration, plus bean matchers, `captureLogs`, and containers (`PostgresContainer`, any Docker image) for integration tests. Works with `package:test` and `flutter_test`.

```yaml
dev_dependencies:
  spring_boot_starter_test: ^0.9.0
```

```dart
final app = springBootTest(
  springApplication,
  profiles: ['test'],
  overrides: [BeanOverride<PaymentGateway>(FakeGateway())],
);
```

Documentation: [spring_boot_starter_test](../components/spring-boot-starter-test/index.md), [Testing the web layer](../components/spring-boot-starter-web/testing.md), and [Tests: @SpringBootTest and @DataTest](../components/spring-core-dart-generator/tests.md).

## Flutter

### spring_boot_starter_flutter

Spring Boot in Flutter apps. `SpringApplicationWidget` starts the application and hands its beans to the widgets. The app widget, its themes, fonts and languages come from configuration files; the platform is a profile (`android`, `ios`, `mobile`, `desktop`, `web`, ...); and the app's lifecycle pauses and resumes scheduled tasks and sockets. Its only platform code is on the desktops, for the window's title bar and size from `spring.flutter.desktop.window.*`.

It knows no design library: it imports `package:flutter/widgets.dart` only, so an app of `spring.flutter.app.type: widgets` (a `WidgetsApp`, the type when no design starter is in the application) has neither Material nor Cupertino in its build. The two design starters below add them, and the one listed sets the type: `spring.flutter.app.type` is only set to choose (both design starters, per platform in profiles, or `widgets` kept on purpose). It needs Flutter 3.50 or later (Dart 3.14).

```yaml
flutter:
  sdk: flutter
spring_boot_starter_flutter: ^0.9.0
```

```dart
@SpringBootApplication()
void main() => runApp(
  SpringApplicationWidget(
    application: () => springApplication,
    home: const CounterPage(),
  ),
);

// State in a bean: listeners are notified after every method call.
@ChangeNotifierComponent()
class Counter {
  int value = 0;
  void increment() => value++;
}

// Lists the beans it needs in its type, and rebuilds when they change.
class CounterPage extends SpringStatelessWidget<(Counter,)> {
  const CounterPage({super.key});

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

Documentation: [spring_boot_starter_flutter](../components/spring-boot-starter-flutter/index.md), and [Flutter](../components/spring-core-dart-generator/flutter/index.md) for what the generator writes for apps.

### spring_boot_starter_flutter_material

Material Design for Flutter apps, on the Flutter team's `material_ui` (since Flutter 3.50, Material is no longer part of the SDK). In the dependencies, it makes the app a `MaterialApp` (`spring.flutter.app.type: material`, deduced when it is the one design starter), every theme of `spring.flutter.theme.*` becomes Material's `ThemeData` with its component themes, and `seed-color` makes a Material 3 palette. It brings the Flutter starter; the app lists `material_ui` too, for the widgets it uses.

```yaml
material_ui: ^1.11.0
spring_boot_starter_flutter_material: ^0.9.0
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      seed-color: teal
```

Documentation: [spring_boot_starter_flutter_material](../components/spring-boot-starter-flutter-material/index.md).

### spring_boot_starter_flutter_cupertino

The iOS look for Flutter apps, on the Flutter team's `cupertino_ui`, without Material. In the dependencies, it makes the app a `CupertinoApp` (`spring.flutter.app.type: cupertino`, deduced when it is the one design starter; with both design starters, the type is set per platform), the themes become `CupertinoThemeData`, and `seed-color` makes the same Material 3 palette a Material app has. It brings the Flutter starter; the app lists `cupertino_ui` too, for the widgets it uses.

```yaml
cupertino_ui: ^1.1.6
spring_boot_starter_flutter_cupertino: ^0.9.0
```

```yaml
# lib/resources/application.yml
spring:
  flutter:
    theme:
      seed-color: teal
```

Documentation: [spring_boot_starter_flutter_cupertino](../components/spring-boot-starter-flutter-cupertino/index.md).

### spring_boot_starter_flutter_navigation

Screens on routes, on the SDK's `Router` (the browser's address bar, deep links, Android's back button), without `go_router`. `@ScreenRoute` on a widget, Spring's path patterns, shells with tabs, typed route constants generated per screen, and route filters. It brings the Flutter starter.

```yaml
spring_boot_starter_flutter_navigation: ^0.9.0
```

```dart
@ScreenRoute('/catalog/books/{isbn}', title: 'Book')
class BookPage extends StatelessWidget {
  const BookPage({super.key});

  @override
  Widget build(BuildContext context) =>
      Text(context.route.get(BookPageRoute.isbn)); // a generated constant
}
```

Documentation: [spring_boot_starter_flutter_navigation](../components/spring-boot-starter-flutter-navigation/index.md).

### spring_boot_starter_flutter_scene

3D scenes for Flutter apps, on `flutter_scene` (WebGL2 in a browser, Impeller elsewhere). `SpringSceneView` is a scene among the app's widgets, `SceneBackdrop` a scene behind one; where scenes do not draw (turned off, no WebGL2, the engine failed) they are plain widgets over their placeholders. The ceiling on frames, the models (`spring.flutter.scene.models.*`) and the application's scene come from properties, and the debug panel has a tab with every scene and model by name. It brings the Flutter starter; the app lists `flutter_scene` too, for the engine's scene widgets it uses.

```yaml
spring_boot_starter_flutter_scene: ^0.9.0
flutter_scene: ^0.24.3
```

```dart
SpringSceneView.declarative(
  name: 'showroom',
  placeholder: const ShowroomPicture(),   // until it draws, or where it cannot
  children: [SpringSceneModel('hero')],   // spring.flutter.scene.models.hero
)
```

Documentation: [spring_boot_starter_flutter_scene](../components/spring-boot-starter-flutter-scene/index.md).

### spring_boot_starter_flutter_signals

Reactive state in the beans of Flutter apps: `@Signal()` on a field of a component (what read it is told when it is assigned), `@Computed()` on a getter (a value kept until what it read changes, also from a `Future` or a `Stream` with its state), `@Effect()` on a method (run again when what it read changes). The fields stay plain fields, and a widget is built again only for the fields its `build` read. It is built on the third-party package `signals_core` and stands beside `@ChangeNotifierComponent`, not instead of it. It brings the Flutter starter.

```yaml
spring_boot_starter_flutter_signals: ^0.9.0
```

```dart
@Component()
class Basket {
  @Signal()
  List<Book> items = [];

  @Signal()
  String? coupon;

  @Computed()                        // kept until items or coupon changes
  double get total =>
      items.fold(0.0, (sum, book) => sum + book.price) *
      (coupon == null ? 1 : 0.9);

  void add(Book book) => items.add(book);
}
```

Documentation: [spring_boot_starter_flutter_signals](../components/spring-boot-starter-flutter-signals/index.md).

### spring_boot_starter_flutter_security

Security for Flutter apps, a plugin with platform code: the app login with OAuth 2.0 / OpenID Connect (`OAuth2LoginService`, authorization code with PKCE), secrets in the Keychain, the Android Keystore and the other platforms' secure stores, the system's login window, and widgets that follow the logged-in user (`context.principal`). It brings the Flutter starter, the navigation starter, the OAuth 2.0 client and `spring_security_core`, so an app with a login lists it alone.

```yaml
flutter:
  sdk: flutter
spring_boot_starter_flutter_security: ^0.9.0
```

```dart
@Service()
class Account {
  Account(this._login);

  final OAuth2LoginService _login;

  Future<void> start() => _login.restore();          // logged in from last time?
  Future<void> signIn() => _login.login('keycloak'); // the login window
  Future<void> signOut() => _login.logout();         // revoke, forget
}
```

Documentation: [spring_boot_starter_flutter_security](../components/spring-boot-starter-flutter-security/index.md).

## Search

### spring_search_dart

Full-text search inside the application, on the VM, in Flutter and on the web, in pure Dart: documents from Markdown files or from any bean, analyzers per language, BM25 ranking, prefixes, typos, phrases and highlighted snippets, through the `SearchService` bean. It depends on `spring_boot_dart` only.

It is not on pub.dev yet: take it from the framework's git repository.

```yaml
spring_search_dart:
  git:
    url: https://github.com/farum-azula/spring_core_dart.git
    path: spring_search_dart
```

```yaml
# lib/resources/application.yml
spring:
  search:
    markdown:
      - location: resources:content/**/*.md
        link: /docs/{path}
```

Documentation: [spring_search_dart](../components/spring-search-dart/index.md).

## Supabase

### spring_boot_starter_supabase

[Supabase](https://supabase.com) on a server and in Flutter apps, with a client of its own: the project's database through Spring Data repositories (its REST API, or SQL with `spring.supabase.db.url`), Auth through Spring Security, Realtime as streams, Storage as a template and declared buckets, Edge Functions as declared interfaces. It brings the data, cache, Feign and WebSocket starters and `spring_security_core`.

```yaml
spring_boot_starter_supabase: ^0.9.0
```

```yaml
# lib/resources/application.yml
spring:
  supabase:
    url: https://abcd.supabase.co
    anon-key: ${SUPABASE_ANON_KEY}
```

```dart
abstract interface class Todos implements ListCrudRepository<Todo, int> {
  Future<List<Todo>> findByDoneOrderByCreatedAtDesc(bool done);
}
```

Documentation: [spring_boot_starter_supabase](../components/spring-boot-starter-supabase/index.md).

## Edge

### spring_boot_starter_edge

The same application as a **function**: on Supabase Edge Functions, Cloudflare Workers, AWS Lambda, Deno Deploy, Netlify Edge Functions and Vercel Functions. It is compiled to JavaScript (or WebAssembly) and answers through the platform's fetch API instead of a socket; controllers, filters, Spring Security, Feign clients and the other starters are those of a server. It brings and exports the web starter.

```yaml
spring_boot_starter_edge: ^0.9.0
```

```dart
@SpringBootApplication()
void main() => runFetchApplication(() => springApplication);
```

```bash
dart run build_runner build
dart run spring_boot_starter_edge:build --platform supabase --name api
```

Documentation: [spring_boot_starter_edge](../components/spring-boot-starter-edge/index.md).

## Libraries the starters bring

Three packages are libraries rather than starters. Applications get them through a starter and rarely list them:

| Package | What it holds | Brought by |
|---|---|---|
| `spring_web_dart` | The HTTP vocabulary of servers and clients: the mapping annotations, `ResponseEntity`, `ProblemDetail`, `HttpHeaders`, HTTP and WebSocket client transports. See [spring_web_dart](../components/spring-web-dart/index.md) | The web, WebSocket, Feign, OAuth 2.0 client, actuator, test and Flutter packages |
| `spring_security_core` | Users, password hashing, `AuthenticationManager`, `@PreAuthorize` and the other method-security annotations. See [spring_security_core](../components/spring-security-core/index.md) | The security, OAuth 2.0 client and Flutter security packages |
| `spring_boot_actuator` | The actuator's endpoints and health model, without HTTP. See [Actuator](../components/spring-boot-actuator/index.md) | The actuator, data and security starters; the data starter's `db` health indicator builds on it |

The design libraries of the Flutter team are the other way round. The design starters do not re-export them, so an app lists `material_ui` next to `spring_boot_starter_flutter_material`, or `cupertino_ui` next to `spring_boot_starter_flutter_cupertino`, for the widgets it uses.

## Your own

Any package can be a starter: a `lib/spring_auto_configuration.dart` file is all it takes for the generator to find it. See [Your own starter](your-own-starter.md).

## See also

- [One context for all starters](shared-context.md)
- [Auto-configurations](../components/spring-core-dart-generator/auto-configurations.md)
