So far you’ve seen how:

1. Relay lets you say what data you need with GraphQL in part 1
2. Relay fetches data from the server in part 2
3. Relay syncs changes back up to the server in part 3

Now let’s see how all the different parts work together.

Caveat: this is only an approximation

In the cartoons up until now the scale of the diagrams has been 1:1… each arrow has (pretty much) represented a single function call.

For these diagrams, the scale is closer to 1:100. This is because Relay is doing so much for you.

Flux is a pattern. Relay is a framework. Flux just gives you guidelines on how to structure your application. Relay gives you concrete functionality. And lots of it.

This means that the number of different parts in the system has ballooned.

From the diagrams, it could look like implementing something with Relay requires a lot more work. The truth is, these extra characters take care of a lot of work for you. They are responsible for the magic.

You don’t really need to know every detail of what they do. In fact, there’s only a small number of parts that you even need to be aware of.

But cracking things open and seeing how they work is the fun part! So I’m going to try to give you a rough approximation of Relay’s inner workings.

The chorus line of characters

Even leaving out some of the lesser cast members, there are still a bunch of them. In my head, I divide them into 4 groups.

The user interface

The user interface takes the data from the system and makes it understandable to the user. It also gives the user a way to change that data. It takes user input and turns it into something the system understands.

The parts of the user interface are:

The root container — Kind of like the root component in Redux, the root container is a CEO. It chooses the top level component to use for the page. It also tells the app where in the graph to start the query. But after that, it’s pretty hands off.

Containers — The container is like a project manager for the component. It has a list of all of the data the component needs to do its job. The container is on top of getting the data from the rest of the system. This allows the component to focus on its job.

Components — A component in Relay is pretty much the same as it is in Flux. It is a presenter. It just knows how to format data into output that people understand (via HTML).

Relay Renderer — In some ways, the Relay Renderer is like the view layer binding from Redux. Like an IT department, it hooks up the container to the store.

Mutations —You saw mutations in part 3. They are like action creators in Flux, but they do more. They provide blueprints for the mutation system to follow for different user changes.

Data storage

Data storage is handled by the store. Even though I’m only representing it as one character here, there are many different objects involved.

The UI talks to it whenever it wants data. It works with the query and mutation systems to make sure it has the data that the UI needs. The store also has a notification system. Each component gets custom-tailored updates when data it uses changes. The store handles all of the details of wiring up these notifications, so you don’t have to think about it.

The query/mutation systems

The query and mutation systems prepare queries. They also keep track of what queries have gone out and what data needs to come in for a query to be complete. You met them in part 2 and part 3.

The cloud

Two characters sit on either side of the cloud: the server on one side and the network layer (which is on the client) on the other.

The server — As you saw in part 1, the GraphQL server is like a librarian. It isn’t the library; it doesn’t actually store the information. You tell the GraphQL server what information you need, and it figures out where to go in the stacks to get that information for you.

The network layer—The network layer manages all communication with the server. It is like an operator in The Matrix. It is responsible for getting requests into the cloud and making sure responses get out of the cloud. If the response doesn’t come out of the cloud correctly, the operator will retry twice before pulling the plug. It also handles errors.

The first render

Let’s see what happens when your app is first loaded.

Step 1: Starting the process

When the page is loaded, React starts rendering. The first thing it reaches is the root container. The root container passes off responsibility to Relay Renderer.

Relay Renderer is in charge of making sure the data is available to the UI. But because the app isn’t mounted, it knows that none of this data is available. It tells the store to start priming the cache.

Step 2: Priming the cache

The store needs to know what data to get for the cache. Relay Renderer figures out what the starting point for the query is (the query root) and passes it to the store. It also gives the store a callback.

The store passes those off to the query system. Then the query system works with the store to figure out what data is already in the cache. We looked at this in part 2.

Step 3: Building the query

The query system builds the query.

I didn’t show this in part 2, but the query system talks to the containers here. It asks them what data they need. Each container passes off a query fragment which specifies the data its component needs.

The query system stitches together the full query out of all of these fragments.

Step 4: Trimming down the query and queuing it up

As we saw in part 2, the query system removes pending requests from the query. Then it adds the query to the queue of requests for the network layer to send out (and also adds it to its own list of pending requests).

Note: things start to go a little asynchronous here. I don’t have a good way to show this in the diagrams.

The query system is done with it’s work for now. It queues up a message for the Relay Renderer with the ready state. But first, the network layer needs to do it’s job…

Step 5: Sending the query to the GraphQL server

The network layer picks up the queue of requests that the query tracker left for it. It sends the requests off to the GraphQL server.

The network layer has nothing else to do ‘til the server responds. It lets the rest of the system do its thing while it waits.

The message that the query system put in the queue is sent. The Relay Renderer gets the ready state.

Step 6: Getting the data back and writing it to the cache

