fespalier-migration
Moving to fespalier and between its versions — upgrading an app from 0.19 to 0.20 (nothing breaks: an app with a data.dart, an action.dart or a deferred page regenerates app.g.dart, whose private name
SKILL.mdskills/fespalier-migration/SKILL.md
GitHubfespalier-migration
Verified against fespalier
589cf391(2026-10-08), release v0.13.0. These skills ship in the fespalier repository, and CI checks them against its code on every change. Version-sensitive claims say the release they became true in; if your app pins another fespalier, trust that release's code over this page. See Versions.
The one rule of upgrading
The package and fsp move together, and lib/app.g.dart is regenerated every time.
The generated code relies on runtime additions of its own release; the upgrade notes of
0.1.1, 0.2 and 0.3 each say "regenerate", and the rule stays even for a release that leaves the file unchanged
(0.10 and 0.13): regenerate and read the diff of lib/app.g.dart.
# 1. pubspec.yaml: bump `ref:` on the git dependency to the release tag, then
flutter pub get
# 2. regenerate with the fsp that matches the package your pubspec.lock resolved
dart run fespalier gen # or: FSP_VERSION=<the same tag> install.sh, then `fsp gen`
# 3. commit lib/app.g.dart, then
flutter analyze && flutter test
fsp --version must print the package's version (ref: vX.Y.Z needs fsp X.Y.Z); an fsp of another
version on PATH is the usual source of an app.g.dart that does not compile.
dart run fespalier uses an fsp on PATH only when its version matches.
0.20 to 0.21: what to check
0.21.0 changes no code you wrote, but a widget test that drives a failing guard or redirect.dart now fails until it calls tester.takeException() for the failure's report (item 7), and every app regenerates app.g.dart: its redirect:s run through runRedirect and its errorBuilder is AppRoutes.errorPage, so a guard or redirect.dart that fails shows the route's error.dart (item 7). Beyond that, app.g.dart is unchanged for an app that spells each type the same wherever it is compared. An app with a parameter whose type is written as a typedef or with an import prefix instead of as the type itself regenerates a different one (items 2 to 4). Four more changes touch what an app sees without touching its code: the telemetry stack moves to OpenObserve v1.1.2 (item 1), fespalier_frb rebuilds less, so a test that counted reloads after a burst may count fewer (item 5), two packages raise a lower bound, of dio and of crypto (item 6), and go_router 18.1.1, which the range fespalier allows takes, keeps the tabs a hot reload leaves (item 8). Bump the ref: of fespalier and every companion to the 0.21.0 tag, regenerate, read the diff, then:
- The telemetry stack moves to OpenObserve v1.1.2, which migrates its data: use
fsp0.21.0 or later forfsp telemetryin every app that shares the stack.fsp telemetrypins v1.1.2 where it pinned v1.0.4, and OpenObserve migrates the stack's database on its first start; v1.0.4 cannot open it afterwards. The stack in~/.fespalier/telemetryis shared by every app on the computer, so an olderfsp telemetry(0.20 or before) writes the v1.0.4 file back, and OpenObserve restarts in a loop (Migration file of version '…' is missingin its log, and the importer says it did not answer). Run the newerfsp telemetryagain: OpenObserve starts on the same data, and--resetis not needed. It also makes a Grafana percentage tile say 100 % when every call in the range failed, where it said Not enough data yet. No app code changes. Seefespalier-troubleshooting(its telemetry diagnostics, "OpenObserve restarts in a loop"). - A typedef of a query type is a query parameter. The typedefs and import prefixes of the app's own files are followed:
ProductViewand theProductit names are one type, and so arem.ProductandProduct. An optional parameterfinal PageNo? page;withtypedef PageNo = int;is a query parameter (?page=), so the typed route gains that optional argument. Unless the route'sdata.dartyields the type spelled the same (typedef Tags = List<String>;on both sides): that parameter is the data, as before. - A typedef or an import prefix of a data type gets the data.
required ProductView productandm.Productget what adata.dartyields asProduct, where an optional one was left to its default. The exact spelling is tried first. - A typedef of a type that is filled by type is filled too. An optional
Kid footerwithtypedef Kid = Widget;in a layout gets the page next tochild(the page is built twice), as an optionalWidget footeralways did; the same fortypedef Failure = Object;andtypedef Retry = void Function();in an error view. A typedef of another package is still compared as spelled, and the message says so. fespalier_frbrebuilds less. A topic's key is rebuilt only by an event that concerns it, and a burst goes through in one event-loop turn while some watched key is not concerned or something watcheschanges.latest; before, Riverpod took a burst one event per turn whenever nothing else watchedchanges.latest, so a key could reload once per event of it. A test that counted reloads after a burst may count fewer now (a key watched alone reloads as before); no code changes. A topic's value counts the events that concerned the key, so one rebuild can move it by more than one (a listener ontopic(42)that saw[1]for the burst[42, 7, 42]sees[2]while something watcheschanges.latest): compare rebuilds, not the number. An exception that a matcher throws reaches a direct listener of the topic (container.listen(topic(key), ..., onError: ...)) as aProviderException, where it arrived as the matcher's own exception.ChangeBudgetis new and opt-in. Seefespalier-data(its change-feeds reference).fespalier_authasks for dio 5.7.0 andfespalier_storagefor crypto 3.0.6 (they asked for dio 5.4.0 and crypto 3.0.0). An app that lets pub choose changes nothing; one that holds a lower version independency_overrides:orpubspec.lockrunsflutter pub upgrade dio crypto.- A guard that fails shows the route's
error.dart, on every go_router. A guard orredirect.dartthat throws, or whoseFuturefails, now reaches go_router as aGuardFailure(itserrorandstackTrace; its message isa guard or redirect.dart failed with <type>, where go_router saidException during route redirect: …), on every version the range allows. The route'serror.dartshows when it takes onlyerror,stackTraceandretry(it builds its ownScaffold, since go_router's error route is a bare page); otherwise the not-found view does. That holds afterpush,pushReplacementandreplacetoo, whereretrycloses the error view and pushes the location again (docs/guards.md, "Retrying a pushed navigation"). Before, a sync throw was the not-found view with no word about it, everywhere, and an async failure was the same on go_router 18.1.1; on 17.2.3 to 18.1.0 an async failure was an uncaughtGoException, and the router stayed on the page it was on. Now, aftergo, a link or a tab, the page the app was on is left (itsonLeaveruns, and telemetry logspage leave); after apushit stays under the error view, covered and not left, andpushReplacementandreplaceover other pages leave the page they replaced. The failure is reported once, in every build mode, withFlutterError.reportError, soFlutterError.onErrorhears it, which is whereSentryFlutter.initlistens. Withtelemetry: truethe navigation ends with the outcomeerrorinstead ofnot_found: the "link leads nowhere" tile no longer counts it, the new "Did a failing check stop a screen from opening?" tile on the Errors dashboard does (a guard that throws before it returns is counted nowhere else), and "How many operations failed?" counts a failure after anawaitonce, on the guard's span. Nothing is uncaught any more, so a reporter that listens only onrunZonedGuardedorPlatformDispatcher.onErrorhears nothing of it. Sentry events: an app withSentryFlutter.initalone gets one event for a failure, the report's (before, the uncaughtGoExceptionof an async failure on 17.2.3 to 18.1.0, and nothing otherwise). An app withFespalierSentry(telemetry: true) as well still gets one event for a failure after anawait: the sink's (tagged with the route and the file) comes first, and the report carries the same error object, so Sentry's deduplication (on by default,enableDeduplication) drops it; with deduplication off it is two (before, the sink's alone on 18.1.1, and the sink's and the uncaught one on 17.2.3 to 18.1.0). A guard that throws before it returns gives the report's event alone. The deduplicated count is run againstSentry.initinfespalier_sentry'stest/dedup_test.dart; the other counts are read from the code paths, not run against the Sentry SDK. A widget test that drives a failing guard fails until it callstester.takeException()for the report; it asserts on the error view, or, aftergo, oncurrentConfiguration.errorbeing aGuardFailure(after apushthat error isnull: go_router keeps the failure in the pushed entry). AGoRouterof your own passeserrorBuilder: AppRoutes.errorPage. Regenerate; no other code changes. Seefespalier-guards(its guards and redirects reference, "If it throws"). - A hot reload keeps the tabs you left, on go_router 18.1.1. From go_router 18.1.1 a hot reload that swaps in the regenerated routes keeps the stack of every tab that was loaded, not only of the tab on screen, and the pages of a tab that is not on screen run no
onLeave. Before, only the tab on screen kept its stack, and the others started over at their first page. A loaded tab the edit removed keeps its pages until its layout goes, and theironLeaveruns then. Debug builds only. No code changes.
Details: docs/migration.md, "0.21.0".
0.19 to 0.20: what to check
0.20.0 breaks nothing: an app with a data.dart, an action.dart, a deferred page or a type written with an import prefix in a route file regenerates app.g.dart (items 1 and 2), with no code change; any other app's is unchanged. Bump the ref: of fespalier and every companion to the 0.20.0 tag, regenerate, read the diff, then:
- The generated names follow the folders. The providers, the deferred libraries, the optimistic layers and the actions are named after their folder, not after where the route sorts:
_dataProductsId,_libCheckout,_optimisticTeamsTeamId,_actionNotesId_edit. So are the DevTools sites,dProductsIdandaNotesId_edit; the guard andredirect.dartsites (g5@6,r32) do not change, and neither does a route's class. A prefixed type's import alias (_e…_m) is made from the library the prefix imports, not from the file that spells the type. The names are private and the DevTools extension reads any site, so no code changes; runfsp genand commit the result. A hot reload now swaps a route added or removed anywhere, sofsp devreloads it instead of restarting. Still refused: a changeddata()or action, a moved folder that has one (and the second of two folders whose names share a stem, added or removed, when one has adata.dartor anaction.dart; two deferred pages alone swap), an import prefix pointed at another library (it was accepted before 0.20.0), and a router setting. Seefespalier-troubleshooting(its dev diagnostics). - A deferred route added or removed hot reloads too.
AppRoutes.deferredis a getter now, where it was astatic finallist, and a deferred page's import is named after its folder (deferred as _pageCheckout, where it was_i7). So an app with a deferred route regeneratesapp.g.dart, with no code change: code that readsAppRoutes.deferredor callsloadDeferred()works as before. Now a swap: a deferred route added, removed or moved beside another; a page added withdeferred: true;deferredturned on or off.fsp sizereads the new names, so runflutter build webagain first; an older build is reported as built from anotherlib/app.g.dart. Before 0.20.0, adding a route before a deferred one was refused (it changedAppRoutes.deferred), but a file that is not a route (aloading.dart, anerror.dartor aguard.dartin the root, or in a folder that sorts before a deferred route) renumbered the position-based import (_i2became_i3) while every hash the reload compares stayed the same. That swap went through, and the deferred page then threw "Deferred library ... was not loaded" until a restart: a bug of 0.19.0 that 0.20.0 fixes, since the import keeps its folder's name. Seefespalier-routing(its route.dart reference, deferred routes).
Details: docs/migration.md, "0.20.0".
0.18 to 0.19: what to check
0.19.0 breaks nothing for an app whose telemetry sinks extend FespalierTelemetry (every sink fespalier ships does): every app regenerates app.g.dart (item 5), and an app that does not name its screen or set otel: true changes nothing else. A telemetry sink that implements FespalierTelemetry instead of extending it adds one method (below). With fespalier_sentry, the scope is named at the commit, which changes a few events from a page's first frame (below).
Native crash records can name their screen, which takes otel_zone v0.7.0 and one call (item 1). Bump the ref: of
fespalier and every companion to the 0.19.0 tag, regenerate, read the diff, then:
Optional: native crash records can name the screen. Bump
otel_zoneto v0.8.1 (the pin is the commit64c4661ac6cd09718141864d528892916677cc38; v0.7.0 was the first withonScreen, andfespalier_otelneeds the rc.4 line from 0.19.0 anyway, which isotel_zonev0.8.0 or later), passonScreen: observability.setCrashScreentoFespalierOtel, and runfsp telemetry --stop, thenfsp telemetry, so the collector reads the attribute and the Errors table has its panel.app.g.dartis not changed by this item (item 5 regenerates it for every app), and an app that does none of this keeps its crash records as they are. Seefespalier-observability(its telemetry section).A telemetry sink of your own.
FespalierTelemetryhas a new member,commit(navigation, commit), with an empty default: the router tells it what each navigation commits, before the page is built. A sink that extendsFespalierTelemetrychanges nothing; one that implements it stops compiling until it adds the method (or extends instead), and one with a member already namedcommitof another signature renames it.RecordingTelemetrywrites commit lines only withrecordCommits: true. Seefespalier-observability(its telemetry reference, "Several sinks").Optional: OpenTelemetry without wiring. Add
otel: trueunderfespalier:, next totelemetry: true, and delete the hand wiring: inlib/main.dart,Future<void> main() => AppMain.run();(a root file makesfspwrite the generatedmain()), and inlib/app/startup.darttheOtelZone, itsstart(), theFespalierOtelsink, the two observers and azone()that runsrunGuarded.fsp genwarns about theOtelZoneand theFespalierTelemetry.installthat are still there. A sink thatstartup()installs withFespalierTelemetry.installmust useFespalierTelemetry.add, once (guarded byFespalierTelemetry.contains, because Retry runsstartup()again), or it replaces the OpenTelemetry sink.otel: trueneedstelemetry: true,fespalier_otelandotel_zone(item 1's pin) underdependencies:, and notmain: manual;fspsays which one is missing.fespalier_otelresolves withotel_zonev0.8.0 or later, but only v0.8.1 runs the generated zone on the web: on v0.8.0 the app works on mobile and its web build is blank, so use the pin. Onlylib/app.main.g.dartchanges for this item (app.g.dartchanges for item 5). Seefespalier-observability(its telemetry section).Sentry names a page at its commit. The scope's transaction name,
fespalier.routeand, next tofespalier_otel,otel.trace_idandotel.span_idare set when a navigation commits, before the new page'sinitStateand firstbuild. Most events read the same: Sentry's own capture of an exception reads the scope after the frame, and a guard,data()or action error takes itsfespalier.routefrom its call site. What changes is what reads the scope during that frame: an event captured on a copy of it (captureException(..., withScope: ...)in your code, and fespalier's own events, whose transaction name now is the page being opened), and code that readsscope.transactionor the tags, such as a page'sinitState. From the commit until the first frame, an event from the page being left names the destination too (captureExceptionright afterrouter.go(...)in the same handler). A search on the transaction name finds these events under the page being opened. Nothing to change in code; a test that readsentry.tagsortransactionNamebefore a pump now sees the new page. Seefespalier-observability(its Sentry reference).Every app regenerates
lib/app.g.dart. Runfsp genand commit the result (a committed file that is not regenerated is stale: the CI recipe indocs/getting-started.md, "Failing CI on a stale file", catches it). There is no code change.AppRoutes.router()builds aGoRouter.routingConfigover a routing config, the same router in release. The layouts' navigators and shells take their keys fromAppRoutes, so a hot reload keeps the pages in them, andAppManifest.byTypeandAppManifest.byPathare getters over the same maps. A hot reload in a debug build now swaps in the regenerated route table, with limits: a route added, removed or moved swaps when no route after it in the order offsp routeshas adata()function, an action or a deferred page (the generated names of those are numbered by position, and a changed name is refused), and a provider, a deferred library or a router setting that changed is refused too. A refused swap prints one message and keeps the old routes until a hot restart; stable names made from the folders will lift the limit on position in a later release.fsp devnow hot reloads after a regeneration that swaps, and hot restarts after one that does not. Seefespalier-troubleshooting(its dev diagnostics).
Details: docs/migration.md, "0.19.0".
0.17 to 0.18: what to check
0.18.0 breaks nothing: the generated app.g.dart is unchanged unless an app lists the new fespalier_launch adapter.
It adds four attributes to the spans of a data load and an action (item 1), the telemetry stack needs one restart to
show them (item 2), fespalier_launch is new and opt-in (item 3), and so is fespalier_frb's ChangeCodec
(item 4). Bump the ref: of fespalier and every companion to the 0.18.0 tag, regenerate, read the diff, then:
- Four attributes are new on the data and action spans:
fespalier.data.attempt,fespalier.data.source,fespalier.action.rolled_backandfespalier.action.invalid. They come withtelemetry: true, like the others. A test that comparesRecordingTelemetrylines whole gains theattempt=,source=,rolled_back=andinvalidtokens. Seefespalier-observability(itsconventions.md). - Restart the telemetry stack once for the new tiles. Run
fsp telemetry --stop, thenfsp telemetry, which rewrites the files and updates the dashboards, so the collector reads its four new dimensions. An app before 0.18.0 sends none of them, so those tiles read 0. fespalier_launchis new and opt-in: nothing changes for an app that does not list it. It opens a typed route from a home-screen shortcut or a widget tap, cold or while the app runs (since 0.18.0). An app that lists it underfespalier: adapters:gets one more adapter inAppAdapters, callsFespalierLaunch.configure(sources:, route:)inmain()beforeAppMain.run(), and configures it in every widget test that bootsAppMain.root()(FespalierLaunch.debugReset()insetUpandtearDown, as for fespalier_push). The plugins (quick_actions and home_widget) stay the app's: their recipes are infespalier-routing(itslaunch-sources.md).- Optional (
fespalier_frb): decode raw core messages withChangeCodec. Nothing changes for a feed over typed events. Anopenthat decodes raw messages itself (.map(decode)) turns one bad message into anAsyncErrorinlatest;.transform(ChangeCodec(decode))skips and counts it instead and keeps the feed going. ThrowUnknownChangefrom the decoder for a variant a newer core added. Seefespalier-data(itschange-feeds.md).
Details: docs/migration.md, "0.18.0".
0.16 to 0.17: what to check
0.17.0 breaks nothing, and changes nothing for an app that uses neither freezed nor build_runner: the generated
app.g.dart is unchanged. It handles two places where fespalier and a code generator trip over each other (items 1 and 2)
and drops a flag from the examples (item 3). Bump the ref: of fespalier and every companion to the 0.17.0 tag,
regenerate, read the diff, then:
- A freezed
extrarestores asnullon a reload, thoughextra_codec.dartlists it. freezed'sconst factory Note(...) = _Note;makes a private_Note, whichExtraCodec({Note: ...})(an exact runtime-type lookup) never matches. Replace the entry withExtraCodec.of([ExtraType<Note>(toJson: ..., fromJson: ...)]), which matches withis; put the most specific type first. A debug build now prints one line, once per type, for anextrano entry takes. Seefespalier-routing(itstyped-routes-and-extra.md). fsp gen,check,watchanddevwarn thatbuild_runnercan deletelib/app.g.dartwhen the app listsbuild_runnerand has alib/app.dart: the builders that write.g.dartfiles claimlib/app.g.dartand delete it, with nothing logged. It is a warning (exit codes are unchanged). Setoutput: lib/routes.g.dart(and change theapp.g.dartimports), renamelib/app.dart, or excludelib/app.dartfromsource_gen:combining_builderinbuild.yaml. Seefespalier-troubleshooting(itsflutter-pitfalls.md).- Optional: drop
-dfrom yourbuild_runnercommands intasks:. build_runner has ignored it since 2.7.0; the commented examplesfsp initandfsp createwrite no longer have it.
Details: docs/migration.md, "0.17.0".
0.15 to 0.16: what to check
0.16.0 is a breaking release for an app on Flutter 3.32 to 3.34: the floor is now Flutter 3.35 and Dart 3.9. It
also changes one member of FespalierAdapter, fixes the places where a write could be sent twice, a provider started a
hidden timer, a notification tap was lost and a step name did not compile, and three outcomes of the network packages (one
port, DownloadBackend.resume, gains a named parameter: item 20), so some outcomes an app sees are different, and adds
opt-in tooling. The generated app.g.dart changes for an app with adapters: (an AppAdapters.handlesEnter getter, and
onEnter: AppAdapters.handlesEnter ? onEnter : null where it was onEnter: onEnter) and for an app with a links:
section (item 12); no file kind, key or command changed. Bump the ref: of fespalier and every companion to the 0.16.0
tag, regenerate, read the diff, then:
Flutter 3.35 or newer (Dart 3.9 or newer) is needed (since 0.16.0).
fespalierand every companion that was in the 3.32 floor job now saysdk: ^3.9.0andflutter: ">=3.35.0";fespalier_sign_keypair(Flutter 3.44) andfespalier_download_background(Flutter 3.47) keep their own, higher ones. On an older Flutterflutter pub getfails with a version solving message that names the SDK, andfsp createsaysFlutter {v} is too old: fespalier needs Flutter 3.35 or newer (https://docs.flutter.dev/release/upgrade). Upgrade Flutter (3.35.7 is the last 3.35 patch, with Dart 3.9.2), set the sameflutter-versionin CI, and raise your ownenvironment:tosdk: ^3.9.0andflutter: ">=3.35.0"(whatfsp createwrites now). An app that has to stay on Flutter 3.32 to 3.34 stays on fespalier 0.15.x.go_router's lower bound is 17.2.3 (it was 17.0.0):
go_router: ">=17.2.3 <19.0.0"infespalier. An app that lets pub choose changes nothing, because 17.2.3 is the newest go_router that Flutter 3.35 to 3.37 resolve (3.38 and later take 17.5.0, and go_router 18 needs Flutter 3.44); an app whosedependency_overrides:orpubspec.lockholds go_router 17.0.0 to 17.2.2 runsflutter pub upgrade go_router.Why. On Flutter 3.32 pub resolved go_router 17.0.0 and no newer one (17.0.1 asks for Flutter 3.35), and that release ran a
Block.thenof anonEnterinside the parse, before the commit, and asserted on a platform payload with no leading slash. On 17.2.3 neither needs a workaround, so the tests that tolerated them on the floor are strict now. What the floor still tolerates is go_router's and Flutter's own, and is true on every Flutter that has it: go_router 17 builds the page agolands on one frame after the location changes (go_router 18 builds it in the same frame), aShellRoutepop skips the leaf'sonExitbefore go_router 17.4, and Flutter before 3.38 drops a link'slinkUrl.fsp create:--features allnow includesotelon every supported Flutter (it needed 3.35 before), and anfsp createapp declaressdk: ^3.9.0andflutter: ">=3.35.0".An adapter's
onEnteris a getter now.FespalierAdapter.onEnterwas a method (FutureOr<OnEnterResult>? onEnter(InboundNavigation navigation)) and isFespalierEnter? get onEnter => null;, whereFespalierEnteris the function type of the old method. An adapter that overrides the method no longer compiles, on purpose:Class 'MyAdapter' can't define method 'onEnter' and have field 'FespalierAdapter.onEnter' with the same name.(conflicting_method_and_field), instead of itsonEnterbeing skipped without a word. Return the same body as a function:// Before (0.15.0) @override FutureOr<OnEnterResult>? onEnter(InboundNavigation navigation) { if (navigation.next.uri.scheme != 'vaam') return null; return Block.then(() => navigation.router.go('/orders/42')); } // After (0.16.0) @override FespalierEnter? get onEnter => (navigation) { if (navigation.next.uri.scheme != 'vaam') return null; return Block.then(() => navigation.router.go('/orders/42')); };The getter is read once, when the router is built. No first-party adapter had an
onEnter, so an app that lists onlyfespalier_push,_analytics,_download,_sentryor_otelchanges nothing here.Every other app with
adapters:navigates synchronously again.AppRoutes.routernow passes go_router anonEnteronly when some adapter's getter is not null, and asks only those adapters. Before 0.16.0 anyadapters:entry made go_router parse every navigation through an asynconEnter, sorouter.go('/a'); router.push('/b');in one handler ended as/home > /b(thegolost) andcurrentConfigurationlagged a frame. Now it ends as/a > /b, committed in the call, as in an app without adapters. Code that worked around the lag (aFuture.delayedor a frame between agoand apush) can go; an app with an adapter that has anonEnterkeeps the async parse and its caveat.A router of your own (
app.dart'srouter()building aGoRouterwithAppRoutes.mount) that passedonEnter: AppRoutes.onEnterpassesonEnter: AppAdapters.handlesEnter ? AppRoutes.onEnter : null. The old line still compiles and still calls the adapters that have one, but keeps go_router's async parse for an app whose adapters have nothing to say. Also new: with adapters and notelemetry:,launchRoutergetslinks: AppAdapters.handlesEnter, so no platform-link observer is added when no adapter has anonEnter(withtelemetry: true, stilllinks: true). Details:docs/adapters.md("onEnteris a getter that answers a function") anddocs/migration.md, "0.16.0".fespalier_download_background: a5xx,408or499on an upload isFailed(other), notFailed(rejected). Only a client error that proves nothing was applied (400,404,413,422, ...) staysrejected. For an upload without anIdempotency-Keythe newotheris an unknown outcome:outcomeUnknown(id)is true, andretryandstartrefuse it (on 0.15.0retrysent the write again after a500or504, which could run it twice). Search forDownloadFailure.rejectedin the code that handles an upload and decide what an unknown outcome shows: ask your server, thenremove(id)andstartagain, or give the upload anIdempotency-Key. Downloads are unchanged.fespalier_download_background: an upload whose registry entry cannot be saved endsFailed(storage)and is not sent.UploadStore.putmay now throwUploadStoreException(FileUploadStoredoes, on a failed write), andFileUploadStoreno longer reads an unreadable file as an empty registry:loadandputthrow, the file is left alone, and until the nextopen()reads it (orclearAccount()deletes it) an upload without a key endsFailed(storage). A customUploadStorethat swallows its failures keeps the old behaviour: letputthrow. HandleFailed(storage)on an upload (retry); the two debug lines are infespalier-troubleshooting.fespalier_cratestack: a5xxwithout a CrateStack envelope keeps the intent's key. A bare500, a proxy's520, a panic handler's text is nowCrateStackOffline(as502,503,504and511were), notCrateStackUnavailable: the write may have committed, and a new key would run it twice. Only a5xxin the envelope (codeandmessage) isCrateStackUnavailableand moves to the next key. Visible effects: a read behindservefalls back to the saved copy on a bare5xx(it threw before),DioFailures.readandCrateStackFailure.fromResponsereturnCrateStackOfflinefor it, anddrainstops at it as it stops at anyCrateStackOffline. Search forCrateStackUnavailablein your own reader and tests; one that expected a bare500to be unavailable now sees offline.fespalier_cratestack:drainreads each intent again before it sends it. An intent without asubjectthat a concurrentsubmitgot accepted (or that was discarded, or wiped by a sign-out) while the drain was busy with an earlier one is no longer sent a second time. Nothing to change.An app with a
links:section regenerates withAppRoutes.urlOf. The diff is a doc comment andstatic Uri urlOf(TypedLocation route, {String? locale})aftermatchUrl:Uri.parse('https://<first domain>${route.locationFor(locale)}'), the mount prefix in it. Nothing has to change; use it for a share sheet, a notification payload or anog:url. An app withoutlinks:regenerates byte for byte. If the first domain oflinks: domainsis not usable (none, not a host name, a wildcard first),fsp genprints the warning! pubspec.yaml `AppRoutes.urlOf` is not generated: ...and goes on, as before: onlyfsp linksfails on it.fespalier: test: a11y:is opt-in. Without itfsp testwrites the file it always wrote. Withtrue(or a list oftap_targets,labels,contrast) every smoke test also runs Flutter's accessibility guidelines on the whole screen, so the first run fails on whatever the app lacks, shared chrome first (anIconButtonwithout atooltip, anInkWellaround aText, pale text): fix the widget once and every route under it passes. Anfspolder than 0.16.0 rejects the key with theunknown fieldmessage that lists thetest:keys.The DevTools extension has a seventh tab, Adapters, and the protocol is still 1: the app lists
adaptersinhello's features, sendsfespalier:adapterevents and a snapshotadapterslist, and answersext.fespalier.adapterEdit. A tool of your own that comparesfeaturesexactly should askcontains. The tab is empty until a package callsDevToolsAdapters.show; on an app older than 0.16.0 it says so. Committeddevtools_options.yamlfiles need no change.A plugin that throws is not asked again.
biometricAvailable(fespalier_biometrics),pushPermission(fespalier_push),pendingIntents(fespalier_cratestack) andChangeFeed.latest(fespalier_frb) now passretry: (_, _) => null. Before, Riverpod 3's default re-asked a plugin or store that threw anExceptionup to ten times over about 50 seconds, with aTimer(a widget test whose fake threw ended with a pending timer; aChangeFeedopened its single-subscription stream again). Now the provider is anAsyncError, read once. If you relied on the retries, callref.invalidate(provider)where you want to ask again.A notification tap while the app starts is opened (
fespalier_push). It was lost:launch()runs beforerunApp,attachafterstartup()and the first frame, and nobody listened totapsin between. Nowlaunch()keeps the latest tap (one, never a queue) andattachopens it once, as a warm tap, after the first frame. The cold-start notification seen again ontapsis still opened once (by id; without an id, by an equal payload). Two things to check: aPushSource.tapsbuilt on a platform channel must return one stream every time (alate finalfield), becausetapsis now listened to twice while the app starts; and a test that taps betweenAppAdapters.launch()andpumpWidgetnow sees that tap open. Seedocs/push.md, "Cold start and taps".fsp checkrefuses a step folder that is no Dart enum constant. Astepskey written asfinal,new,defaultorin, a name every enum has (values,index,hashCode...), a name that starts with a digit (2fa), or two folders that become one constant (contact_info,contact-info) passedfsp checkand then wrote a step enum thatflutter analyzerejected, so no building app changes. Rename the folder and its key insteps(final_step,step_2fa); the messages are infespalier-troubleshooting.A request with a body is sent again after a 401 through
DioHttpClient. Anhttp.Request(get,post,put,patch,delete) goes to Dio as bytes, soSessionInterceptorrefreshes and sends it again whole (WriteGuardlets that one second send of a write through, as it always did after a 401). Before 0.16.0 it failed withClientException: fespalier_dio: unknownand the refresh never helped: remove a retry you wrote around that. A streamed or multipart request (StreamedRequest,MultipartRequest) is not sent again: the caller gets the 401 as the response, after the refresh. AClientExceptionfromDioHttpClientthat has no Dio message now carries its cause (fespalier_dio: unknown: <cause>): code that compared the whole message changes.Offline while a token refreshes is
Failed(network), no longerFailed(unauthorized). A download whose credentials could not be reached endsnetworkwhen its grantor, or theHttpCredentialsofHttpDownloadBackend, throws anhttp.ClientException(fespalier_auth'sAuthUnavailableis one).unauthorizedstays for a refusal and for any other throw. If your app treatsunauthorizedas "sign the person in again", it no longer does that for being offline: show "offline, try again" fornetworkand callDownloads.retry. Aresumewhose grantor cannot be reached leaves the downloadPausedand returns false.A paused download resumes from its freshly granted address, and each resume gets its own renewal. Before 0.16.0
resumeasked the grantor and threw the newurlaway, so an expired signed address earned a 403 first, and only one renewal existed for the whole life of the download: a second long pause endedFailed(unauthorized). Nowresumegoes to the grant'surl(the bytes kept stay), and a start, a retry and a resume each have one renewal. The grant aresumeasks for is used now, not discarded. ADownloadBackendof your own (a fake in a test, a custom transfer) must accept the newurl:named parameter ofresume(id, {authorization, url}):flutter analyzenames the override that is missing it.FakeDownloadBackend.resumeUrlsrecords it.
Details: docs/migration.md, "0.16.0".
0.14 to 0.15: what to check
0.15.0 is a breaking release for an app that imports package:fespalier_dio/http.dart or
package:fespalier_dio/problem.dart: the package:http half of fespalier_dio is now the fespalier_http package,
and both libraries are removed, not deprecated (the 0.11.0 forms precedent). The generated app.g.dart is unchanged,
and a Dio-only app changes nothing (package:fespalier_dio/fespalier_dio.dart still exports problem.dart). Bump the
ref: of fespalier and every companion to the 0.15.0 tag, then:
- Add
fespalier_httptodependencies:with the sameurlandrefasfespalier, and change the imports:package:fespalier_dio/http.dartbecomespackage:fespalier_http/fespalier_http.dart(which also exportsproblem.dart), andpackage:fespalier_dio/problem.dartbecomespackage:fespalier_http/problem.dart. No member was renamed.flutter analyzenames every import left behind (Target of URI doesn't exist). fespalier_authnow depends onfespalier_http(itsAuthorizerimplementsHttpCredentials,AuthAttemptimplementsHttpAuthorization); an app that overrides dependencies by hand addsfespalier_httpto the overrides.- New and opt-in:
DioHttpClientinpackage:fespalier_dio/client.dart,HttpCredentials,HttpWrites.isWrite(the one write rule both guards call; behaviour unchanged) andFakeHttpClient/FakeHttpCredentialsinpackage:fespalier_http/testing.dart.fespalier-data(itshttp.md) has the layer order. Details:docs/migration.md, "0.15.0".
0.13 to 0.14: what to check
0.14.0 is a breaking release for fespalier_push: every PushSource changes its tokens type, and an app with no token
callback changes nothing else. Bump the ref: of fespalier and every companion to the 0.14.0 tag, then:
PushSource.tokensis aStream<PushToken>(it wasStream<String>). Wrap the vendor's string:PushToken(kind: PushTokenKind.fcm, value: token);kindis an open string (PushTokenKind.fcm,apns,hms,unifiedpush,onesignal,mipush,oppo,vivo,honor,jpush, or your own),valueis never null, andproperties(an unmodifiableMap<String, String>) carries what the backend needs besides the token, such as OneSignal'ssubscription_id.onTokeninFespalierPush.configuretakes aPushToken, andpushTokenis aStreamProvider<PushToken>. Sendkind,valueandpropertiesto the backend.PushToken.toStringprints the kind only: do not print the value yourself.- A revocation is a separate event, never a null token:
PushSource.revocations(aStream<PushTokenRevoked>, empty by default, so a source that never revokes needs nothing), thepushTokenRevokedprovider,onTokenRevokedinconfigure. - Tests:
FakePushSource(token: PushToken(...)),emitToken(PushToken(...)), andrevokeToken(kind, properties:). - No telemetry changed (no token event is reported). The vendor recipes (FCM, APNs, HMS, UnifiedPush, OneSignal, JPush,
flutter_mix_push) are in the
fespalier-routingskill'spush-sources.md. Details:docs/migration.md, "0.14.0".
0.12 to 0.13: what to check
Bump the ref: of fespalier and every companion to the 0.13.0 tag and run the matching fsp gen; lib/app.g.dart and
lib/app.main.g.dart come out unchanged (no emitter or template changed since 0.12.0 but the version fsp init prints), and
docs/migration.md has no 0.13.0 entry because there is nothing to change. What is new is additive and opt-in: the companion
packages fespalier_maps, fespalier_push, fespalier_biometrics, fespalier_analytics, fespalier_frb and
fespalier_riverpod (each in the skill that owns its topic; they take the same url and ref as fespalier), and in
package:fespalier: appShowSignal (a RefetchSignal that fires when the app is shown again after it was hidden, not when
it only went inactive), FespalierTelemetry.contains(sink) (whether a sink is installed, alone or inside a combine), and
package:fespalier/fespalier.dart also exports Riverpod's NotifierProviderFamily, ProviderFamily and
ProviderOrFamily. No TelemetryOp, file kind, fespalier: key or command was added, so an exhaustive telemetry sink
still compiles.
0.11 to 0.12: what to check
0.12.0 changes nothing for an app that does not opt in: app.g.dart and app.main.g.dart regenerate to the same
bytes. New in startup.dart (since 0.12.0): FutureOr<void> ready(ProviderContainer container) and
void attach(GoRouter router, ProviderContainer container), each optional. The gate makes the app's
ProviderContainer itself when ready() exists, runs it before the router is built, and calls attach() after the
first frame that shows the router, after the adapters' attach. The order is zone(), startup(), the container,
ready(), the router, attach(). ready and attach are reserved names in startup.dart: a helper of that name with another shape is now an fsp error (rename it or make it private). A ready() that throws goes to the splash's error and retry, which
disposes the container, makes a fresh one and runs ready() again (not startup()). To move a main: manual app's
main() over: its overrides to startup() (they are made before any container), the code between creating its
ProviderContainer and runApp (an await container.read(x.future), an eager read, a container.listen) to
ready(), and the post-frame step that needs the router to attach(). Details: the fespalier skill's app-main reference; docs/migration.md, "0.12.0".
0.10 to 0.11: what to check
0.11.0 is a breaking release for apps with forms (form() in an action.dart); an app with none changes nothing. Bump the ref: of fespalier (and every companion) to the 0.11.0
tag, then:
- Add
fespalier_formsunderdependencies:, at the same giturlandrefasfespalier(the block is inpackages/fespalier_forms/README.mdanddocs/forms.md), and runfsp gen.app.g.dartnow importspackage:fespalier_forms/fespalier_forms.dart, only in an app with aform(). Until the dependency is therefspreports an error at eachform():`form()` is the form of `action()`, and since 0.11.0 forms are in the fespalier_forms package: add `fespalier_forms` under `dependencies:` in pubspec.yaml, with the same git `url` and `ref` as fespalier. - Imports of the form types. Code that names
ActionForm,ActionField,ActionTextField,ActionFormFields,FieldCodec,ActionFormMessages,ActionFormValidationoruseActionFormimportspackage:fespalier_forms/fespalier_forms.dart:package:fespalier/fespalier.dartno longer exports them (no shim and no re-export). The names and the behaviour are the same, and a page that only calls the generateduseFormneeds no import. - What stays in
fespalier:FieldErrors,validate()andoptimistic(). A test of an action'sFieldErrorsor ofvalidate()changes nothing;fespalier_dio,fespalier_auth,fespalier_cratestackandfespalier_sentryare unchanged. A test file that waspackages/fespalier/test/action_form_test.dartin a fork ispackages/fespalier_forms/test/action_form_test.dartnow. - Floor and CI:
fespalier_formsclaims Flutter 3.32 like the packages it follows; a repository that copies this repository'sjust floorlist adds it. - Where the form is documented now: the forms and optimistic pages of
fespalier-data(the one page it was part of is split in two). - Drafts are new and opt-in, but every app with a
form()regenerates.useFormtakes aFormDraft? draftanduseActionFormgets the action'sid:,key:andshape:; abool,DateTimeor enum field gets aDraftCodec. A key of an action with a form can no longer be calleddraft(fspsays`draft` can't be a key of an action with a form: its hook, `useForm`, takes a parameter called `draft`; rename it). Drafts are kept informDraftStorage(yourdataCacheStorageby default): callclearFormDrafts(ref)at sign-out and giveformDraftScopethe account. - Asking before unsaved changes go is new and changes no generated code. A
leave.dartthat isleaveIfClean(context, ref, page)(fromfespalier_forms) asks in a bottom sheet ("Keep editing", "Discard", "Keep as draft" for a form with adraft:); auseFormunder a page with aleave.dartregisters its form as the page'sLeaveSourceitself. The sheet is Flutter's (showModalBottomSheet), so an app on material_ui'sMaterialApp, which has noMaterialLocalizations, overridesleavePromptwith its own sheet. See the forms reference offespalier-data, "Leaving with unsaved changes". - Multi-page forms are new and opt-in (the flows reference of
fespalier-data). A section'saction.dartwith aconst stepsmap is a form over several pages that share one form and one draft; an app that adds none changes nothing. Only a map literal calledsteps(or<action>Steps) beside aform()is read as one from 0.11.0 (and reported when malformed); astepsof another shape is left alone. A flow section may have a page-lessleave.dart.LeaveScope.onBacknow blocks the pop on the first page of a navigator too.
Route lifecycle
An app with an observe.dart regenerates lib/app.g.dart, and nothing else changes for a hook you wrote.
- The generated closures read
onEnter: (ref, scope) => ...now:RouteHooks.onEnterisvoid Function(Ref ref, RouteScope scope)?. A hand-builtRouteHooks(a test, a fork) takes two parameters:onEnter: (ref, _) => .... Runfsp genwith the 0.11.0fsp. onEntermay take{required RouteScope scope}:scope.hold(provider)keeps a provider (a route'sdata) loaded until the page is gone, a parked tab included, andscope.onLeave(callback)runs when it is gone.onLeaveandonFocuscannot take it (an error). The page instance, the order at leave and the lifetimes are onfespalier-observability's lifecycle page.AppRoutes.attachtakes the optionalProviderContainerin an app with anobserve.darttoo (it had it only withadapters:), and the generatedlib/app.main.g.dartpasses it (attach: AppRoutes.attach: regenerate both files). Hooks therefore run in the app's root container: a provider overridden only in a nestedProviderScopereads its default there.AppRoutes.attach(router)works as before.- A scope ends when its container is disposed too, so a
scope.onLeavecallback runs at the end of apumpRoutertest. - Page ids changed for
replace: a page made byreplacehas the key of the page it replaced (go_router), and the lifecycle now uses it:replace('/c/1?q=2')on/c/1is no leave and enter,replace('/c/2')is. Telemetry page events and Sentry breadcrumbs follow.pushandpushReplacementare unchanged. Test a hook withTestRouteScope(package:fespalier/testing.dart).
Adapters
An app without fespalier: adapters:
gets nothing from this part. An app with adapters: regenerates two files:
lib/app.g.dartgainsAppAdaptersand the adapters' imports (package:<name>/fespalier_adapter.dart as _a0), andAppRoutes.attachtakes an optionalProviderContainerand runs each adapter'sattachwith it.lib/app.main.g.dartno longer imports the adapters: it callsAppAdapters.zone,.beforeRun(),.wrap,.overrides(),.providerObservers()and.routerObservers(), and gives theStartupGateattach: AppRoutes.attach.main: manualwithadapters:is accepted (0.10.0 refused it): callAppAdaptersfrom yourmain()andAppRoutes.attach(router, container)once both exist (fespalier, app-main page).FespalierAdapterhas a new member,attach(router, container), with an empty default. An adapter thatimplementsFespalierAdapter(notextends) stops compiling: extend it.FespalierAdapteralso haslaunch()andonEnter(InboundNavigation)(empty defaults), and the runtime hasInboundLaunchandlaunchRouter: a platform link is markedNavigationSource.linkin telemetry whenlaunchRouter(links: true)builds the router. The generated wiring is there too:AppRoutes.routertakeslaunch:and passeslinks: truewith telemetry or adapters, and with adapters there is anAppRoutes.onEnter(passed toGoRouter(onEnter:), since 0.16.0 only when an adapter has anonEnter) andAppAdapters.launch(), which the generated main asks once and hands to the router asAppMain.launch. Every app'sapp.g.dartchanges (the router is built insidelaunchRouter: runfsp gen). An app.dartrouter()passeslaunch: AppMain.launchon (fspwarns otherwise); amain: manualapp callsAppAdapters.launch()itself. AnyonEntermakes go_router parse every navigation asynchronously and apply its redirect limit, so it is generated only with adapters.- Moving from
main: autotomanual: deletelib/app.main.g.dart. Each adapter's top-leveladapteris read once, at the firstAppAdapterscall.attachruns after the first frame that shows the router.
Guards above tabs (0.11.0)
A guard above a tab layout (the tabs folder's own, or a page-less folder over it) is now generated once, on the StatefulShellRoute's redirect:, not copied into each tab's route (fsp gen). Behaviour is the same; its telemetry and DevTools site is one, with the tab folder's pattern as fespalier.route (/ for a group), so dashboards grouping guard outcomes by route see the tabs merged. A tab's own guard.dart stays on its route.
Telemetry (0.11.0)
TelemetryOp gains custom, for a package's own operation (FespalierTelemetry.begin and finish; TelemetryStart has
new name and attributes fields and TelemetryEnd a new attributes field). A FespalierTelemetry sink of your own
with an exhaustive switch on TelemetryOp stops compiling: add a TelemetryOp.custom case or end the switch with
_ =>. The error says the switch does not handle TelemetryOp.custom. An app that uses only FespalierOtel,
FespalierSentry or RecordingTelemetry changes nothing. FespalierSentry does not send a custom failure as an event
unless you pass a capture: that returns true for it (the exception text is the package's).
0.9 to 0.10: what to check
Bump the ref: to the 0.10.0 tag, run the matching fsp gen as always, and expect lib/app.g.dart unchanged. This was
checked as of bfbbf87f (after 0.9.1): nothing the emitter writes, no runtime file of package:fespalier and no template
that fsp new or fsp init writes into an app changed behaviour since 0.9.1, only comments and the documentation pointers
of a few messages. Re-run fsp gen and git diff lib/app.g.dart on the release itself to confirm; a diff there is a bug to
report, not something to accept.
- The documentation moved. The long README is now a short one, and the reference is one-topic pages under
docs/(docs/routing.md,docs/data.md,docs/i18n-tolgee.md, ...). The old README anchors still work (the README keeps one per old heading, anddocs/README.mdmaps them). Somefspmessages cite a page now, where 0.9 cited the README:fsp init's pointer (see docs/app-startup.md), thefsp runandtasks:messages (docs/cli.md, "Tasks: commands around `flutter run`") and the warning⚠ this app sends no fespalier spans yet ... (docs/observability.md, "Telemetry"). A CI step or a script that greps for the old(README, "...")text must follow; the message's meaning is the same. - Two new, opt-in companion packages with no generator change (no file kind,
fespalier:key orfspcommand):fespalier_tolgee(translated texts, the language from the URL:fespalier-i18n) andfespalier_cratestack(offline-first reads, queued writes and sync, with a CrateStack client:fespalier-offline,fespalier-cratestack). Like every companion, they take the sameurland the samerefasfespalier(andfespalier_cratestackneedsfespalier_dioat the same tag too). An app that does not depend on them is byte for byte what it was. Neither ships afespalier_adapter.dart, so they go instartup(), not inadapters:. - Adopting translations from
gen-l10nor from thetolgeeSDK is not a mechanical change (keys become strings, the locale comes from the route, apostrophes before a brace are doubled): the steps are infespalier-i18n(itsmessages-and-catalogs.mdpage). - Nothing to do for telemetry sinks: 0.10.0 adds no
TelemetryOpand no convention (contract version 1), so an exhaustive sink still compiles. Reads throughserveandsubmitrun inside the existing data and action spans.
0.8 to 0.9: what to check
Bump to v0.9.0, regenerate (lib/app.g.dart changes in every app, by its page names: item 10), and look at these:
- A
FespalierTelemetrysink that switches exhaustively overTelemetryOpstops compiling (The type 'TelemetryOp' isn't exhaustively matched by the switch cases since it doesn't match the pattern 'TelemetryOp.auth', and'TelemetryOp.image'). Add aTelemetryOp.authcase (it is whatpackage:fespalier_authreports, withTelemetryStart.authStep,authBackend,authTriggerandauthDpop) and aTelemetryOp.imagecase (whatpackage:fespalier_imagereports, withTelemetryStart.imageCdn,imageWidthandimagePreload, andTelemetryEnd.imageStatus), or end the switch with_ =>.fespalier_otelandRecordingTelemetryhave it. A sink with adefault, or one that does not switch, is unaffected.TelemetryOutcomegainsnone,expired,rejectedandcancelled, andFespalierTelemetry.beginandfinish(for adapter packages). - The telemetry conventions gain an
authand animageoperation, withfespalier.auth.*andfespalier.image.*attributes, within contract version 1 (new values offespalier.operation, new keys): a dashboard that lists the operations shows two more.fsp telemetry's dashboards label them "Session (sign-in, refresh, sign-out)" and "Image load". - New, opt-in:
package:fespalier_auth(fespalier-guards, itsauth-package.md), with OpenID Connect and Keycloak (package:fespalier_auth/oidc.dart), a dio interceptor (package:fespalier_auth/dio.dart) and, as a separate package, device-bound tokens (package:fespalier_sign_keypair, DPoP; itsauth-dpop.md). An app that addsfespalier_sign_keypairneeds Dart 3.12 and Flutter 3.44, the sameurlandrefasfespalierandfespalier_authfor the three, and network access togithub.com/vaam-apps/flutter-sign-keypairatpub get(it is a git dependency, not on pub.dev). Nothing else changes: no generated code, file kind, key or command. - An app with
telemetry: trueregenerates a differentapp.g.dart. Each data provider callsdata()throughtraceDataCall(ref, 'd4', id, () => _i5.data(ref, id: id), telemetry: ...)instead oftraceData(ref, 'd4', id, _i5.data(ref, id: id), telemetry: ...)(an app withouttelemetry: truekeepstraceData). It costs one closure per provider build, with noFutureand no microtask. What follows: adataspan starts beforedata()runs, so its duration includes the synchronous part; adata()that throws before it returns now gets adataspan (fespalier.data.state = error,fespalier.async = false; before 0.9.0 it got none); andFespalierOtelmakes data and action spans current while they run, so the spans ofotel_httpandotel_diomade inside are their children. - New, opt-in:
package:fespalier_image(fespalier-images): aResponsiveImagethat fetches a network image at the width its box needs through an image CDN (imgproxy, EmgR, Cloudinary, imgix, Thumbor, a template or a signed srcset), andRouteLink(onPreload:)in fespalier itself, which runs a callback when a link starts a preload (a nullable parameter: nothing changes for a link that does not pass it). The sameurlandrefasfespalierfor the two. No generated code, file kind, key or command changes. - New, opt-in, in
fespalier-observability:FespalierTelemetry.combineandadd(several sinks in the one slot, each with its own tokens and isolated), thewithinhook a sink may override (an instance member with a default, so a sink compiles unchanged unless it already had a member namedwithinwith another signature: rename it),FespalierTelemetry.runfor adapter packages, andnavigateFromwithNavigationSourceand the attributefespalier.navigation.source(contract version 1 gains a key; absent unless a bridge marks the navigation).RecordingTelemetrygainsrecordWithin:andsource=. - The package asks for
hooks_riverpod: ^3.3.2(it was^3.2.1): on riverpod 3.2.1, the lowest the old constraint admitted, a closedPrefetchHandleleft its provider alive andfreshnessdid not load again. An app already resolves 3.3.2 or newer; one pinned lower must raise its own constraint. - New, opt-in:
package:fespalier_dio(fespalier-data, itshttp.md):ref.cancelToken()andref.abortable(client),withFieldErrors()andWriteGuardfor Dio andpackage:http. A repository dependency with the sameurlandrefasfespalier; an app that does not add it is unchanged (no generated code, file kind, key or command). - New, opt-in:
package:fespalier_sentry(fespalier-observability): Sentry, errors first (events tagged with the route pattern, the app file and the action, one breadcrumb per page change, the OpenTelemetry trace id on each event next tofespalier_otel; screen-load transactions only withtracing: true). The sameurlandrefasfespalier, andsentry_flutter9.26.0 or newer. No generated code, file kind, key or command changes.FespalierTelemetrygainstraceOfandlinkTrace(instance members with defaults) andTelemetryTrace, whichcombineuses to tell a sink which trace an operation is in (FespalierOtelanswers it): a sink that already had a member namedtraceOforlinkTracewith another signature must rename it. - An app that opts in to nothing regenerates with page-name changes only (since 0.9.0). Each
pageBuilder:fespalier writes (a route with atransition.dartorpresent.dart, aremountroute, a layout's shell) is wrapped innamedPage('<pattern>', () => ...): two lines per page builder, the first gainingnamedPage('/products/:id', () =>and the last a). The pagesTransitions.*,layoutPageandremountPagebuild are then named by their route pattern (RouteSettings.name), so aNavigatorObserver(Sentry's, Firebase Analytics', PostHog's) sees/products/:idwhere it sawnull(aremountpage saw:id). Keys, restoration ids, transitions and the release build are otherwise the same. A route with neither (a barebuilder:) is go_router's own page and unchanged. Withtelemetry: trueeachdata.dartprovider also becomestraceDataCall(..., () => data(...), telemetry: ...)(item 4). Atransition.dartthat builds aPageof its own can passname: Transitions.pageName. - New, opt-in, in
fespalier(its app-main page): thefespalier: adapters:key inpubspec.yaml(a list of package names), andFespalierAdapterinpackage:fespalier/startup.dart. Each listed package shipslib/fespalier_adapter.dartwith a top-leveladapter, and the generatedmain()calls itszone,beforeRun,overrides,providerObservers,routerObserversandwrap; the key makesmain: autowritelib/app.main.g.darton its own. An app without the key regenerates the samelib/app.main.g.dartas before. Anfspolder than 0.9.0 rejects the key as an unknown field.
0.7 to 0.8: what to check
Bump to v0.8.1, regenerate, and look at these:
unknown_pathchecks segment types. The string-path lint (lints: unknown_path) now also reports a literal path that reaches a route whose segment cannot parse it:`/products/abc` reaches /products/:id, but `abc` is not an int, so it shows not-found [unknown_path](on one line). It is the same id and level, so an app withunknown_path: errorthat passed on 0.7.0 can fail on 0.8.1, for a path that always showed not-found. Fix the literal, use the typed route, or// fsp:ignore unknown_path. Messages and what is checked:fespalier-troubleshooting, "String paths" in its diagnostics reference.- The package asks for
hooks_riverpod: ^3.2.1(it was^3.0.0):Ref.mountedis right for a stale ref and a paused provider resumes, whichfreshnessrelies on, and the experimentalpersist()thatdataCacheis built on is there. An app already resolves 3.4.x; one pinned lower must raise its own constraint. - An app that opts in to nothing regenerates with DevTools-only changes. A data route's view now watches through
watchData(ref, 'dN', provider)andlib/app.g.dartgains a_devToolsProviders()map thatdevToolsRegisterreceives.watchDatareturnsref.watch(provider)unchanged (a pass-through: noFuture, no microtask, and in a release build it isref.watch) and the map is only read underkFespalierDevTools, so behaviour, timing and the release build are the same; only the diff of the generated file is new. freshnessanddataCacheare now namesfspreads in adata.dart. A public top-level variable of that name and another type is an error (`freshness` must be a `Freshness(...)`); rename it. A private_freshnessis never read. Aroute.dartmay holdconst freshness = Freshness(...)too (the "expected ..." error now names seven constants).- New, opt in:
Freshness(staleTime,refetchOnResume,refetchOnReconnect),DataCachewithdataCacheStorageandMemoryDataStorage,package:fespalier/persist.dart, and thefreshandcachedtags offsp routes. A route that opts in keeps its page when a reload fails (the freshness page offespalier-data). - A
lib/app/app.dart,startup.dartorsplash.dartat the root that is something else is the one thing that can break:fspreads them now (main: auto) and errors with "the app's widget gets the router: ...". Move the file into_components/, or setmain: manual. Moving a hand-writtenmain()to the generatedAppMainis optional; the table is inreferences/upgrading-0-7-to-0-8.md. An app with none of the three gets no new file (lib/app.main.g.dartis written only when one exists, or withmain: generated). - New, opt-in:
observe.dart(onEnter,onFocus,onLeaveper page), thetelemetrykey,package:fespalier_otel,RecordingTelemetryandfsp new --observe. Seefespalier-observability. fsp newwith nothing to create now lists--observe:nothing to create: ... also pass --action, --layout, --loading, --error, --not-found, --guard, --observe or --transition.- A new tag on
fsp routes: a page with anobserve.dartat or above it is taggedobserve(and--jsontagsand the route tree'smarkersgain the value); consumers that match tags exactly should accept it. otel_zoneand the dartastic rc.4 line (since 0.19.0).fespalier_otelneedsdartastic_opentelemetry^1.1.0-beta.17 and API rc.4, which isotel_zonev0.8.1 (commit64c4661ac6cd09718141864d528892916677cc38): bump thatref. It accepts go_router 17 and 18, so thego_router: ^18.0.0override is gone; anotel_zoneup to v0.7.0 pins go_router 17 (throughotel_go_router^0.2.0) and cannot resolve beside this package.DeferredLibraryhas an optionalroute(the generator sets it withtelemetry: true), andtraceGuardandtraceDatatake an optionaltelemetry:; nothing to do unless you call them yourself. An app with noobserve.dartand notelemetry: truegets none of items 7 to 11 inapp.g.dart: noTelemetrySite, noAppRoutes.attach, noobserve:(the generator'sno_companionstest pins it).
0.6 to 0.7: what to check
Bump to v0.7.0 and regenerate. A route that is not deferred generates exactly what it did before. The one visible change is
new warnings: fsp gen, check and watch now read the string paths in lib/ and warn about one that matches no route
(no route matches `/nope`, so it shows not-found [unknown_path]; the severity is the pubspec's lints: unknown_path, and
error makes the commands exit 1). Fix the path, use the typed route, // fsp:ignore unknown_path, or set off. New and
opt-in: deferred (a page's code loads on demand), fsp maestro with semantics_ids, the DevTools extension,
TypedLocation.pushReplacement and RouteInfo.sibling.
0.5 to 0.6: what to check
Bump to v0.6.0, regenerate, and look at these:
remount: neveris what fespalier generated before 0.6.0 (a page keeps its state when its URL changes), and the generated code keys a page by the URL where it used go_router'sstate.pageKey. A route that should start again when its URL changes opts in withremount(fespalier-routing).replacenow shows its location in the address bar and replaces the history entry on the web; on 0.5.0 it was go_router's in every case (the address bar followed it only when no page was below it), so usegofor URL state there.pumpRouter(disposeRouter: false)is the way to keep a test's ownaddTearDown(router.dispose)(item 1 of "0.4 to 0.5").
0.4 to 0.5: what to check
Bump to v0.5.0, regenerate, and look at these:
pumpRouterdisposes the router when the test ends. A test that registeredaddTearDown(router.dispose)before calling it now fails with A GoRouteInformationProvider was used after being disposed, because that teardown runs afterpumpRouter's. Delete the line, or, since 0.6.0, keep it and passdisposeRouter: false.- New reserved names. Every typed route gains
preload,of,maybeOfandcopyWith, so a segment or query parameter with one of those names is refused byfsp; rename it. Anaction.dartfunction can't use them either. AppRoutes.router()without anavigatorKeymakes a fresh one, so tests no longer share a navigator through the generated class. A test that mounts under a prefix restores the defaults withaddTearDown(AppRoutes.mount).- New, and nothing changes unless you use it:
action.dart,RouteLinkwithpreload(it brings inurl_launcher),XRoute.of(context)andcopyWith, guards and redirects that take aRef, andfsp links/fsp routes --graph.
0.3 to 0.4: what to check
Nothing in the generated code or the runtime API breaks; bump, regenerate, and look at these:
- The package is
publish_to: 'none'. It was never on pub.dev; keep the git dependency and move itsref:tov0.4.0. currentLocation(tester)follows apush(the top of the stack). A test that asserted the old location after a push, or readcurrentConfiguration.last.matchedLocationto work around it, can now usecurrentLocation; one that expected the old value fails.- Three diagnostics read differently (folder names accept
A-Z, a hand-written family keyed by a query parameter, an optional parameter of a non-query type). Only a test that matchesfsp's text notices. - New:
const nest = false;inroute.dartmakes a route a sibling of the page above it, with a compound path (fespalier-routing). Nothing uses it unless you write it.
0.2 to 0.3: what to check
Six things can change behaviour or break the build; the full table, with what to do for
each, is in references/upgrading-0-2-to-0-3.md.
prefetchreturns aPrefetchHandleand lives until youclose()it (it lapsed after 30 s before);prefetchKeepAliveis gone. PasskeepFor:for timed behaviour.- A
transition.dartat or above a layout now animates that layout's shell too (fsp initwrites a root one, so most apps see it). Look at every layout; takebool shellintransition()to treat the shell differently. - Generated
data()providers keep Riverpod's automatic retry (no moreretry: null). Give the appProviderScope(retry: ...)a policy or setdata_retry: none; tests that count calls or leave timers will notice.DataViewalso keeps the old state on screen during a reload (keep_previous). NotFoundScopetakes a namedcaseSensitive:(hand-written scopes only).fespalier.darthides go_router's ownRouteMatchfor fespalier's; importpackage:go_router/go_router.dart(prefixed, or withhide) if you used it.router()andmount()gainednavigatorKey, and layouts are built aspageBuilderpages. Regenerate; nothing to write.
Plus new reserved names (extra as a segment; later, of, maybeOf and copyWith, since 0.5.0) and pumpRouter's default of no
retries. Everything else in 0.3.0 is additive.
Adopting fespalier in a go_router app
Mount the tree inside your router under a prefix and move routes one folder at a time:
GoRouter(
navigatorKey: rootKey,
routes: [
...legacyRoutes,
...AppRoutes.mount(at: '/shop', navigatorKey: rootKey), // pass YOUR router's key
],
errorBuilder: AppRoutes.errorPage,
)
atis the URL prefix: typed routes,uriin guards,dataAtandmatchall know it (ProductRoute(id: 2).locationis/shop/products/2; a location outside the prefix isnullfordataAt). Mount once:mountstoresatand the key in static fields.- Pass the host router's own
navigatorKey; routes usingnavigator.dartorpresent.dartneed it as theirparentNavigatorKey. mountpasses noextraCodec,restorationScopeId,observersorinitialLocation: they belong to your router. Forward unknown URLs toAppRoutes.notFound(state.uri).- Move a route = a folder with a
page.dart; aShellRoute= alayout.dart; a stateful shell = a tab layout; a routeredirect=guard.dart/redirect.dart;pageBuildertransitions =transition.dart; string paths = typed routes. - Siblings with a compound path. A folder below a page nests under it, so a deep link
to
/orders/1/refund/confirmbuilds/orders/1/refundtoo. If your tree hadGoRoute(path: 'refund')andGoRoute(path: 'refund/confirm')side by side on purpose, keep that shape withconst nest = false;inrefund/confirm/route.dart(0.4.0).
The step-by-step guide, with a compiled, tested host router, the mapping table and the
things mount does not carry, is in
references/go-router-adoption.md.
examples/adopt is that guide as a running app: the old routes beside AppRoutes.mount(at: '/shop')
in an app.dart router() under main: auto, the old URLs redirected to the typed routes,
ready() and attach() in startup.dart, the pre-adoption version kept compiled in lib/before/,
and test/parity_test.dart, which opens the same URLs in both. Read it next to the guide.
Coming from RIBs
A team that knows Uber's RIBs maps each part onto a file kind or a provider, never onto classes of the same names:
a router's attach decision is a guard.dart, an interactor is data.dart, action.dart and observe.dart, the
builder and component are the generated lib/app.g.dart and Riverpod providers, a viewless RIB is a (group)
folder, and a workflow is a URL with guards in front. The difference that matters: the location, not business logic,
decides what is on screen. The table, the tutorial app as folders and the traps are in
references/from-ribs.md; the user documentation is docs/coming-from-ribs.md.
Also
fsp initin an existing project never overwrites a file: it printsskip ... (exists).- Keep
lib/app.g.dartcommitted and adddart run fespalier genplusgit diff --exit-code lib/app.g.dartto CI:fsp checkdoes not see a stale file. - Releases are cut by release-please; each tag is a package and an
fspof the same version and takes the same steps (bump, matchingfsp, regenerate). Read the rootCHANGELOG.mdentry of that release: its "BREAKING CHANGES" first (0.3.0 has an "Upgrading from 0.2" section instead).
If fsp or flutter analyze complains after an upgrade, see
fespalier-troubleshooting.