fespalier-routing
How a fespalier folder tree becomes URLs and typed routes — static, dynamic ($id), catch-all ($$rest, $$$rest) and (group) folders, _private folders, typed and enum segments, query parameters, sibling
SKILL.mdskills/fespalier-routing/SKILL.md
GitHubfespalier-routing
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 folder is the URL. A page.dart (or a redirect.dart) serves its
folder's path; every other kind decorates it. Start with
fespalier if you have not installed or generated anything yet.
Folders to URLs
| Folder | Segment | Example |
|---|---|---|
products/ |
static | /products |
$id/ |
dynamic; typed by the parameters that ask for it | /products/42 (int id) |
$$rest/ |
one or more remaining segments, a List |
/docs/a/b (docs/$$rest) |
$$$rest/ |
zero or more | /files, /files/a/b |
(account)/ |
group: shares a layout/guard/loading, adds nothing to the URL | /profile ((account)/profile) |
_components/, .x/ |
skipped: colocated code, never a route |
- A page-less folder folds into its children's paths (
greet/$name/page.dartis/greet/:name). A(group)may hold a page:(marketing)/page.dartserves/if nothing else does. - A page is the parent of the routes below it: a deep link to
/orders/1/refund/confirmbuilds/orders/1/refundunder it. To make a route a sibling of the page above instead, with a compound path, putconst nest = false;in its folder'sroute.dart(0.4.0;references/route-dart.md). - Two pages at one URL are an error (
(a)/xand(b)/x). Siblings are tried static, then dynamic, then catch-all, whatever the folder order; a page another route always catches first is an error too, and the fix is to move one into or out of its(group). fsp new 'orders/[id]'(or:id) writes$idfolders;[...rest]and[[...rest]]write the catch-alls. Unquoted$is a shell hazard.
Types come from the parameters
// data.dart in products/$id/ (and every file that asks for $id)
Future<Product> data(Ref ref, {required int id}) => fetchProduct(id);
required int id makes $id an int everywhere: the page, the guard, the
typed route, the parsing. /products/abc shows the nearest not_found.dart,
skips the guards that read segments or query parameters, and never builds the page. A segment is a String, int,
double, bool or an app enum (read by name); a catch-all is a List of
those (or num/DateTime). An optional nullable parameter (int? page,
List<String> tags = const []) is a query parameter and never leads to
not-found. Two files that disagree on a type are an error. Everything, with
samples that compile, is in
references/segments-and-types.md.
Typed routes
ProductRoute(id: 42).go(context); // or .push<T>(context), .replace(context)
const SearchRoute(q: 'ap', page: 2).location; // '/search?q=ap&page=2'
ProductRoute(id: 42).go(context, locale: 'fr'); // localized path, if route.dart has one
NoteRoute(id: 3).go(context, extra: note); // typed extra
SearchRoute.of(context).copyWith(page: 2).go(context); // since 0.5.0: the URL as state
The class is named after the page class (ProductPage becomes ProductRoute),
the folder path for a page function (OrdersOrderIdCancelRoute), or
const routeName = 'Name'; in page.dart. .location includes the mount
prefix and is always the canonical spelling. Prefer typed routes over string
paths: a renamed folder then breaks the build, not a link. A string path is allowed,
and since 0.7.0 fsp warns about a literal that matches no route
(references/typed-routes-and-extra.md).
More in
references/typed-routes-and-extra.md,
which also covers of / maybeOf / copyWith (the URL as state: read the typed
route at the current location, change one query parameter, null clears it),
extra (for pages, layouts, guards and redirects) and extra_codec.dart.
Links between pages
RouteLink(
to: ProductRoute(id: 42), // or uri: Uri.parse('/products/42')
preload: Preload.intent, // none (default) | intent | visible
onPreload: (context) => ..., // 0.9.0: what else the page needs, when the preload starts
method: LinkMethod.go, // go (default) | push | replace
builder: (context, follow) => ListTile(title: Text(p.name), onTap: follow),
)
RouteLink (0.5.0) is a link a browser understands: a real <a href> on the web
(status bar, middle click and Ctrl-click open a tab, the href carries the mount
prefix and locale: spelling), a plain widget elsewhere, and a plain click that goes
through go_router with method. Give follow to the child, or the link shows a
URL and does nothing. It carries no extra. preload: starts the data of the page it
points at (fespalier-data), and since 0.7.0 its code when the page is deferred; RouteLinkScope sets the default for the app. onPreload: (since 0.9.0) runs with the link's context when the preload starts, for what the page needs that is
not a provider, such as its image at the size it shows it (ResponsiveImage.precache,
fespalier-images). In debug a
uri: that matches no route throws. Detail, the web click path and tests:
references/links.md.
Opening the app: launches and platform links (since 0.11.0)
An adapter's launch() answers an InboundLaunch(location, source: NavigationSource.notification) (or
InboundLaunch.to(route, source: ...)); launchRouter(launch, (launch) => GoRouter(...), links: true) builds the router at
that location over the platform's initial route and marks the first navigation with the source. With links: true
(telemetry, or an adapter that has an onEnter since 0.16.0) a platform deep link, at cold start or while running, is marked NavigationSource.link; an
in-app go is not. A launch does not stop later links being marked. Android hands a cold-start link over as the initial route; iOS delivers it after the first frame, as a warm link. make receives the launch (null on the web). Never on the web. An adapter's onEnter sees it as
InboundNavigation.source, and must not block InboundNavigation.initial. The generated AppRoutes.router(launch:) calls launchRouter (links: true with telemetry, links: AppAdapters.handlesEnter with adapters alone); the generated
main passes it AppMain.launch, the adapters' answer, and a main: manual app asks AppAdapters.launch() itself. With adapters
AppRoutes.router passes onEnter: AppAdapters.handlesEnter ? onEnter : null (since 0.16.0): go_router gets AppRoutes.onEnter only if
an adapter's onEnter getter is not null (none of the first-party ones has one; before 0.16.0 any adapter made it pass one, and onEnter was a method, which
no longer compiles). Without one go_router keeps its simplest code path, and any onEnter makes go_router parse every navigation
asynchronously and apply its redirect limit to all of them, so with an adapter that has one go('/a') then push('/b') in one handler loses the go.
An app.dart router() must pass launch: AppMain.launch on (an fsp warning otherwise). Details: docs/navigation.md, "Opening the app: launches and platform links".
Platform links end to end, and a deep-link plugin (since 0.12.0). There is no deep-link package: Flutter (deep linking is
on by default since 3.27) hands the link to go_router and the router marks it link. The steps are links: in the pubspec,
fsp links (files, and the manifest and entitlements with the opt-in keys), .well-known served with no redirect, and a
device check (adb shell am start -a android.intent.action.VIEW -d <url> <package>, xcrun simctl openurl booted <url>);
a widget test calls sendPlatformLink(tester, Uri.parse(url)) from package:fespalier/testing.dart. fsp links warns
(never fails) when flutter_deeplinking_enabled is false in the manifest or FlutterDeepLinkingEnabled is false in
ios/Runner/Info.plist. A plugin such as app_links or Branch needs that switch off, and then fespalier sees no platform
link: an adapter of your own answers launch() from getInitialLink() and forwards warm links with
navigateFrom(NavigationSource.link, ...). Recipe: references/links.md, "Platform links end to end".
Notification taps (since 0.13.0). fespalier_push is an adapter (adapters: [fespalier_push]): the tap that cold-starts the
app is answered in launch() and opens the route as the initial location, a tap while the app runs is a go (or push) in
attach, both marked notification; the guards still run, and a tap delivered twice (same message id) opens once. The
package depends on no push SDK (Firebase Messaging is a recipe), has no HTTP code, never posts the token (onToken is
yours; since 0.14.0 a PushToken with a kind, a value and properties, and a revoked one is a PushTokenRevoked through onTokenRevoked, never a null) and never shows the permission prompt. The app writes a PushSource, a PushRoute (linkRoute(hosts:, matches:)
refuses //x, backslashes, foreign hosts) and one call in main() before AppMain.run():
FespalierPush.configure(source:, route:, onToken:, onTokenRevoked:); unconfigured, it reports once and does nothing. Details and the testing
recipe: references/push.md; the vendor recipes: references/push-sources.md.
Shortcuts and home-screen widgets (since 0.18.0). fespalier_launch is an adapter (adapters: [fespalier_launch]): the shortcut or the widget tap that cold-starts the app is answered in launch() and opens the route as the initial location, and a tap while the app runs is a go (or push) in attach, both marked shortcut or widget; the guards still run. The package depends on neither launcher plugin (quick_actions and home_widget are recipes), sets no shortcut and saves no widget data. The app writes one LaunchSource per plugin, a LaunchRoute (a switch over ShortcutAction and WidgetAction, with widgetLinkRoute(schemes:, hosts:, matches:) for a widget's URI, which refuses anything but an in-app path) and one call in main() before AppMain.run(): FespalierLaunch.configure(sources:, route:); unconfigured, it reports once and does nothing. Details and the testing recipe: references/launch.md; the plugin recipes: references/launch-sources.md.
A tap on a download's notification works the same way (adapters: [fespalier_download], since 0.15.0, configured with
FespalierDownload.configure(backend:, store:, route:) before AppMain.run()); the skill is fespalier-downloads, "Notification taps".
Not-found views
A not_found.dart at the root is the app-wide one (without it users see a plain
Nothing at /path); any other folder can have one, and the nearest wins, for two things:
- Unknown paths. An unknown URL shows the
not_found.dartof the deepest folder it is under (a$dynamicfolder matches any value), else the root's. That isAppRoutes.notFound(uri), which the router'serrorBuildercalls throughAppRoutes.errorPage(since 0.21.0), which shows a failed guard'serror.dartinstead when the route has one. - Unparsable segments.
/teams/a/members/abc(anintid) shows the nearestnot_found.dartabove that route; a(group)'s counts here, but a group adds nothing to the URL, so its own is never picked for an unknown URL.
It gets Uri uri and the segments of its own path as raw Strings (as the URL spells
them, decoded); no query and no data; it shows without any layout, so it brings its
own Scaffold. Two folders with one URL cannot both have one, a catch-all folder cannot
have one, and under AppRoutes.mount(at:) the prefix is skipped when looking for the folder
(a URL outside it gets the root's). fsp new members --not-found scaffolds one.
The other routing files
| Need | File and reference |
|---|---|
| Paths match in any case, or one folder stays exact | route.dart with caseSensitive: references/route-dart.md |
/produits and /produkte for /products, one route |
route.dart with paths, locationFor, locale:: same reference |
Texts in the URL's language, a language menu (fespalier_tolgee, 0.10.0) |
fespalier-i18n |
| A page must start again (fresh state) when its URL changes, not keep it | route.dart with const remount = Remount.onSegments; or the pubspec's remount (0.6.0): same reference |
| A page's code must be a chunk of its own on the web, loaded on demand | route.dart with const deferred = true; or the pubspec's deferred (0.7.0): same reference |
A deep link must not build the page above (refund under refund/confirm) |
route.dart with const nest = false; (0.4.0): a sibling with a compound path, same reference |
| A page full-screen above the tab bar, URL still under its parent | navigator.dart: references/navigators-and-present.md |
| A sheet or dialog page class of your own, with a URL | present.dart: same reference |
| Ask before a page goes (unsaved changes), Android back and the iOS swipe too | leave.dart (0.11.0): references/leaving-a-page.md |
A route that only forwards (/old-products/3 to /products/3) |
redirect.dart (fespalier-guards) |
| Every route's path, groups, layouts, params and your own metadata at runtime | meta.dart and AppManifest: references/manifest-and-meta.md |
| A notification tap that opens a route, cold start and warm | fespalier_push (0.13.0): references/push.md, references/push-sources.md |
| A shortcut or home-screen widget tap that opens a route, cold start and warm | fespalier_launch (0.18.0): references/launch.md, references/launch-sources.md |
| A link that shows its URL, opens in a tab, and preloads the page's data | RouteLink, RouteLinkScope (0.5.0): references/links.md |
Behaviours worth knowing before you debug
replaceandpushon the web (since 0.6.0):ProductRoute(id: 1).replace(context)puts its location in the address bar and replaces the history entry (over a page that was pushed it keeps the stack instead). Apushstays out of the address bar unless the pubspec haspush_updates_url: true(a reload then builds that URL's own stack). On 0.5.0 usegofor URL state. Seereferences/typed-routes-and-extra.md.pushReplacement(since 0.7.0):ProductRoute(id: 1).pushReplacement<T>(context)is go_router's: a new page key, so a sheet handing over to a full page does not keep the sheet's state or transition (over a pushed pagereplacekeeps the key; over a page of the declarative stack it is ago, which keeps it only for the same path template). The replaced page's own future never completes, and when it was the only page, neither does this one. Takeslocale:and, where the route has one,extra:.- Trailing slashes are dropped by go_router:
/products/reaches/products. Nothing to configure. - Case is sensitive by default.
case_sensitive: falsein the pubspec, or aroute.dartper folder (nearest wins), emitscaseSensitive: false. The requested case is kept in the router's location; onlystate.matchedLocationis spelled by the route. - A deferred page (0.7.0,
const deferred = true;in aroute.dart) shows the nearestloading.dartwhile its code loads on the web anderror.dartif that fails; once loaded it builds synchronously. Onlypage.dartis deferred, layouts never are, and a type (an enum, anextraclass) declared in a deferred page.dart is an error. A test that pumps its own router needsawait tester.runAsync(AppRoutes.loadDeferred);(pumpRouterdoes it). - A page keeps its state when only its parameters change (
/c/1to/c/2): go_router keys it by the path template.remount(0.6.0) changes that per folder or app-wide; the default isnever. - Localized paths are one
GoRoutewith an alternation, not one route per locale, so nested routes, page keys and restoration ids see one route. Read the route'spathsthroughRouteInfo, neverpathParameters(_l0). Since 0.10.0fespalier_tolgeereads these spellings (localeSpelling(AppManifest.all),relocate) and takes the locale from the route (a$langenum segment, or the spellings); the texts arefespalier-i18n. - A page on a tab's first route cannot have a
:segmentin its own path (go_router refuses): give the tab atabOptionsinitialLocation(fespalier-layouts). AppRoutes.mount(at: '/x', navigatorKey: hostKey)stores its arguments statically; pass the hostGoRouter's own key whenever a folder usesnavigator.dartorpresent.dart.fsp routesprints every route with its tags; run it before guessing which file serves a URL.
If fsp complains, look the message up in
fespalier-troubleshooting.