The network layer hears back from the GraphQL server. It transforms the response to JSON. Then the query system picks it up and passes it off to the store. The store adds it to the local cache.

Step 7: Notifying the renderer

Once the data is written to the cache, the query system is notified. It sends out the message to Relay Renderer with a new ready state, letting the Renderer know that the cache is primed and ready to go.

Relay Renderer will then prepare an object that the containers can use to get their data from the store. It calls setState(), passing this object down to the containers.

Step 8: Getting the data from the store to the UI

Using the object that Relay Renderer passed down, the container will set up a “resolver”. It will use the resolver to get its data from the store.

Note: This is handled automatically in the container prototype’s componentWillMount() implementation.

During this process, the store also sets up some observers. These observers will notify the resolver, which will notify the container, whenever this data has changed.

Now that the container has the data, it calls setState() to pass it down to the component.

So that’s how I think about all the different parts of Relay. Hope it helps!

Did this help? If it did, a click on the ♥ is much appreciated… it helps other people find it, too!

Resources

1. GraphQL docs
2. Relay docs
3. Talk at React.js Conf January 2015
4. Exploring GraphQL
5. GraphQL and Relay with Nick Schrock
6. From REST to GraphQL
7. Falcor with Jafar Husain
8. Relay: An Application Framework for React
9. Scaling UI Development with Relay

A cartoon guide to Facebook’s Relay, part 4 was originally published in Code Cartoons on Medium, where people are continuing the conversation by highlighting and responding to this story.

Relay is the same as Flux and Redux in a way. All three of them use objects to represent changes. When a change object comes through to the store, the store will make the change in the state. Then the store will notify the UI to update.

Unlike Flux and Redux, Relay pushes the change up to the server, too.

Sometimes changes aren’t simple, though. They can ripple out and have effects that aren’t so obvious.

For example, take adding new content. It could have impacts on other parts of the graph, too.

Balancing speed and consistency

How do you 1) show all of the changes, but 2) do it as quickly as possible?

To show all the changes, you could just refetch the whole graph… but that would be slow. Or you could just fetch the one change you made… but then the data isn’t consistent with what’s on the server.

Relay balances these two — speed and consistency. It does that by figuring out exactly what data it needs to update.

It will also make the change seem to happen faster by doing an “optimistic update”. This is where the app guesses what the new state will be before the server responds. When the server response does come in, it will make any necessary changes.

Here’s the sequence of events:

1. Relay updates the local cache with what it thinks the new state is going to be (an “optimistic update”… I’ll explain how it figures this out later).

2. It sends up the mutation query to the server. It also sends a query graph that requests data from the server. Once the server makes the update, it will fill in that query graph and return it as the payload.

3. The store will merge the payload into the graph it already has cached. If the optimistic update in step 1 was incorrect, those changes will be overwritten here.

Relay manages all this by introducing another new system, the mutation system.

Introducing mutations & the mutation system

Mutations are the Relay version of the actions you see in Flux or Redux. Instead of having an action type that comes from a list of constants, the Relay mutation has a name which comes from the list of mutations the server understands.

A mutation object knows its mutation name. And, like an action creator, it knows how to prepare the input… the variables the server will need to make the change.

But it does more than an action creator in Flux or Redux does.

The mutation

I think of the mutation as an architect. It provides a set of blueprints for different things.

It provides a blueprint for the fat query. This is a list of the fields that might change in response to the mutation. It can also provide a blueprint for optimistic updates.

When data comes back from the server, it provides a blueprint for how the store’s data should change in response to the mutation. The blueprint guides the store in figuring out how to change fields or delete data.

This set of blueprints is handed off to the mutation system.

The mutation system

The mutation system is like a contractor carrying out and directing the work on that set of blueprints.

It takes the blueprint for the fat query and compares it to the graph of data that the app is currently using, called the tracked query. It figures out which data needs to be refreshed. If a property is in both graphs, it gets added to the mutation request.

Note: The mutation defines this fat query, not the component. This means even if a seemingly unrelated component has made a change, if it impacts another component’s data, all of the changed data will still be fetched from the server. This is great because you get consistency without coupling components together.

If the mutation has a blueprint for an optimistic update, it carries that out.

How the store and mutation system team up

Just as the store works with the query system for fetching data, it works with the mutation system for changing data.

1. The UI passes a mutation object to the store.

2. The store passes the mutation to the mutation system.

3. The mutation system figures out what the optimistic update should be. It tells the store to update the cache with that data.

4. The store writes the data and sets up a broadcast to fire later. That broadcast will let the UI know that there is new data to show.

5. The mutation system compares the fat and tracked queries to figure out the smallest bit of data that the server needs to send down. It sends the request, which includes the change to make and the query.

6. The broadcast that the store set up in step 4 goes out. The UI requests the data that the optimistic update changed.

