ReArch = re-imagined approach to application design and architecture > We must state definitions and provide for priorities and descriptions of data. > We must state relationships, not procedures. > > -- Grace Murray Hopper, _Management and the Computer of the Future_ (1962)

Features

Specifically, ReArch is a novel solution to:

• ⚡️ State Management
• 🧮 Incremental Computation
• 🧱 Component-Based Software Engineering

And with those, come:

• Reactivity through declarative code
• Loose coupling and high testability
• App-level composability via a functional approach to dependency inversion
• Feature composition through side effects

In a Nutshell

Define your "capsules" (en-capsulated pieces of data) at the top level:

// Capsules are simply functions that consume a CapsuleHandle.
// The CapsuleHandle lets you get the data of other capsules,
// in addition to using a large variety of side effects.

// This particular capsule manages a count from a classic example counter app,
// using the state side effect.
(int, void Function()) countManager(CapsuleHandle use) {
  final (count, setCount) = use.state(0);
  return (count, () => setCount(count + 1));
}

// This capsule provides the current count, plus one.
int countPlusOneCapsule(CapsuleHandle use) => use(countManager).$1 + 1;

And then, if you are using Flutter, define some widgets:

// Widgets are just like a special kind of capsule!
// Instead of a CapsuleHandle, they consume a WidgetHandle.
// They also live at the top level.
@rearchWidget
Widget counterAppBody(BuildContext context, WidgetHandle use) {
  final (count, incrementCount) = use(countManager);
  final countPlusOne = use(countPlusOneCapsule);
  return Scaffold(
    appBar: AppBar(title: Text('ReArch Demo')),
    floatingActionButton: FloatingActionButton(
      onPressed: incrementCount,
      tooltip: 'Increment',
      child: Icon(Icons.add),
    ),
    body: Center(
      child: Text(
        '$count + 1 = $countPlusOne',
        style: TextTheme.of(context).headlineLarge,
      ),
    ),
  );
}

// Or, until static metaprogramming roles around:
class CounterAppBody extends RearchConsumer {
  const CounterAppBody({super.key});

  @override
  Widget build(BuildContext context, WidgetHandle use) {
    final (count, incrementCount) = use(countManager);
    final countPlusOne = use(countPlusOneCapsule);
    return Scaffold(
      appBar: AppBar(title: Text('ReArch Demo')),
      floatingActionButton: FloatingActionButton(
        onPressed: incrementCount,
        tooltip: 'Increment',
        child: Icon(Icons.add),
      ),
      body: Center(
        child: Text(
          '$count + 1 = $countPlusOne',
          style: TextTheme.of(context).headlineLarge,
        ),
      ),
    );
  }
}

Note: the @rearchWidget above requires static metaprogramming, which has not yet been released.

Getting Started

With Flutter

Simply run: flutter pub add rearch flutter_rearch

And (this part is important), wrap your application widget with a RearchBootstrapper widget in your main.dart:

void main() {
  runApp(RearchBootstrapper(
    child: MaterialApp(...),
  ));
}

Dart Only

Simply run: dart pub add rearch

And then just create one container for your application:

void main() {
  final container = CapsuleContainer();
  // Use the container.
}

Documentation

Now go take a look at the documentation!

Why ReArch?

ReArch is different than other approaches to build applications because it enables feature composition and also acts upon two key observations:

1. UI is a function of state and side effect(s).
2. State is a function of other state and side effect(s).

Accordingly, ReArch allows you to simply define functions of state + side effects for creating both state and UI, and in doing so allows you to create applications of great scale. Also because of this insight, I'd argue that ReArch is the most testable approach to building applications today. With ReArch, all of your capsule/widget code will be pure functions (despite having arbitrary side effects!), and you will never need complicated mocks.

While ReArch can be used for state management, it is also much more; it provides a solution to build any application by borrowing from the fields of component-based software engineering and incremental computation.

ReArch was also the the subject of my master's thesis.

Further, ReArch has an extremely powerful side effects system, and that is not an understatement. You will never have to wait on a new feature; you can just create a side effect! Side effects enable you to have extremely high code reuse between your state and widget logic, and allow you to think in the same manner for both.

Worth mentioning here, ReArch's persistence side effect also provides the (arguably) best mechanism to cache/persist state out of any Flutter state management framework. Don't believe me? Take a peak at the examples in the documentation.

Why not use my current solution?

If the reasons listed above are not enough for you, then here are some more reasons, based on some other popular solutions.

Credit

Giving credit where credit is due: I got the original idea for ReArch (although, it was much different back then!) after using riverpod, flutter_hooks, and functional_widget. ReArch would not have been possible if not for these stellar, role-model projects. ReArch took dozens (not an exaggeration) of design overhauls to arrive at where it is today, incorporating many ideas from these 3 pacakges along the way.

Help Wanted!

As much as I have done with ReArch, it always seems like there is more to do. One person can only do so much!

If you would like to contribute, here are some areas where I would really appreciate help!

• Documentation (especially inline!)
  • If you could add code samples/improve clarity, that would be greatly appreciated.
• Adding extension methods to AsyncValue and Option are easy "first issues"
  • See the respective source files for more on contributing there.
• New (platform-agnostic) side effects!
  • I've made many as I've needed them, but it'd be great to have more.
  • If you find yourself using a custom side effect over and over, consider making a PR! Chances are other developers can use it too.

Sponsors

You can become a sponsor of my work here!