Home

Octopus is a declarative router for Flutter. Its main concept and distinction from other solutions is dynamic navigation through state mutations. It is a TRULY DECLARATIVE router, where you don’t change the state imperatively using push and pop commands. Instead, you (or the user) specify the desired outcome through state mutations or the address bar, and the router delivers a predictably expected result.

Most solutions use templating for navigation, pre-describing all possible router states with hardcoding (and code generation). While this is an expected and predictable approach in traditional BE SSR (where the page is assembled server-side), it has several serious drawbacks on the client side:

1. You cannot predict all possible states in advance.
2. There is no ability to implement routes of arbitrary depth (e.g., /shop/category~id=1/category~id=12/category~id=123/product~id=1234).
3. Understanding what happens in cases with nested routes can be quite complex.
4. Loss of state in nested routes, as such routers typically display only the active route, even though the nested state continues to exist.

What does the current solution offer?

1. Changing state through mutation.
2. Nested navigation, both through the out-of-the-box solution and your custom implementation.
3. A router state machine and case implementation based on state changes. For example, it’s very easy to implement breadcrumbs or integrate a tab/sidebar with router state arguments.
4. A history of states, allowing you to implement a time machine or, after reauthentication, return the user to where they started. Or simply log this for analytics purposes.
5. A user-friendly API with a "foolproof" design, where mutable states are clear and methods for changing them are provided, and immutable states are also clearly indicated.
6. A strong focus on Guards. Since the user can now obtain any desired configuration, you might want to "clip their wings." Ensure that the "Home" page is always at the root except for logged-out users, change states during navigation or upon reaching certain conditions, for example, showing login for unauthorized users. Recheck all navigation states on a specific event, just pass the subscription to your guard.
7. Implementation of dialogs through declarative navigation. No more showing dialogs from the navigator and mixing anonymous imperative dialogs with declarative navigation.
8. Preserve and display the entire navigation tree in the URL and deep links, not just the active route!
9. Clear debugging and the representation of the state as a string will simplify development.
10. Concurrency support a out of the box.

With a declarative approach, the only limit is your imagination!