7. The mutation system receives the payload. It passes it to the store, which updates the cache. Then it queues up another broadcast to the UI.

8. The UI gets the new data from the store.

So that’s how I think of mutations and data syncing in Relay. Hope it helps!

Did this help? If it did, a click on the ♥ is much appreciated… it helps other people find it, too!

Coming up next…

See how it all fits together in part 4.

Resources

1. GraphQL docs
2. Relay docs
3. Talk at React.js Conf January 2015
4. Exploring GraphQL
5. GraphQL and Relay with Nick Schrock
6. From REST to GraphQL
7. Falcor with Jafar Husain

A cartoon guide to Facebook’s Relay, part 3 was originally published in Code Cartoons on Medium, where people are continuing the conversation by highlighting and responding to this story.

GraphQL gives you a way to say what part of a graph you need, as you saw in part 1.

Relay makes the connection between the graph in the cloud and the graph that the user is interacting with on the page.

Relay can automate:

1. downloading the bits of the graph that you need and caching them
2. making future requests for data smaller
3. figuring out which parts of the graph you really need right now, and which you can wait for

It also automates syncing any changes to the graph back up to the server. We’ll cover this in part 3.

Downloading and caching

The UI doesn’t talk to the server directly. Instead, it gets all of the data from the store, which has a local cache of the data.

When the page loads initially, the UI will ask the store to prime the cache. This will pull down the data from the server. Then the UI can do it’s first render.

1. First, the system needs to figure out what data to get from the server. It gathers all of the query fragments from the components that will be shown. Then, it stitches those together into a single graph. That graph query is requested from the server.
2. The server responds by filling in the part of the graph described by the query with the actual data. The data is added to the local cache.
3. The UI gets a notification that the data is ready and in the cache (more about this below). The UI asks the store for the data and renders it.

Making queries smaller

Now we have data in the cache. Because of this, Relay can make future queries smaller.

1. The system figures out what parts of the query it already has and what parts it needs.
2. The part that is already cached is removed from the query. Then the reduced graph query is sent to the server.
3. The little bit of the graph that was missing is returned from the server. The store merges it into the local cache. The UI is notified that the data is in, and it asks the store for the data.

Deferring queries

Sometimes, you have two kinds of data needs. Some data needs to be fetched immediately to render the page, and other data that can come in later.

For example, on a news article the article body needs to be rendered immediately. But comments, which aren’t really that important, can be rendered a few seconds later.

In theory, Relay makes it possible to split up the queries. When the required data comes in, the page will render. When the deferred data comes in, it will be added to the page.

1. The query graph is split up based on whether the properties are deferred. The deferred query is marked as dependent on the required query.
2. The server responds with the required data. The UI renders the page with that data.
3. The server responds with the deferred data. The UI updates the page with the data.

Note: While Relay itself can handle deferred queries, there is a piece of the puzzle missing. Facebook’s GraphQL server can handle dependencies between queries, but for simplicity’s sake they didn’t add it to the GraphQL spec. They do plan to make it possible though, and you can follow the issue.

To do these things, Relay introduces a new character — the query system.

Introducing the query system

The query system is in charge of figuring out what data to fetch. It works together with the store to figure out the smallest queries that it can send.

I think of the query system as a bike messenger who’s obsessed with efficiency. Before sending a query, it checks what data is in the store. It won’t ask the server for data the store already has.

It will even go above and beyond to make the query smaller. It checks what data is supposed to come in from pending requests. Instead of sending a concurrent request for the same data, it will just clip away parts that it expects to come in from the pending requests.

How the store and query system team up

The query system is just a small part of Relay. I’ll cover the rest of the characters later. But I think it’s helpful to get a detailed view of how the query system works with the store to automate data fetching, and how the two talk with the server and the UI.

Note: Everything in this cartoon is automatically handled by Relay. So you don’t technically need to know how this works. But it’s more fun when you do!

Here’s an example of the interaction between these two.

1. The UI asks the store to fill up the cache. Specifically, it asks for the data that is needed for the first render.

2. The store delegates this to the query system.

3. The query system tries to make the query as small as possible.

4. The query system sends the query off. It adds it to the list of requests that are pending.

5. In the meantime, the query system wants to let the UI know what’s going on.

It sends a ready state message to the UI (it does this with a callback that the UI passed to the store, and the store passed to it). In the ready state message, the ready property is set to false since the data hasn’t come in yet.

6. When the query results come back, the query system sends them to the store. It also removes the request from the list of pending requests. The store adds the results to the local cache.

7. The query system lets the UI know that it can get the data from the store.

8. The UI asks the store for the data. The store gives it the data and also sets up some observers. These will be used to target updates to specific components when new data comes in.

So that’s how I think of data fetching in Relay. Hope it helps!

