Simple routing with GoRouter
What’s the problem?
Coming from web development, I expected navigation in Flutter to be essentially the same. I was quickly surprised to learn that navigation was (mostly) manual and required push-ing and pop-ping routes. Luckily, by the time I had “joined the chat,” go_router was popular and gave me the API that I craved.
However, it introduced some issues of its own. The problems I soon grew annoyed of were:
How to define my routes
How to build URLs for nested routes
How to enforce required path parameters at compile-time
I tried out a few different techniques that worked, some better than others, but nothing felt solid.
I was inspired by some experimentation I was doing on a project using class-based routes. After a couple weeks of playing with the idea at home and getting feedback from other Flutter devs and coworkers, I put together the first implementation of SimpleRoutes!
There have been a lot of improvements since that first version, but the main ideas remain the same.
Keep it simple
SimpleRoutes uses classes and generics to build your routes and declare their relationships.
Defining your routes,
configuring GoRouter,
and navigating.
All made as simple as possible.
Need data?
Many routes require one or more parameters. SimpleRoutes provides an API for enforcing these requirements at compile-time.
Defining your data
Define your path parameter names using Enum keys.
Enums are used to eliminate the use of “magic strings” and to standardize parameter keys used in the template interpolation.
Define a SimpleRouteData class.
Override one or more of the data properties and SimpleRoutes will inject your parameters for you:.
For path parameters, override the parameters property with a map of Enum values to Strings. This is how we interpolate your values into the path template.
There are additional properties for query parameters and extra data.
Parameters
In the example above, we override the parameters property, which is of the type Map<Enum, String> - this is how SimpleRoutes populates your path parameters.
You can also override the Map<String, String?> get query property to add (optional) query parameters - any null values will be omitted and each value will be URL encoded.
You can override the Object? get extra to inject extra data into the GoRouterState.
Last but not least, define your DataRoute class.
Your route should now extend the DataRoute class with the appropriate generic type.
This links the route to its data requirements, to be enforced by SimpleRoutes when you set up navigation (more below).
You’ll notice a couple extras in the code above.
SimpleRoutes provides helper functions to further simplify the creation and use of your routes. In this code snippet, we use the fromSegments helper to properly join together multiple path segments into one path definition, as well as the .prefixed extension on the enum key; this extension uses the Enum’s name prefixed with a colon (:), which is required by GoRouter for path parameters.
If you were to examine the path property, it would return /users/:userId.
Navigating
When navigating to a data route, SimpleRoutes will enforce the data class in a required, typed data argument in both the go and push methods.
Data extraction
SimpleRoutes provides extension methods on GoRouterState to make data extraction simple, too.
Extract path parameters using the getParam method, query parameters using the getQuery method, and “extra” data using getExtra.
A favorite pattern of mine is to use a named constructor or factory on your data class to extract data from GoRouterState.
This encapsulates all of the responsibility for managing your route’s data in one class and makes your router’s builder functions much cleaner.
But what about nesting?
All of the same functionality can be used with nested/child routes.
Any child routes should implement the ChildRoute interface, typed for their immediate parent route.
Then, override the parent property and provide an instance of that route.
This is how SimpleRoutes builds the fully-qualified path used during navigation.
Notice in the example above, the route is a DataRoute typed for its parent’s route data class. Any routes that are children of a data route must be a data route themselves. This is because SimpleRoutes needs the path parameters of its parents to construct the URL.
Because this route doesn’t require any data itself, it can re-use its parent’s data class. However, if this route required an additional parameter, we would need to construct a new data class that provided the parameters for all of its parents and itself.
Add this route to your router using the same .goPath property as every other route.
SimpleRoutes is smart enough to not append a leading slash to any child/nested routes.
