spring_boot_dart

spring_boot_dart is the part of Spring for Dart that starts an application. It is the Dart port of Spring Boot's SpringApplication, its external configuration, its @ConfigurationProperties binding and its auto-configuration.

With spring_core_dart alone you have a container of beans, but you still write the start yourself: read the config files, create the context, set the log levels, run the start-up work. spring_boot_dart does all of it from one annotation on main.

Why

Every application needs the same start-up code, and it is easy to get wrong:

spring_boot_dart gives you all of this with Spring Boot's names and rules, so configuration and habits from a Spring project carry over. It works the same in a server, a command-line tool and a Flutter app, on the Dart VM, in AOT builds and on the web.

Setup

# pubspec.yaml
dependencies:
  spring_boot_dart: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0   # required: it scans the package

spring_boot_dart exports spring_core_dart, so one import is enough. It depends on nothing else. Most applications do not add it directly: every starter (spring_boot_starter_web, spring_boot_starter_flutter, ...) depends on it and exports it.

Example

A complete application with typed settings, a start-up task and a profile.

// bin/main.dart
import 'package:spring_boot_dart/spring_boot_dart.dart';

import 'spring_gen/main.spring.dart'; // written by build_runner

// Every key under shop.* in one typed, validated object.
@ConfigurationProperties('shop')
@Validated()
class ShopProperties {
  @NotBlank()
  String name = 'NEON Books';

  Duration deliveryTime = const Duration(days: 3); // shop.delivery-time=2d

  @Min(1)
  int maxBasketSize = 10; // shop.max-basket-size
}

// Runs once the application has started.
@Component()
@Log()
class Greeting implements ApplicationRunner {
  Greeting(this.shop);

  final ShopProperties shop;

  @override
  void run(ApplicationArguments args) =>
      log.info('${shop.name} is open, ${shop.maxBasketSize} books per basket');
}

@SpringBootApplication()
void main(List<String> args) => runApplication(args);
# lib/resources/application.yml
spring:
  application:
    name: neon-books
shop:
  max-basket-size: 20
logging:
  level:
    root: info
# lib/resources/application-prod.yml: read only with the prod profile
shop:
  max-basket-size: 50

Running it

dart run build_runner build          # writes bin/spring_gen/main.spring.dart
dart run bin/main.dart               # max-basket-size 20
dart run bin/main.dart --spring.profiles.active=prod   # 50
SHOP_MAXBASKETSIZE=30 dart run bin/main.dart           # 30: the environment wins over the files

The start logs, at INFO:

Starting neon-books using Dart 3.13.5 with PID 4242
No active profile set, falling back to 1 default profile: "default"
Started neon-books in 0.07 seconds
NEON Books is open, 20 books per basket

With shop.max-basket-size=0 the application does not start. It prints a report that names the key:

***************************
APPLICATION FAILED TO START
***************************

Description:

Binding to target properties under 'shop' failed:

  - shop.max-basket-size: must be greater than or equal to 1 (was "0")

Action:

Update the application's configuration (lib/resources/application.properties, command line or environment).

How it works

Dart has no reflection at run time, so the scan happens at build time. dart run build_runner build reads the whole package (lib/ and the directory of main; there is no @ComponentScan to write) and generates spring_gen/main.spring.dart with:

runApplication(args) then does what Spring Boot's SpringApplication.run does. The steps are on SpringApplication.

What is inside

Starting:

External configuration:

Auto-configuration:

Reference:

In Spring (Java)

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

Differences that matter:

See also