Did this help? If it did, a click on the ♥ is much appreciated… it helps other people find it, too!

Coming up next

Syncing changes back up to the server with Relay.

Resources

1. GraphQL docs
2. Relay docs
3. Talk at React.js Conf January 2015
4. Exploring GraphQL
5. GraphQL and Relay with Nick Schrock
6. From REST to GraphQL
7. Falcor with Jafar Husain

A cartoon guide to Facebook’s Relay, part 2 was originally published in Code Cartoons on Medium, where people are continuing the conversation by highlighting and responding to this story.

The last two cartoons covered Flux and Redux. Those are data handling patterns to keep your UI in sync. When a user interaction happens, they update the state and trigger rerendering.

But where’s the cloud? How do you get the data that a component needs from a server, and then update the server when the user makes changes?

The Flux docs don’t tell you were to put this. Even at Facebook, different teams add it in different parts of the app. Redux gives you a single place to do it (middleware), but it still requires effort to wire it up.

Relay takes care of this problem. It makes it easy to fetch data from the server as part of your data flow. In order to do this, Relay needs to know what data each component needs from the server. This is where GraphQL comes in.

So let’s look at GraphQL. But first…

What is a graph?

You might think of a graph as the same thing as a chart, or the graphs you made on a graphing calculator. That’s not the kind of graph we’re talking about.

The kind of graph we’re talking about is a group of things that are connected to each other by relationships. These things and relationships have special names in graph theory. The things are called nodes and the relationships between them are called edges.

If that sounds unfamiliar, just think of a property chain. For example, user.friend[0].attending[0]. That’ another way of thinking about the same graph.

If you look at an app like Facebook, a graph is the most natural way to think about the data. There are lots of things, and lots of relationships between those things.

When you pull up a page on Facebook, it’s showing you a particular view of that graph. And each component on the page shows you a small slice of the graph.

So how do you make the connection between a component and the small section of the graph that it displays?

This is what GraphQL does. It makes it possible to indicate the small section of the graph that you want. This small section is called a fragment. The fragments combine to create a larger query.

Relay piggybacks on this capability—being able to combine multiple fragments into a larger query — to solve a problem.

The problem

So what is the problem that Relay solves using GraphQL?

When you build React components, it’s easy to reuse them across different parts of your site. This is one of the main benefits of React. It’s called composability.

If your component needs to use data from the server, though, it gets harder to just drop a component in place. The server needs to know what properties the component needs. In many apps, this will be hard-coded on the server. There will be a URL (called an endpoint) that passes down data for that particular view. The endpoint code will know exactly what properties its view needs.

The problem here is that whenever you add (or remove) properties from the component, you have to change the server code too. This is called coupling; when you change one, you have to change the other, too.

Because you have to manually keep these two in sync, it makes bugs and obsolete code more likely.

• Bugs come from underfetching data. You don’t pull down the properties that you need for a component because you forgot to add them to the server.
• Obsolete code results in overfetching data. For example, let’s say you remove a component from the tree. Do you delete its properties from the server response? How can you be sure another component doesn’t use that endpoint and need those properties? Instead, it’s better to just keep them in the response… but then you have a lot of cruft lying around.

The solution: declarative data fetching

With GraphQL, you don’t hard-code the server with the list of properties that your view needs. Instead, the component provides a list of what it needs to the server.

This list is combined with the lists from other components. The structure of the combined list is a tree, just like the component tree. It gets handed off to the endpoint. There’s only one endpoint and it handles all requests.

The nice thing about this is that it localizes changes. When you need to add or remove a property, you only need to change the component… not the server.

What GraphQL looks like

To make this work, each component needs to provide the list of properties that it needs from the server. This is the query fragment. Relay will figure out which components are going to render and will get the query fragments for them. It will compile these into a single query — a consolidated list of properties that it needs from the server.

This turns into a query like this:

query {
  user(id: 5) {
    friends(first: 3) {
      picture
      name
      location
    }
  }
}

This consolidated query is kind of like a questionnaire. The client has laid out all of the questions it wants the server to answer, and the server just needs to fill in the blanks.

One important thing to note: GraphQL doesn’t actually store your data. It just gives you a language to ask for data.

If your database is the public library, then GraphQL would be the librarian. It just listens to your request and figures out what you want. Then it goes around to the different bookshelves and finds the data that you asked for. The bookshelves in this analogy are the tables of your database, or whatever you are holding your data in.

This means you can use GraphQL on top of all sorts of different backends; an existing MySQL database, a NoSQL database like MongoDB, or even on top of regular text files.

For each property in the query, the server will have a resolve() function. This is where GraphQL figures out the value and fills in that question on the questionnaire, computing a value or querying a database.

There’s a lot more to GraphQL, but this is enough to get started with Relay. Let me know on Twitter if you’d like to see a GraphQL deep dive in the future.

Coming up next…

