
# Spring for Dart

Spring for Dart brings the programming model of Spring Framework and Spring Boot, the Java frameworks, to Dart and Flutter. You write plain classes and mark them with annotations such as `@Service()` or `@GetMapping('/books')`. The framework creates the objects, connects them, configures them from `application.properties` or `application.yml`, and runs the application.

Dart has no runtime reflection on Flutter, on the web or in AOT executables. So the annotations are read at build time: `spring_core_dart_generator`, a `build_runner` builder, writes plain Dart code that creates your objects, routes your requests and applies your aspects. The same application runs with `dart run`, as a compiled executable, in a Flutter app and in the browser.

## What it is good at

- **Wiring.** A class asks for what it needs in its constructor. The container builds the whole graph in the right order, and a missing or ambiguous dependency stops the start with a message that names the class and the parameter. See [Inversion of control and dependency injection](inversion-of-control.md).
- **Configuration.** Settings come from files, environment variables and the command line, with profiles (`dev`, `prod`, `test`) on top. A group of settings is bound into a typed class and checked at startup.
- **Ready-made features.** Starters add a web server, HTTP clients, a cache, scheduled tasks, security, logging or database access when you add them to `pubspec.yaml`, with sensible defaults you can replace one bean at a time. See [The starters](starters.md).
- **One context for everything.** The beans of your code and of every starter live in one application context, so the starters work together without glue code. See [One context for all starters](shared-context.md).
- **Tests.** Any bean can be replaced by a fake in a test, and the test starts the real application around it.
- **Checks early.** Many mistakes are found by the generator, before the application runs: an invalid pointcut, a validation constraint on a type it cannot check, a Flutter asset missing from `pubspec.yaml`. Others are found at startup, before the first request: a placeholder whose property is not set and has no default, two handlers for one route, a missing bean, a bean cycle.

## Who it is for

- **Servers.** REST APIs, WebSocket servers and backends for Flutter apps, with `spring_boot_starter_web`.
- **Flutter apps.** State and services in beans, handed to widgets; themes, texts and app settings in configuration files; platform profiles (`android`, `ios`, `web`, ...), with `spring_boot_starter_flutter`.
- **Command-line tools.** Configuration, logging and start-up tasks for a CLI, with `spring_boot_starter_logging`.

You do not need to know Java or Spring. These pages explain every idea from the start. If you do know Spring, most annotations and property names are the ones you know; each package page lists the differences.

## Get started in 5 minutes

A web server with one service and one endpoint.

**1. Create a package** and set its dependencies in `pubspec.yaml`. The web starter brings everything else it needs (the core, Spring Boot, logging); the generator and `build_runner` are only used at build time.

```yaml
# pubspec.yaml
name: hello
environment:
  sdk: ^3.13.0

dependencies:
  spring_boot_starter_web: ^0.9.0

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

**2. Write the application** in `bin/main.dart`. Everything in `lib/` and in the directory of `main` is scanned; there is no list of classes to keep up to date.

```dart
// bin/main.dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

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

// A bean: the container creates one Greeter and passes it where needed.
// The name comes from the configuration, "World" when it is not set.
@Service()
class Greeter {
  Greeter(@Value(r'${greeting.name:World}') this.name);

  final String name;

  String greet() => 'Hello, $name!';
}

// GET /hello answers with the greeting.
@RestController()
class HelloController {
  HelloController(this.greeter); // injected by type

  final Greeter greeter;

  @GetMapping('/hello')
  String hello() => greeter.greet();
}

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

`r'${greeting.name:World}'` is a raw string: `${...}` is Spring's placeholder, not Dart's interpolation.

**3. Add a setting** in `lib/resources/application.properties`:

```properties
greeting.name=Dart
```

**4. Generate the code and run it:**

```bash
dart pub get
dart run build_runner build      # writes bin/spring_gen/main.spring.dart
dart run bin/main.dart
```

```bash
curl localhost:8080/hello
# Hello, Dart!
```

Settings can be overridden without touching the file: `dart run bin/main.dart --greeting.name=Ada`, or `GREETING_NAME=Ada dart run bin/main.dart`.

Run `build_runner` again after you add or change annotations, or keep `dart run build_runner watch` running.

## These pages

| Page | What it explains |
|---|---|
| [Inversion of control and dependency injection](inversion-of-control.md) | The core idea: the container creates and wires your objects. Beans, injection, configuration, lifecycle, scopes and tests. |
| [Comparisons](../compare/index.md) | Small side-by-side examples: get_it and dependency injection, the Observer pattern, logic around a method, HTTP clients. |
| [The starters](starters.md) | A tour of every package and what adding it gives you. |
| [One context for all starters](shared-context.md) | How starters are found, how they use each other's beans, and how your own beans replace theirs. |
| [Your own starter](your-own-starter.md) | Writing a package that adds beans to every application that depends on it. |

## The packages

| Package | What it is | Documentation |
|---|---|---|
| `spring_core_dart` | The container: beans, configuration, profiles, events, validation, JSON, AOP | [spring_core_dart](../components/spring-core-dart/index.md) |
| `spring_core_dart_generator` | The `build_runner` builder that reads the annotations and writes the code | [spring_core_dart_generator](../components/spring-core-dart-generator/index.md) |
| `spring_boot_dart` | Starts an application from `@SpringBootApplication`, reads the configuration, adds the starters | [spring_boot_dart](../components/spring-boot-dart/index.md) |
| `spring_boot_starter_web` | An HTTP server with `@RestController` classes | [spring_boot_starter_web](../components/spring-boot-starter-web/index.md) |
| Other packages | WebSocket, data, cache, scheduling, Feign, security, OAuth 2.0 client, actuator, logging, test, Flutter, navigation, Flutter security, search, and the libraries they build on | [The starters](starters.md) |

An application lists the starters it uses, and nothing they bring: a web server lists `spring_boot_starter_web` alone, and gets `spring_core_dart` and `spring_boot_dart` through it.

## In Spring (Java)

The ideas are the same as in Spring: beans, the application context, auto-configuration, starters, profiles, `@ConfigurationProperties`. What differs comes from Dart:

- The scanning happens at build time. After you change annotations, run `build_runner` again.
- `@SpringBootApplication()` goes on the `main` function, not on a class.
- `lib/resources/` plays the role of Java's resources folder: `application.properties` and other files there are embedded in the build.
- Annotations are constructor calls, so they have parentheses: `@Service()`, not `@Service`.
