Flux in practice

A guide to building UIs with React

In my previous post, I extolled the virtues of Flux, echoing many of the points given by the Facebook engineers in their excellent F8 talk on the topic. It amounted to a high-level overview of what you might expect to find in Flux-style application, but not much more than that.

So, what does it actually mean to write an application in the Flux way? At that moment of inspiration, when faced with an empty text editor, how should you begin?

This post follows the process of building a Flux-compliant application from scratch. A full example is available here: github.com/lipsmack/flux

Initializing the application

Your basic, garden-variety Flux application comprises a series of instructions that define how data and state should flow through the system. One such instruction could be to initialize the application:

var AppDispatcher = new flux.Dispatcher();
AppDispatcher.dispatch("initialize", {
    foo: "bar"
});

This, by itself, is admittedly unremarkable, but let’s take a closer look at the ripple of events that follow this instruction:

AppDispatcher.register("initialize", function(options) {
    React.renderComponent(<AppView />, document.body);
    AppState.set(Object.assign({
        status: "initialized"
    }, options));
    return AppDispatcher.dispatch("fetchData");
});

Ok, so what’s actually going on here? By dispatching the initialize instruction, we trigger the following:

1. React binds the application root node to the document body.
2. The application state is primed with various runtime options, environment variables, and so on.
3. We dispatch and return another instruction: fetchData.

Owing to the promise-based architecture of Flux Dispatchers, the call to initialize will not resolve until fetchData has completed. This means we can keep very tight control over the lifecycle of our application. Moreover, being promises, we can chain dispatched instructions and write more expressive code. This is the full instruction chain from the sample repository:

AppDispatcher.dispatch("loadMiddleware", [
    "logger",
    "profiler"
]).then(function(middleware) {
    return AppDispatcher.dispatch("initialize", {
        middleware: middleware
    });
}).then(function() {
    console.info("Application initialized successfully");
}).catch(function(err) {
    console.error("Error initializing application:", err);
});

Let’s step through this example:

1. The first instruction is to loadMiddleware. The result of this instruction should not surprise you: some kind of module loader is invoked, and the middleware is returned. Being a promise, these modules are passed to our fulfilment handler — the first then.
2. The first instruction having been fulfilled, we then move on to initialize. As we saw above, this does some application setup and then returns the promise resolved by fetchData. This brings us to the second then.
3. Once the call to initialize has resolved, we invoke the next fulfilment handler: in this case, we simply log a success message to the console and call it a day. So what about that catch?
4. If, for any reason, one of the preceding instructions fails, the rejection handler — catch — will be notified. Due to the way promises cascade, this could be an error from any of loadMiddleware, initialize, fetchData, or anything else that is invoked along the way.

I’m sure you’ll agree that its simplicity belies its power and expressiveness — a testament to promise-driven design.

Storing application state

The purpose of the Dispatchers is to propagate instructions to other parts of the application. By themselves, they do not define how application state should behave — they are simply a mechanism for signalling intention. The application state is captured by the storage layer: a series of repositories or Stores that notify subscribers of any mutations.

var AppState = new flux.Store();
AppState.on("change", function(changeset, state) {
    console.log("Changes:", changeset);
});
AppState.set("status", "initialized");

The idea of a Store is to be a collection that encapsulates some set of values, be it some loosely connected environment variables, a single item, or a list of items. How the Store handles data internally will depend on the requirements that are peculiar to it.

In an example above, we bootstraped the application state during initialization:

AppState.set(Object.assign({
    status: "initialized"
}, options));

Mutating the state like this will trigger a change events that can be handled by our views and trigger a UI update. Indeed, this is the way that all UI changes should be heralded, as we’ll see below.

Keeping the state in check

With Flux, there is a binding contract that data must flow in a single direction: this means that the views can respond to changes in state, but cannot modify that state directly.

What follows is not a strict requirement of Flux, but is a useful way to guarantee the purity and integrity of the system: Proxies.

var ReadOnlyAppState = new flux.Proxy(AppState);

This innocuous-looking line of code performs a very important function: it turns our mutable Store into a harmless, immutable Proxy. All the events that AppState emits are echoed by the Proxy, so the views can treat these two interchangeably. Where they differ, however, is that the Proxy does not define any sort of ‘setter’ — it is a read-only abstraction.

A Flux application could easily exist without this layer of indirection, but it adds some level of guarantee to the unilateral flow of the data. With proxies in our arsenal, state-changing behaviour cannot leak into our views; changes to data and state are required to go via a Dispatcher.

Flux Proxies fulfil a similar purpose to ES6 Proxies: interceding for a specified target object and “trapping” access. In our case, the expectation is that the target object will implement the Store API.

From state to views and back again

With our newly-defined Proxy, we are ready to start notifying the views of changes to data and state. The root node for our simple application might look something like this:

var AppView = React.createClass({
    componentDidMount: function() {
        ReadOnlyAppState.on("change", function(changeset) {
            this.setState(changeset);
        }, this);
    },
    render: function() {
        return <div></div>;
    }
});

This is one half of the puzzle: trigger a view render whenever the application state is changed. But what if we want to capture a user interaction and update state accordingly? Mutating state directly is off-limits, so we need to dispatch a relevant instruction:

onClick: function() {
    AppDispatcher.dispatch("doSomething");
}

This instruction will invoke a chain of events that will cause a state change to cascade back through the system. This keeps the views clean and makes the application very easy to reason about: there is a clear separation of concerns between data and presentation.

Adhering to this approach will guarantee that state and views are decoupled, allowing for easier development and maintenance. If, at a later time, we decide to change the behaviour of any one part, nothing else in the system should be affected.

What happens next?

Remarkably, there’s not much more to a Flux application than this. Its simplicity is a little disarming, but that’s one of its greatest virtues. There are a few unanswered questions, however:

• Should you have one Dispatcher, or many? If you opt for many, how do you break them up?
• Is routing a function of state or an instruction passed to a Dispatcher? Can we use a routing library like Backbone.Router or Director?
• Should your application be a single monolith, with Dispatchers talking to a single, all-encompassing React component? Or should you create a series of scattered, loosely-related React components, each performing a single, well-defined task?

There is no real consensus to any of these, and rightly so — Flux and React are not application frameworks and they are not encumbered by especially opinionated design. However, in the posts that follow, I intend to explore some of these ideas and hopefully reach some conclusions over what makes sense in a Flux application.

Gary Chambers is a Software Engineer at Football Radar, specialising in JavaScript development. Read more about the work done at Football Radar.