There’s more work to do than just splitting up the query. That’s where Relay comes in. I’ll cover that in part 2.

Did this help? If it did, a click on the ♥ is much appreciated… it helps other people find it, too!

Resources

1. GraphQL docs
2. Relay docs
3. Talk at React.js Conf January 2015
4. Exploring GraphQL
5. GraphQL and Relay with Nick Schrock
6. From REST to GraphQL
7. Falcor with Jafar Husain

Thank you to all of my reviewers on this series: Kent C. Dodds, Lee Byron, Steven Luscher, Tim Yung, and Sebastian Siemssen.

A cartoon guide to Facebook’s Relay, part 1 was originally published in Code Cartoons on Medium, where people are continuing the conversation by highlighting and responding to this story.

One thing that causes even more confusion than Flux is the difference between Flux and Redux, a pattern that was inspired by Flux. In this article I’ll explain the differences between the two.

If you haven’t read the last article about Flux, you should do that first.

Why change Flux?

Redux solves the same problems as Flux, plus some.

Just like Flux, it makes state changes in apps more predictable. If you want to change state, you have to fire off an action. There’s no way to change the state directly because the thing holding the state (the store) only has a getter, not setters. These basics of Flux and Redux are pretty similar.

So why a different pattern? Redux creator Dan Abramov saw an opportunity to improve on Flux. He wanted better developer tools. He saw that if you moved a couple of things around, you could make better developer tools possible, but still have the same predictability that Flux gives you.

He wanted hot reloading and time travel debugging (there’s another cartoon to explain these). But there were some problems which made developer tooling hard to do with Flux.

Problem 1: The code for stores can’t be reloaded without wiping out the state

In Flux, the store contains two things:

1. The state change logic
2. The current state itself

Having these two on the same object is a problem for hot reloading. When you reload the store object to see the effect that the new state change logic has, you lose the state that the store is holding on to. Plus, you mess up the event subscriptions that tie the store to the rest of the system.

Solution
Separate these two functions. Have one object that holds on to the state. This object doesn’t get reloaded. Have another object that contains all of the state change logic. This object can be reloaded because it doesn’t have to worry about holding on to any state.

Problem 2: The state is being rewritten with every action

In time travel debugging, you keep track of each version of a state object. That way, you can go back to an earlier state.

Each time the state is changed, you need to add the old state to an array of previous state objects. But because of the way JavaScript works, simply adding the variable to the array won’t work. This doesn’t create a snapshot of the object, it just creates a new pointer to the same object.

To make it work, each version needs to be an entirely separate object so that you aren’t accidentally changing past versions.

Solution
When an action comes in to the store, don’t handle it by changing the state. Instead, copy the state and make changes to the copy.

Problem 3: There aren’t good places for third-party plugins to jump in

When you’re making developer tools, you need to be able to write them generically. A user should be able to just drop the tool in without having to custom fit their own code around it.

For this to work, you need extension points… places where the code expects to have things added to it.

An example is logging. Let’s say you want to console.log() every action as it comes in, and then console.log() the state that results from it. In Flux, you’d have to subscribe to the dispatcher’s updates and to updates from each store. But that’s custom code, not something a third-party module can easily do.

Solution
Make it easy to wrap parts of the system in other objects. These other objects add their bit of functionality on top of the original. You can see these kinds of extension points in things like “enhancers” or “higher order” objects, as well as middleware.

In addition, use a tree to structure the state change logic. This makes it so the store only emits one event to notify the views that the state has changed. This event comes after the whole state tree has been processed.

Note: With these problems and solutions, I‘m focusing on the developer tooling use case. These changes help in other use cases, too. On top of that, there are other differences between Redux and Flux. For example, Redux also reduces boilerplate and it makes it easier to reuse logic in the store. Here’s a list of some other upsides to Redux.

So let’s see how Redux makes these things possible.

The new cast of characters

The cast of characters changes a little bit from Flux to Redux.

Action creators

Redux keeps the action creator from Flux. Whenever you want to change the state of the application, you shoot off an action. That’s the only way that the state should be changed.

As I said in the article on Flux, I think of the action creator as a telegraph operator. You go to the action creator knowing basically what message you want to send, and then the action creator formats that in a way that the rest of the system can understand.

Unlike Flux, action creators in Redux do not send the action to the dispatcher. Instead, they return a formatted action object.

The store

I described stores in Flux as over-controlling bureaucrats. All state changes must be made personally by a store and have to go through the action pipeline, instead of being requested directly. The store in Redux is still controlling and bureaucratic, but it’s a little bit different.

In Flux, you can have multiple stores. Each store has its own little fiefdom, and it is in total control. It holds on to its little slice of state, and has all the logic for changing that little slice of state.

The Redux store tends to delegate more. And it has to. In Redux, there is only one store… so if it did everything itself, it would be taking on too much work.

