fespalier documentation
The README is the 60-second path. These pages are the reference, one topic each.
| Page | What is in it |
|---|---|
| Installation and setup | Install options, companion packages, fsp create, fsp init, CI, platform notes |
| Configuration | Every fespalier: key of pubspec.yaml, and route.dart |
| App configuration | Your app's own values per environment: config/app.yaml, profiles, AppConfig, secrets (since 0.24.0) |
| File kinds | What each file under lib/app/ is, exports and receives |
| Migration | Adopting fespalier in a go_router app, and what changed per release |
| Coming from RIBs | What a RIB's router, interactor, builder and workflows become, and moving a feature over |
| Routing | Segments, enums, catch-alls, query parameters, case, localized paths, groups, not-found, the manifest |
| Navigation | Typed navigation, of and copyWith, remount, extra, RouteLink, deferred routes |
| Layouts | Tab layouts, menus, adaptive navigation, transitions, state and scroll restoration |
| Guards | guard.dart, redirect.dart, feature flags, biometric unlock |
| Data | data.dart, retries, freshness, caches, a Rust core's changes, section data, typed helpers |
| Actions | action.dart, validate(), FieldErrors, optimistic updates |
| Forms | form() and useForm with fespalier_forms: typed fields, validation, server errors |
| HTTP transport | fespalier_transport: the interface, the two implementations, decorators and their order, the memo, failures |
| HTTP clients | Dio and package:http over the transport: cancelling, field errors, writes never retried |
| Streaming | Server-sent events with fespalier_stream: live feeds, resuming, change feeds and their topics, telemetry |
main(), app.dart, startup.dart and splash.dart | The generated main() and the root files |
| Adapters | Packages that plug into the generated main() |
| Authentication | Signed-in routes with fespalier_auth: OpenID Connect, DPoP, device-signed sessions |
| Images | Responsive CDN images with fespalier_image |
| Translations | Tolgee texts with fespalier_tolgee: offline, over the air, language from the URL |
| Maps | A pin picker that returns a place with fespalier_maps: MapLibre, geocoder, position |
| Downloads | Files that outlive a screen with fespalier_download: requests, status, engine, restarts, background |
| Push notifications | Notification taps open typed routes with fespalier_push: cold start, warm taps, tokens |
| Analytics | Screen views by route pattern with consent, fespalier_analytics: sink, backends, testing |
| Shortcuts and widgets | Shortcuts and home-screen widgets open typed routes with fespalier_launch: cold start, warm taps |
| Observability | Lifecycle hooks, telemetry, OpenTelemetry, Sentry, Crashlytics |
| Telemetry conventions | Span, event and attribute names: contract version 1 |
| Dashboards on your computer | fsp telemetry: OpenObserve and Grafana |
| DevTools extension | Routes, guards, data and actions in Flutter DevTools |
| CLI reference | Every fsp command, the generated file, editor plugins, fsp dev, performance |
| Route tests | fsp test smoke tests and fsp maestro flows |
| Testing | pumpRouter, currentLocation, the app around the router |
| Run the examples | minimal, shop, features, tabs, telemetry and auth |
| Troubleshooting | Symptoms, things to know, known limitations |
| FAQ | Why the API is shaped this way |
| Development | The repository, just ci, what CI runs |
| Releasing | How a release is cut (maintainers) |
Old README sections
An older link such as github.com/fespalier/fespalier#telemetry, or a message that says (README, "Telemetry"), still works: the README keeps an anchor for every old heading, and each section now lives on the page below.
- ../README.md: Getting started · License
- cli.md: Running your app:
fsp dev· Tasks: commands aroundflutter run·fsp buildandfsp run· Plain output, CI and Windows · The generator · Deep links and a sitemap (fsp links) · Checking string paths · Web chunk sizes (fsp size) · Performance - file-kinds.md: File kinds · Function views · File names · How parameters are filled
- routing.md: Segment types · Enum segments · Catch-all segments · Typed catch-alls · Case and trailing slashes · Localized paths · Non-ASCII spellings ·
(group)folders · A sibling with a compound path · Not-found views · Query parameters · Route manifest andmeta.dart - layouts.md: Tab layouts · Menus and breadcrumbs:
nav.dart· A bar, a rail or a drawer: fespalier_adaptive · Transitions · Shared elements (heroes) · State restoration · Scroll restoration - guards.md: Guards ·
redirect.dart· Sending people back · Feature flags: fespalier_flags · Where flag values come from · Testing flagged routes · Biometric unlock: fespalier_biometrics · The unlock page · Actions that ask again · Relock when the app comes back · Testing an unlock - observability.md: Route lifecycle:
observe.dart· Telemetry · Turning it on · OpenTelemetry with otel_zone · Sentry: fespalier_sentry · What Sentry gets from fespalier · Wiring Sentry · One transaction per screen · Sentry defaults and privacy · Testing with Sentry · Crashlytics · Several sinks: combine and add · Spans around data() and actions · Where a navigation came from: navigateFrom · Operations of your own: TelemetryOp.custom · Testing telemetry · What it costs - navigation.md: The root navigator (
navigator.dart) ·present.dart: a page of your own · The URL as state:ofandcopyWith· Remounting a page:remount· Typedextra· Restoringextraon the web · Links:RouteLink· Preloading the data behind a link · Deferred routes: a page's code on demand - data.md:
data.dart: a function, a selector or a provider · Retries and reloads · Freshness:staleTime, resume and reconnect · Reconnects: fespalier_connectivity · A cache that survives a restart:dataCache· A cache on disk: fespalier_storage · A Rust core's changes: fespalier_frb · Providers per page instance: fespalier_riverpod · Typed helpers on the route · From a location to its data · Section data - streaming.md: Decoding a core's events:
ChangeCodec(now Decoding:EventCodec, since 0.25.0) · A rebuild budget:ChangeBudget - actions.md:
action.dart: typed writes ·validate()andFieldErrors· Optimistic updates:optimistic() - forms.md: Forms:
form()andvalidate()(form() since 0.11.0; validate() is in actions.md) - http.md: HTTP clients: fespalier_http and fespalier_dio · Cancelling a load whose page is gone · Server validation errors on forms · Writes are never retried, over HTTP too · One seam for any client · The wrapping order · Credentials for clients that are not an http.Client
- app-startup.md:
main(): app.dart, startup.dart and splash.dart - adapters.md: Adapters in the generated
main() - push.md: Push notifications: fespalier_push · Install · Configure · Mapping a payload · Cold start and taps · Tokens and permission · Testing
- analytics.md: Analytics: fespalier_analytics · Install · Screen names · Consent · Time on screen · Backends · Testing
- launch.md: Shortcuts and home-screen widgets: fespalier_launch · Install · Configure · Mapping an action · Cold start and taps · Widgets and platform links · Testing
- route-tests.md: Maestro flows (
fsp maestro) · Route smoke tests (fsp test) - auth.md: Authentication · How it fits together · Installing fespalier_auth · The session · Restoring at startup · Guarding signed-in routes · Signing in and out · Calling your API · OpenID Connect and Keycloak · Device-bound tokens: DPoP with fespalier_keypair_dpop · Device-signed sessions: fespalier_sign_keypair · Firebase, Supabase and your own API · Writing a backend · Testing signed-in routes
- telemetry-conventions.md: Telemetry conventions
- telemetry-dashboards.md: Dashboards on your computer:
fsp telemetry· The app side · The dashboards · Reading the colours · The flags · A summary in the terminal:--report· The web andotel_zone· OpenObserve and Grafana show the same numbers · Your own copy - responsive-images.md: Images · Installing
fespalier_image· The image CDN:imageCdnProvider· Buckets: the widths an image is fetched at ·ResponsiveImage· URL builders · imgproxy and EmgR · Cloudinary · imgix · Thumbor · A URL template · Already sized: a srcset · Signed image URLs · Precaching an image behind a link · Images in heroes · Images on the web · Caching images · Testing images · Image loads in telemetry · What images cost - devtools.md: DevTools extension
- examples.md: Run the examples
- development.md: Development
- releasing.md: Releasing
- testing.md: Testing
- faq.md: Design notes
- troubleshooting.md: Status