
# Routes in Dart configuration

The routes can also be declared in code: a `ScreenRoutes` bean, built with `ScreenRoutes.route()`. It is the same model as `@ScreenRoute` and `@RouteShell`, in the form of Spring WebFlux's `RouterFunctions`. Any number of such beans and the annotated screens are merged, and checked together at the start.

## Why

Annotations suit screens that own their address. Code suits routes built from data (a screen per feature flag), routes kept in one place for review, or screens of a library the app cannot annotate. Both forms share the same checks: a path declared twice stops the start and names both places.

## Example

```dart
@Configuration()
class AppRoutes {
  @Bean()
  ScreenRoutes routes() => ScreenRoutes.route()
      .shell((shell) => MainTabs(shell), (tabs) => tabs
          .branch('/catalog', (b) => b
              .screen('/catalog', (r) => const CatalogPage())
              .screen('/catalog/books/{isbn}', (r) => const BookPage()))
          .branch('/profile', (b) => b
              .screen('/profile', (r) => const ProfilePage())))
      .screen('/checkout', (r) => const CheckoutPage(),
          transition: PageTransition.fade)
      .nest((admin) => admin
          .screen('/admin', (r) => const AdminPage())
          .filter(AdminOnly()))                // for the routes of this nest only
      .redirect('/', '/catalog')
      .notFound((r) => const NotFoundPage())
      .build();
}
```

## The builder

| Method | Meaning |
|---|---|
| `screen(path, builder, {name, title, params, extra, shell, branch, transition, attributes, content, link})` | A screen at `path`, built by `builder`. The named arguments are those of `@ScreenRoute` and `@RouteInfo(link:)` |
| `shell(builder, branches, {key})` | A shell built by `builder` (it gets the `ShellState`); `branches` declares its branches. `key` names it, so a screen's `shell:` can refer to it |
| `branch(path, screens)` | Inside `shell`: a branch starting at `path`, with the screens `screens` declares |
| `nest(nested)` | The routes `nested` declares; its filters apply to them only |
| `filter(filter)` | A `RouteFilter` for every screen of this builder |
| `redirect(from, to)` | Sends the address `from` to `to` |
| `notFound(builder)` | The screen for unknown addresses |
| `error(builder)` | The screen for a navigation that failed; `RouteState.error` says why |
| `build()` | The routes |

Paths are written in full. A screen declared in a branch but outside its path (`/motion` in `/more`) opens in that branch all the same, over the branch's first screen.

## Constants for routes in code

A class marked `@RouteDeclarations()` gets generated constants (`to(...)`, keys) for routes declared only in code; the start checks that each one is registered.

## In Spring (Java)

```java
RouterFunctions.route()
    .GET("/books/{isbn}", handler::book)
    .filter(adminOnly)
    .build();
```

## See also

- [Screens and routes](screens.md)
- [Shells and tabs](shells.md)
- [Filters, guards and errors](filters-and-guards.md)