Instead, it takes care of holding on to the whole state tree. It then delegates the work of figuring out what state changes need to happen. The reducers, headed up by the root reducer, take on this task.

You might have noticed there’s no dispatcher. That’s because, in a bit of a power grab, the store has also taken over dispatching.

The reducers

When the store needs to know how an action changes the state, it asks the reducers. The root reducer takes charge and slices the state up based on the state object’s keys. It passes each slice of state to the reducer that knows how to handle it.

I think of the reducers as a department of white-collar workers who are a little overzealous about photocopying. They don’t want to mess anything up, so they don’t change the state that has been passed in to them. Instead, they make a copy and make all their changes on the copy.

This is one of the key ideas of Redux. The state object isn’t manipulated directly. Instead, each slice is copied and then all of the slices are combined into a new state object.

The reducers pass their copies back to the root reducer, which pastes the copies together to form the updated state object. Then the root reducer sends the new state object back to the store, and the store makes it the new official state.

If you have a small application, you might only have one reducer making a copy of the whole state object and making its changes. Or if you have a large application, you might have a whole tree of reducers. This is another difference between Flux and Redux. In Flux, the stores aren’t necessarily connected to each other and they have a flat structure. In Redux, the reducers are in a heirarchy. This hierarchy can have as many levels as needed, just like the component hierarchy.

The views: smart and dumb components

Flux has controller views and regular views. The controller views act as middle managers, managing the communication between the store and their child views.

In Redux, there’s a similar concept: smart and dumb components. The smart components are the managers. They follow a few more rules than the controller views, though:

• Smart components are in charge of the actions. If a dumb component underneath them needs to trigger an action, the smart component passes a function in via the props. The dumb component can then just treat that as a callback.
• Smart components do not have their own CSS styles.
• Smart components rarely emit DOM of their own. Instead, they arrange dumb components, which handle laying out DOM elements.

Dumb components don’t depend on action files directly, since all actions are passed in via props. This means that the dumb component can be reused in a different app that has different logic. They also contain the styles that they need to look reasonably good (though you can allow for custom styling — just accept a style prop and merge it in to the default styles).

The view layer binding

To connect the store to the views, Redux needs a little help. It needs something to bind the two together. This is called the view layer binding. If you’re using React, this is react-redux.

The view layer binding is kind of like the IT department for the view tree. It makes sure that all of the components can connect to the store. It also takes care of a lot of technical details so that the rest of the hierarchy doesn’t have to understand them.

The view layer binding introduces three concepts:

1. The Provider component: This is wrapped around the component tree. It makes it easy for the root component’s children to hook up to the store using connect().
2. connect(): This is a function provided by react-redux. If a component wants to get state updates, it wraps itself using connect(). Then the connect function will set up all the wiring for it, using the selector.
3. selector: This is a function that you write. It specifies what parts of the state a component needs as properties.

The root component

All React applications have root components. This is just the component at the top level of the component hierarchy. But in Redux applications, this component takes on more responsibility.

The role it plays is kind of like a C-level executive. It puts all of the teams in place to tackle the work. It creates the store, telling it what reducer to use, and brings together the view layer binding and the views.

The root component is pretty hands-off after it initializes the app, though. It doesn’t get caught up in the day-to-day concerns of triggering rerenders. It leaves that to the components below it, assisted by the view layer binding.

How they all work together

Let’s see how these parts work together to create a functioning app.

The setup

The different parts of the app need to be wired up together. This happens in setup.

1. Get the store ready. The root component creates the store, telling it what root reducer to use, using createStore(). This root reducer already has a team of reducers which report to it. It assembled that team of reducers using combineReducers().

2. Set up the communication between the store and the components. The root component wraps its subcomponents with the provider component and makes the connection between the store and the provider.

The Provider creates what’s basically a network to update the components. The smart components connect to network using connect(). This ensures they’ll get state updates.

3. Prepare the action callbacks. To make it easier for dumb components to work with actions, the smart components can setup action callbacks by using bindActionCreators(). This way, they can just pass down a callback to the dumb component. The action will be automatically dispatched after it is formatted.

The data flow

Now that the application is set up, the user can start interacting with it. Let’s trigger an action to see the data flow.

1. The view requests an action. The action creator formats it and returns it.

2. The action is either dispatched automatically (if bindActionCreators() was used in setup), or the view dispatches the action.

3. The store receives the action. It sends the current state tree and the action to the root reducer.

4. The root reducer cuts apart the state tree into slices. Then it passes each slice to the subreducer that knows how to deal with it.

5. The subreducer copies the slice and makes changes to the copy. It returns the copy of the slice to the root reducer.

6. Once all of the subreducers have returned their slice copies, the root reducer pastes all of them together to form the whole updated state tree, which it returns to the store. The store replaces the old state tree with the new one.

