Mastering Fish Redux: Build Complex Flutter Pages with a Simple 3‑Step Process

Since November 2019 the "Baiping" app has been using Flutter together with Alibaba Xianyu's Fish Redux for state management, accumulating more than 80 page‑level features. Although the GitHub repository sees few updates, the team announced a 2.0 architecture evolution in May 2021 and released Fish_Redux 3.0 later that year, confirming ongoing internal use and optimization.

This article mainly explains two aspects of Fish Redux: 1. A brief introduction to core concepts and the "best" development workflow based on Fish Redux. 2. An in‑depth analysis of the declarative configuration assembly.

Core Concepts

Fish Redux originates from Alibaba Xianyu’s technology team and builds on the classic Redux ideas—State, Action, Reducer, Store, Middleware—exactly matching their semantics. It resolves the tension between centralized and divided state handling by automatically merging fine‑grained reducers into a master reducer.

Each component consists of three optional parts:

View : UI driven by data, dispatches events, and accesses dependencies via ViewService.

Effect : Handles side effects such as lifecycle callbacks.

Reducer : Modifies state and triggers UI refresh.

Dependencies : Declares relationships between components.

"Best" Development Workflow

Assume a UI design and a Protocol Buffer (API) definition are ready. The recommended workflow consists of three simple steps.

Step 1 – Component Splitting : Divide the page into five large components (profiles, malls, wallets, banners, tools). Each developer can work on a component independently.

Step 2 – Individual Component Development (example: tools_component) : state.dart: Define the component’s state based on the protobuf and UI. reducer.dart & action.dart: Identify mutable data, define actions and reducers. effect.dart & action.dart: Describe side‑effect events (e.g., network requests) and their actions. view.dart: Implement the UI. component.dart: Configure assembly (usually auto‑generated; unused modules like dependencies should be removed).

Step 3 – Page‑Level Assembly : user_home_page/state.dart: Define the page state using sub‑component states (e.g., ProfilesState, ToolsState) and create a connector. user_home_page/page.dart: Configure the whole page assembly.

Declarative Configuration Assembly

Fish Redux uses declarative configuration to automatically assemble View, Reducer, Effect, and the dependencies (sub‑components, middleware, adapters). Most code can be generated by the VS Code plugin; developers only need to write the dependencies section.

The dependencies function accepts two parameters: adapter: Optimizes list performance. slots: Declares sub‑components required by the page.

Example:

dependencies = (adapter, slots) {
  // configuration code
}

Registration

Register the UserHomePage with a single line of code, linking global state via connecrtExtraStore and focusing on the UserHomePage() constructor.

Page Build Process

The Page.buildPage method receives the route name and parameters, creates the store, and combines reducers:

combineReducers([protectedReducer, protectedDependenciesReducer])

The _PageWidget (a StatefulWidget) handles initState (creating the store and initializing state) and build (rendering the view).

Creating Sub‑Component Reducers

The createReducer method iterates over slots, generates sub‑reducers via connector.subReducer(logic.createReducer()), and merges them with combineReducers and combineSubReducers.

Component Rendering

The ComponentWidget (also a StatefulWidget) creates a context in initState and builds the actual UI in build.

In summary, Fish Redux provides a fully declarative, auto‑generated assembly pipeline that handles component splitting, state linking, reducer composition, and first‑render lifecycle, enabling collaborative development of complex Flutter pages.

References

[^1] Redux – https://redux.js.org

[^2] Fish Redux GitHub – https://github.com/alibaba/fish-redux

[^3] "Flutter Fish Redux Architecture Evolution 2.0" – https://mp.weixin.qq.com/s?__biz=MzU4MDUxOTI5NA==&mid=2247487235&idx=1&sn=22d1e3bd714657c7ec07f4e4def2590e

[^4] Google Protocol Buffers – https://developers.google.com/protocol-buffers

[^5] Fish Redux Example – https://github.com/alibaba/fish-redux/tree/master/example

[^6] VS Code Fish Redux Template Extension – https://marketplace.visualstudio.com/items?itemName=huangjianke.fish-redux-template

[^7] Flutter Architectural Overview – https://flutter.dev/docs/resources/architectural-overview

[^8] Flutter StatefulWidget – https://api.flutter.dev/flutter/widgets/StatefulWidget-class.html

[^9] Fish Redux Documentation – https://github.com/alibaba/fish-redux/blob/master/docs/zh-cn/README.md

[^10] Flutter Fish_Redux 3.0 Launch – https://mp.weixin.qq.com/s/YYyU2yoM61VuApz9FsUxQw