When it comes to implementing a url-based Router (aka Nav2) there are really 2 high-level components to the API:

• A controller to read/write to the current url
• A parsing/matching system to convert a url into a stack of views, or pages.

The interesting thing here, is that the controller portion, is a fairly stable, boring API. Reading or writing the url location, or accessing queryParams is all pretty straight-forward. Really all you are doing here is setting a string value, and parsing query params using the URI class.

On the other hand, the parsing system has a near infinite number of permutations. As seen in libraries like RouteMaster, GoRouter, VRouter, Beamer, any number of interesting abstractions can be crafted to declaratively parse a url, and render some stack of page objects.

As a developer this can be a little frustrating as it feels like there is no middle ground. In order to gain even basic control of the url location, we are forced to choose a controller that is coupled to some opinionated parsing schema, (or write our own Router from scratch). These parsing schemas themselves are often significantly more complex than the underlying controller API and can obfuscate the basic functionality you’re interested in.

Given this, we thought it would make sense to create a library that handles _only_ the controller portion of a Router, and delegates the location parsing up to the developer.

Introducing url_router 

UrlRouter makes no assumptions about your UI layout. How you react to router.url is up to you. Your UI could be a single page desktop style app, that parses the url inside of it’s main view:

late final router = UrlRouter(
  onGeneratePages: (router) => [
    // Main view will handle this url internally
    MaterialPage(child: MainView(router.url)),
]);

@override
Widget build(BuildContext context) => MaterialApp.router(
  routeInformationParser: UrlRouteParser(),
  routerDelegate: router,
);

Or maybe you build a stack of pages with simple string parsing if your app is quite simple:

late final router = UrlRouter(
  onGeneratePages: (router) {
    return [
      MaterialPage(child: MainView()),
      if(router.url == '/settings')... [
         MaterialPage(child: SettingsView()),
      ]
    ];
  },
);

Controlling Url

UrlRouter offers a small but powerful API to control the url:

Access the UrlRouter anywhere in your app, using UrlRouter.of(context), or use the context extensions:

• context.url
• context.urlPush
• context.urlPop
• context.urlRouter

Finally UrlRouter handles redirects, protected routes as well as builder which allows you to wrap UI around the navigator stack:

late final router = UrlRouter(
  onGeneratePages: ...,
  // Optional, protect or redirect urls
  onChanging: (router, newUrl) {
    if (authorized == false) return '/';
    return newUrl;
  },
  // Optional, wrap some outer UI around navigator
  builder: (router, navigator) {
    return Row(
      children: [ 
          const SideBar(), 
          Expanded(child: navigator) 
      ],
    );
  },

);

Small is good

That’s it! That is the entire API. What is so nice about this approach is that the actual implementation of the Router becomes extremely simple, weighing in at only around 120 lines of code for the entire delegate and less than 10 lines for the route information parser. This keeps the bug-surface very small, and the overall api can be quickly grokked.

Who’s it for / What’s the point?

To be clear: if you are looking for a full turn-key “routing system”, you may want to look into one of the other packages mentioned above. There are many options, all with different flavors, and you’re likely to find one that you like.

This package is primarily designed for the developer who would like to roll their own route-matching code, and does not want to deal with the complexity of learning someone else’s system. It provides full control of the url to you, and allows you to layout your app tree accordingly.

This can also just serve as a nice stepping stone for a developer who is currently using onGenerateRoute (or MaterialApp.routes) but they want functional back buttons on the web.

A last set of developers who may be interested are those who are creating their own route-matching libraries, but who do not want to re-invent the controller layer. url_router could easily be wrapped up to serve that purpose.

If you found the package useful, or have any issues, please let us know!