7. The store tells the view layer binding that there’s new state.

8. The view layer binding asks the store to send over the new state.

9. The view layer binding triggers a rerender.

So that’s how I think of Redux and its differences from Flux. Hope it helps!

Coming up next

I’m making a list of topics. If you have any suggestions, or there are any parts of the React ecosystem that you find confusing and you’d like to see explained, let me know on Twitter.

Resources

• Redux docs
• Dan Abramov’s React Europe talk
• The Evolution of Flux Frameworks
• Smart and Dumb Components
• The upsides of using Redux
• The downsides of using Redux
• JS Jabber: The Evolution of Flux Libraries with Andrew Clark and Dan Abramov

Thank you to the amazing Dan Abramov, Kent C. Dodds and Matt Zabriskie for their feedback.

A cartoon intro to Redux was originally published in Code Cartoons on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hot reloading

When you’re developing an app, you’re usually making one small change after another. The faster you can see the effects of the small changes (and recover from the small mistakes that you make), the faster you will develop.

The neat thing about hot reloading is that your app’s state isn’t reset after every change. Let’s say you’re testing a particular screen. You’ve added a few todo items and crossed a few off. But now you realize you need to change some UI text. For example, you need to change the placeholder from “New toto” to “New todo”.

Without hot reloading, you’d have to:

• Make the change in your code
• Refresh the page in your browser
• Re-add the data and push all of the same buttons

With hot reloading, you don’t have to re-add the data because you don’t lose the state. Your list of todos will still be there. This makes debugging a lot faster.

Even if a React app doesn’t use Redux for its data, you can do hot reloading. You’re just limited in what you can hot reload. Views and action creators can be hot reloaded, but the store cannot. This is because the store has two roles: changing state based on actions and holding on to state. If the state change code is reloaded, you lose the state that the store is currently holding on to.

That’s what Redux gives you here: the ability to hot reload the state logic. And it does that by separating those two roles. In Redux, the store holds on to the state, but the state change logic is done by a different object, the reducer. This means you can hot reload your state change logic (reducers) without losing the state the store is holding on to.

Time travel debugging

Hot reloading lets you keep your state even after code changed. With time travel debugging, you can go backwards to previous points in your state.

This makes it faster to test very specific parts of your interaction. For example, lets say you have a bug. It happens when you cross out a todo item and then add another. You would run through the full scenario once to set up your state. After that, you can just keep testing it by going backwards one step in your state and adding the second todo again.

There are other exciting uses for this. You could record all of the actions of a QA tester. When the QA runs into a bug, they just need to package up the action and state history. You could even turn that into an automated test.

Time travel debugging is technically possible with Flux, but complicated. Redux makes it trivial.

Coming up next

See how Redux makes this all work:

A cartoon intro to Redux - Code Cartoons

Other languages: 한국어

Hot reloading and time travel debugging: what are they? was originally published in Code Cartoons on Medium, where people are continuing the conversation by highlighting and responding to this story.

Flux is both one of the most popular and one of the least understood topics in current web development. This guide is an attempt to explain it in a way everyone can understand.

The problem

First, I should explain the basic problem that Flux solves. Flux is a pattern for handling data in your application. Flux and React grew up together at Facebook. Many people use them together, though you can use them independently. They were developed to address a particular set of problems that Facebook was seeing.

One really well known example of this set of problems was the notification bug. When you logged in to Facebook, you would see a notification over the messages icon. When you clicked on the messages icon, though, there would be no new message. The notification would go away. Then, a few minutes later after a few interactions with the site, the notification would come back. You'd click on the messages icon again… still no new messages. It would just keep going back-and-forth in this cycle.

It wasn’t just a cycle for the user on the site. There was also a cycle going on for the team at Facebook. They would fix this bug and everything would be fine for a while and then the bug would be back. It would go back-and-forth between being resolved and being an issue again.

So Facebook was looking for a way to get out of this cycle. They didn’t want to just fix it once. They wanted to make the system predictable so they could ensure that this problem wouldn’t keep resurfacing.

The underlying problem

The underlying problem that they identified was the way that the data flowed through the application.

Note: this is what I’ve gleaned from simplified versions that they’ve shared in talks. I’m sure the actual architecture looked different.

They had models which held the data and would pass data to the view layer to render the data.

Because user interaction happened through the views, the views sometimes needed to update models based on user input. And sometimes models needed to update other models.

On top of that, sometimes these actions would trigger a cascade of other changes. I envision this as an edge-of-your-seat game of Pong — it’s hard to know where the ball is going to land (or fall off the screen).

Throw in the fact that these changes could be happening asynchronously. One change could trigger multiple other changes. I imagine this as throwing a whole bag of ping-pong balls into your Pong game, with them flying all over the place and crossing paths.

All in all, it makes for a hard to debug data flow.

The solution: unidirectional data flow

So Facebook decided to try a different kind of architecture, where the data flows in one direction — only one direction — and when you need to insert new data, the flow starts all over again at the beginning. They called their architecture Flux.

This is actually really cool… but you probably can’t tell it from the diagram above.

Once you understand Flux, this diagram is pretty clear. The problem is that if you’re coming to the documentation completely new to Flux, I don’t think that this diagram helps you understand it… and that’s what a diagram should do. It should give you a big picture understanding of a system before you dive in to really start figuring out how you do specific things.

What helped me understand Flux better wasn’t a diagram like this, but instead thinking of the system in terms of different characters working together as a team to achieve a goal. So I want to introduce you to the cast of characters that I have in my head.

Meet the characters

I’m just going to give a quick introduction to the characters before I explain how they all interact.

The action creator

The first character is the action creator. It’s in charge of creating actions, which is the path that all changes and interactions should go through. Whenever you want to change the state of the app or have the view render differently, you shoot off an action.

I think of the action creator as a telegraph operator. You go to the action creator knowing basically what message you want to send, and then the action creator formats that in a way that the rest of the system can understand.

The action creator creates an action with a type and a payload. The type will be one of the types that you have defined as actions in your system (usually a list of constants). An example of an action would be something like MESSAGE_CREATE or MESSAGE_READ.

There’s a neat side effect to having a part of your system that knows all of the possible actions. A new developer can come on the project, open up the action creator files and see the entire API — all of the possible state changes — that your system provides.

Once it has created the action message, the action creator passes that action off to the dispatcher.

The dispatcher

The dispatcher is basically a big registry of callbacks. It’s kind of like a telephone operator at a phone switchboard. It keeps a list of all of the stores that it needs to send actions to. When an action comes in from the action creator, it will pass the action around to different stores.

It does this in a synchronous way, which helps with that multi-ball Pong game effect that I was talking about earlier. And if you need to set up dependencies between stores so one gets updated before the other, you can have the dispatcher manage this for you with waitFor().

The Flux dispatcher is different from dispatchers in many other architectures. The action is sent to all of the registered stores regardless of what the action type is. This means the store doesn’t just subscribe to some actions. It hears about all actions and filters out what it cares about and doesn’t.

The store

Next is the store. The store holds on to all state in the application, and all of the state changing logic lives inside of the stores.

I think of the store as an over-controlling bureaucrat. All state changes must be made by it personally. And you can’t directly request that it change the state. There are no setters on the store. To request a state change, you must follow proper procedure… you must submit an action via the action creator/dispatcher pipeline.

As I mentioned above, if a store is registered with the dispatcher, all actions will be sent to it. Inside the store there’s usually a switch statement that looks at the action type to decide whether or not this store cares about this action. If the store does care about this action, it will figure out what change needs to be made based on this action and update the state.

Once the store has made its changes to the state, it will emit a change event. This will notify the controller view that the state has changed.

The controller view and the view

The views are in charge of taking the state and rendering it out for the user as well as accepting user input.

The view is a presenter. It isn’t aware of anything in the application, it just knows the data that’s handed to it and how to format the data into output that people understand (via HTML).

The controller view is like a middle manager between the store and the view. The store tells it when the state has changed. It collects the new state and then passes the updated state along to all of the views under it.

How they all work together

So let’s take a look at how all of these characters work together.

The setup

First there’s the setup: application initialization which only happens once.

1. Stores let the dispatcher know that they want to be notified whenever an action comes in.

2. Then the controller views ask the stores for the latest state.

3. When the stores give the state to the controller views, they pass that state along to their child views to render.

4. The controller views also ask the stores to keep them notified when state changes.

The data flow

Once the setup is done, the application is ready to accept user input. So let’s trigger an action by having the user make a change.

We’ll kick off the data flow with a user interaction.

1. The view tells the action creator to prepare an action.

2. The action creator formats the action and sends it off to the dispatcher.

3. The dispatcher sends the action off to the stores in sequence. Each store gets notified of all actions. Then the store decides whether it cares about this one or not, and changes the state accordingly.

4. Once it’s done changing state, the store lets its subscribed view controllers know.

5. Those view controllers will then ask the store to give them the updated state.

6. After the store gives it the state, the view controller will tell its child views to rerender based on the new state.

So that’s how I think of Flux. Hope it helps!

Coming up next…

A cartoon intro to Redux - Code Cartoons

Resources

• Flux documentation
• Fluxxor documentation
• The Case for Flux

Thank you to the fantastic Kent C. Dodds, Matt Zabriskie, and Christopher Chedeau for their early feedback, and to all the folks at BrooklynJS for their comments on the live action version!

A cartoon guide to Flux was originally published in Code Cartoons on Medium, where people are continuing the conversation by highlighting and responding to this story.