Figuring out yourself is really difficult. It’s not just about finding what makes you happy or productive — it’s about recognizing the patterns beneath both. What drives you to create, what drains you, and what tools help you climb the peaks and prevent you from tumbling down.

Over time, I’ve learned that productivity isn’t about forcing consistency — it’s about understanding rhythm. There are moments when you feel unstoppable, and moments when you can’t even start. The goal isn’t to erase those fluctuations, but to design systems that respect them. Divergent Todos grew out of that realization — an experiment in building a tool that fits how your mind actually works, not how a productivity system thinks it should.

The Spark

In my first job, things were simple. Although I was a one person team, I used my calendar diligently. Each calendar entry was, in my mind, a todo — a follow up for a customer or a provider. And I did follow up on everything, nothing slipped through the cracks. There was clarity, simplicity, and flow.

But as I moved into larger organizations I started drifting away from my own system, new tools kept piling on. Notifications became noise, and every tool competed for a slice of my attention. Slowly, I began to feel like my focus was no longer mine to direct. My tools had turned into tiny attention traps, each pulling me further from the clarity I once had. I began to feel like my attention was being controlled rather than me directing it.

Eventually, I hit a breaking point. My mornings began with flooded inboxes — not from people, but from tools emailing me about notifications. It was almost funny, in a dark way — a notification letting me know another notification was waiting. That’s when it clicked: the very tools meant to help me were competing for my attention just like social apps.

The Divergent Idea

The idea behind Divergent Todos is about taking back control — creating a space that exists solely for you and what you have decided to focus on. It’s meant to be as simple as possible, as decoupled from everything else as possible. It’s not an interface to manage documents, messages, events, or tasks. This is an interface to manage your attention.

When opening Divergent Todos you will be completely underwhelmed. That is intentional. It is designed to feel like an “open mind” at the center of all the noise around you. Switching to the app should feel like taking a breath.

Divergent Todos achieves this goal in two ways. First through the actual app experience:

• It is a desktop app, decoupled from the noisy browser
• It shows you a single week, Monday to Friday as open spaces (though you can peak into next week)
• A todo is just its checkbox and its text, no additional buttons, just organic interactions
• It gently offers moving uncompleted todos from past days/weeks to the current day
• When your focus should be elsewhere, during time boxing or the weekend, it visually reminds you that you should also blur out your other todos
• There are no lists, labels, meta data, time and date, syncing, sharing or other distracting features. It is just you and where you want to put your attention

But Divergent Todos is as much about practice as the app itself. Let me explain how I use it.

Squashing notifications

When I sit down at the computer in the morning I start by going through all my notifications in all my tools — but I don’t act on any of them. Instead, I clear out each notification and translate them into a todo for the current day with a short explanation and link. I fight the urge responding to the message, replying to the comment and reviewing the code change. Nothing is allowed to hold my attention longer than it takes to read the notification and create a todo for myself.

This small ritual already puts my mind at ease. Sometimes I step away at this point — make a coffee, stretch, or just let my mind settle. I haven’t really produced anything yet, but I’ve reclaimed control from my tools. I can see my day clearly, on my own terms.

Prioritizing and Updating

I personally don’t prioritize my todos. I keep them in order — first in, first served. When I act on a todo and it requires follow-up, that follow-up becomes a new todo the next day. Only if I find myself with extra time during the day I bring back my follow ups. If no follow ups, I go back to any notifications and create new todos.

This rhythm ensures I always feel okay about my response time. By default, it takes a day to follow up — but more often than not, I’m able to follow up the same day if I don’t feel overwhelmed. I don’t spend time rearranging priorities or chasing urgency; I simply move forward, one todo at a time.

Todos, not Tasks

Divergent Todos isn’t a task list — it’s a todo list. That distinction matters. When I complete something, I check it off even when there is more work to do. I rather create a new todo for the next day. This keeps my list honest and light, but more importantly it generates momentum.

When someone has asked something of me, I just tick off the todo after responding. If I ask something of someone else, I add a follow-up todo for the next day — just a short note and a link. I proactively direct my attention and keep on top of things instead of relying on notifications.

Time-boxing

There are tasks that are overwhelming in and of themselves. Maybe it is a big unclear task, maybe you do not feel confident the time spent is worth it or maybe it is just super boring to work on. Also when energy or focus is low, even simple work can feel impossible. For these moments I use the time-boxing feature.

Time-boxing helps you feel progress without draining all your energy. By deciding in advance how much attention you want to dedicate, you remove the emotional weight of needing to “finish.” You just move the needle. Even 25 focused minutes can turn dread into momentum. It’s not about forcing productivity; it’s about staying connected to progress. I always complete the todo after time-boxing and create a follow up the next day if there is more work to do.

Syncs and Standups

The todos in Divergent Todos aren’t created for reporting or to satisfy company metrics — they exist purely for you, to feel in control of your attention. The fact that they help in syncs and standups is just a welcome side effect.

Traditional task planning has this illusion that you’ll dedicate 100% of your time to the tasks you’ve committed to. But that’s rarely reality. The day fills with small interruptions, questions, and unplanned work. When syncs or standups roll around, it can be easy to feel unproductive because the “big tasks” haven’t moved as much as expected.

With Divergent Todos, that pressure fades. Even if a task hasn’t advanced, I can see everything I did put my attention to — the follow-ups, the fixes, the small decisions that kept the day moving. Divergent Todos capture the reality of work, not just the team or company plan. It reminds me that progress is rarely linear, but it’s always happening.

Feeling of Productivity

Using a tool that’s designed from the perspective of handwritten todos brings a very different sense of productivity. A task can take days or even weeks to complete, but a todo rarely takes more than a few minutes. It’s digestible, no matter how you feel that day. Each todo gives you a small, achievable step forward — and those steps build momentum. You get into a rhythm, a rhythm of movement, of progress, of feeling productive in a way that’s grounded and sustainable.

Weekends

Work belongs to Monday through Friday. If you find yourself working on weekends, you’re either young and learning or you should be saving lives. Life isn’t a list of milestones, tasks, or even todos. Life is bringing your attention to your senses and your experience, without a checkbox waiting at the end of it.

Divergent Todos gives you a gentle reminder if you ever open the app during the weekend — a nudge to step back and return to living instead of planning. Because work can sometimes become an escape from a stressful personal life. As a parent of two kids, I know this all too well.

The Technical Journey

Divergent Todos is a seemingly simple application — it’s just some todos with a date. But as anyone who has tried to build something simple knows, simplicity is hard. The entire project was driven by one core value: pushing back against the overwhelming nature of modern productivity tools that constantly compete for your attention.

That philosophy shaped countless design and technical decisions, like:

• Fading out everything else during time-boxing or weekends — a visual reminder to stay focused or step away.
• Creating a desktop app to escape the clutter of the browser, which is often packed with distractions before you even start.
• A cheap and simple subscription model — no psychological pricing tricks like $1.99, no annual plan discounts, just clarity and fairness.
• Open source code, because transparency aligns with the same principle of calm clarity that drives the app itself.

What looks like an unassuming todo app is actually a deliberate rebellion against noise and complexity.

Lessons Learned

Modern automation, smartphones, and AI have made life incredibly efficient — but in doing so, they often bypass something fundamental: our need to feel in control of our own attention. Without that, we feel lost. Our attention in every moment is the life we are living. It’s how we experience time, how we create meaning, and how we connect with the world around us.

Divergent Todos has taught me that technology doesn’t have to pull us away from that sense of ownership. It can be designed to give it back — to create moments of calm focus instead of fragmented urgency. The challenge is not building smarter systems, but building ones that help us stay grounded in what truly matters: awareness, rhythm, and the feeling that our attention still belongs to us.

Looking Ahead

There are no grand plans for Divergent Todos. This is it — this is the app. There will be no AI agents, no notifications, no sharing features and no mobile app. Divergent Todos is meant to be your safe space at the workplace — the place you come to when you want to return to your rhythm, to see where your attention has been and where it is going, and to know that it’s okay to step away for a moment or two.

I hope it’s as helpful to you as it has been for me.

Divergent Todos

In this article, we’ll explore a simple yet powerful pattern for structuring code in React components. By following this pattern, you’ll gain a strong intuition about where to put code, making your components easier for fellow developers (and future you) to understand. We’ll refactor the React TicTacToe example to demonstrate how this pattern improves code readability and maintainability.

The Problem: Component Complexity

Let’s start with a familiar example from the React TicTacToe tutorial:

function Board({ xIsNext, squares, onPlay }) {
  function handleClick(i) {
    if (calculateWinner(squares) || squares[i]) {
      return;
    }
    const nextSquares = squares.slice();
    if (xIsNext) {
      nextSquares[i] = 'X';
    } else {
      nextSquares[i] = 'O';
    }
    onPlay(nextSquares);
  }

  const winner = calculateWinner(squares);
  let status;
  if (winner) {
    status = 'Winner: ' + winner;
  } else {
    status = 'Next player: ' + (xIsNext ? 'X' : 'O');
  }

  return (
    <>
      <div className="status">{status}</div>
      <div className="board-row">
        <Square value={squares[0]} onSquareClick={() => handleClick(0)} />
        <Square value={squares[1]} onSquareClick={() => handleClick(1)} />
        <Square value={squares[2]} onSquareClick={() => handleClick(2)} />
      </div>
      <div className="board-row">
        <Square value={squares[3]} onSquareClick={() => handleClick(3)} />
        <Square value={squares[4]} onSquareClick={() => handleClick(4)} />
        <Square value={squares[5]} onSquareClick={() => handleClick(5)} />
      </div>
      <div className="board-row">
        <Square value={squares[6]} onSquareClick={() => handleClick(6)} />
        <Square value={squares[7]} onSquareClick={() => handleClick(7)} />
        <Square value={squares[8]} onSquareClick={() => handleClick(8)} />
      </div>
    </>
  );
}

When reading this component line by line, you encounter:

• The component’s name and dependencies
• State logic and behavior (like handleClick)
• The UI markup

While this works, the mixture of UI and implementation details can overwhelm readers of the code, especially as components grow in complexity.

Refactoring for Readability: A New Pattern

Here’s a simple refactor that leverages a lesser-known but powerful feature of JavaScript: function hoisting. Functions declared within a component are hoisted, meaning you can define them after the return statement.

Additionally, unlike custom hooks — where you typically need to pass relevant context as arguments — these internal functions have direct access to all state and dependencies defined within the component. This reduces boilerplate and makes the component easier to read and maintain.

function Board({ xIsNext, squares, onPlay }) {
  const winner = calculateWinner(squares);
  const status = createStatus()

  return (
    <>
      <div className="status">{status}</div>
      <div className="board-row">
        <Square value={squares[0]} onSquareClick={() => handleClick(0)} />
        <Square value={squares[1]} onSquareClick={() => handleClick(1)} />
        <Square value={squares[2]} onSquareClick={() => handleClick(2)} />
      </div>
      <div className="board-row">
        <Square value={squares[3]} onSquareClick={() => handleClick(3)} />
        <Square value={squares[4]} onSquareClick={() => handleClick(4)} />
        <Square value={squares[5]} onSquareClick={() => handleClick(5)} />
      </div>
      <div className="board-row">
        <Square value={squares[6]} onSquareClick={() => handleClick(6)} />
        <Square value={squares[7]} onSquareClick={() => handleClick(7)} />
        <Square value={squares[8]} onSquareClick={() => handleClick(8)} />
      </div>
    </>
  );

  function createStatus() {
    if (winner) {
      return 'Winner: ' + winner;
    }

    return 'Next player: ' + (xIsNext ? 'X' : 'O');
  }

  function handleClick(i) {
    if (calculateWinner(squares) || squares[i]) {
      return;
    }
    const nextSquares = squares.slice();
    if (xIsNext) {
      nextSquares[i] = 'X';
    } else {
      nextSquares[i] = 'O';
    }
    onPlay(nextSquares);
  }
}

Why This Refactor Works

• Context First: Readers see the component’s purpose and essential state before diving into implementation details.
• Improved Readability: The UI can be understood independently before diving into the mechanics of what happens during a click.
• Access to State and Dependencies: Internal functions automatically have access to all state and props without extra arguments, unlike hooks that require explicit parameter passing.
• Familiar Structure: The top-down flow resembles the constructor and methods pattern from object-oriented programming, which can feel more intuitive.

Overall this pattern reduces cognitive load, making it easier for developers to reason about the component.

Applying the Pattern to More Complex Components

Let’s apply this pattern to a more complex component: Game.

Original Game Component:

export default function Game() {
  const [history, setHistory] = useState([Array(9).fill(null)]);
  const [currentMove, setCurrentMove] = useState(0);
  const xIsNext = currentMove % 2 === 0;
  const currentSquares = history[currentMove];

  function handlePlay(nextSquares) {
    const nextHistory = [...history.slice(0, currentMove + 1), nextSquares];
    setHistory(nextHistory);
    setCurrentMove(nextHistory.length - 1);
  }

  function jumpTo(nextMove) {
    setCurrentMove(nextMove);
  }

  const moves = history.map((squares, move) => {
    let description;
    if (move > 0) {
      description = 'Go to move #' + move;
    } else {
      description = 'Go to game start';
    }
    return (
      <li key={move}>
        <button onClick={() => jumpTo(move)}>{description}</button>
      </li>
    );
  });

  return (
    <div className="game">
      <div className="game-board">
        <Board xIsNext={xIsNext} squares={currentSquares} onPlay={handlePlay} />
      </div>
      <div className="game-info">
        <ol>{moves}</ol>
      </div>
    </div>
  );
}

Refactored Game Component Using the Pattern:

export default function Game() {
  const [history, setHistory] = useState(createHistory);
  const [currentMove, setCurrentMove] = useState(0);
  const xIsNext = currentMove % 2 === 0;
  const currentSquares = history[currentMove];
  const moves = history.map(createMove);

  return (
    <div className="game">
      <div className="game-board">
        <Board xIsNext={xIsNext} squares={currentSquares} onPlay={handlePlay} />
      </div>
      <div className="game-info">
        <ol>{moves}</ol>
      </div>
    </div>
  );

  function createHistory() {
    return [Array(9).fill(null)]
  }

  function handlePlay(nextSquares) {
    const nextHistory = [...history.slice(0, currentMove + 1), nextSquares];
    setHistory(nextHistory);
    setCurrentMove(nextHistory.length - 1);
  }

  function jumpTo(nextMove) {
    setCurrentMove(nextMove);
  }

  function createMove(squares, move) {
    let description;
    if (move > 0) {
      description = 'Go to move #' + move;
    } else {
      description = 'Go to game start';
    }
    return (
      <li key={move}>
        <button onClick={() => jumpTo(move)}>{description}</button>
      </li>
    );
  }
}

Key Improvements

• Declarative Top-Down Flow: The top of the component describes what it is — state, dependencies, and UI. The bottom defines how it works — its behavior.
• Simplified Reasoning: Readers gain relevant context before diving into implementation details, reducing the chance of misunderstanding the component’s flow.
• Seamless Access to Context: All functions have implicit access to component state and props, eliminating the need for passing parameters as you would with custom hooks.
• Easier to Extract Logic: If any function grows too large, it can be extracted into a custom hook or separate file, without losing clarity.

Final Thoughts

This pattern doesn’t just improve readability — it primes developers with relevant context before exposing them to complex implementation details. While simple, it becomes more impactful as components scale.

I call this the constructor pattern because it mimics the idea of a class constructor at the top, with supporting methods defined later in the file.

✨ Try it out: Refactor one of your existing React components using this pattern. Does it help you reason better about your code?

💬 Let me know: Drop a comment if this approach made sense or gave you new insights.

🚀 Stay tuned: My next article will explore how this pattern can be extended to manage state more effectively.

Thanks for reading! If this pattern resonated with you, show some ❤️ by sharing your thoughts. I’d love to hear how it works for you in real-world projects.

In the world of web applications it is not enough to just write code. We also need a well thought out interface for our users to interact with the application. The web has changed a lot the last few years as we have moved from building static websites to full fledged complex applications. The workflow of writing code, collaborating with designers and push great products out the door is still changing as we explore this brave new world. In this article I am going to tell you about a collaboration where the designer treats the developer as a manufacturer of components, and how this idea can make very happy developers and designers.

Meet Arne

When you meet Arne the first time, looking at his style in clothing and that huge keychain he drags around, you kinda get this impression of a punk rocker who works as a janitor. Though Arne is indeed a practical guy he does all his work on and on top of a small laptop. I kid you not, he has a tiny external mouse using the hand resting point of his laptop as the scroll surface. Consider this in addition to him always being late, impossible to get his attention due to always listening to loud music and last but not least, his workspace of choice, you can safely state that Arne is an original.

Industrial design

But before we get into React we need to talk about industrial design. So Arne has a master in physical product design, including studies in interactive and digital design. His master thesis was designing an oil vacuum cleaner. Pretty cool stuff. It cleans up oil spills in the ocean. What makes traditional digital web design different from practical industrial design is that you often have multiple manufacturers, where each manufacturer builds specific components for your creation. It is your responsibility as the designer to make sure that all the pieces fits together at the end.

The way Arne approached this workflow is that he would visit the manufacturers to understand how their manufacturing process works. This research makes his designs more manufacturer friendly. As Arne says: “To describe the expected product you have to understand how it will be built”. This process often starts with “the big picture”, not even pointing out the different components. It is all about functionality which can be based on different criteria. In the case of the oil spill vacuum cleaner it was mostly a matter of size.

As the process moves a long the components are identified and their details are defined. Details like measurements, materials etc. are extracted into their own isolated concepts. Some components composes into bigger components. And now we are starting to see how this relates to React.

Ducky

So Arne and I are working together on a project for a little startup in Norway called Ducky. They are environmental consultants and are working on a platform to socialize, gameify and educate around how companies and people like you and me can make a difference for the environment.

The platform is completely web based and there are often changes and new features as the startup is still researching how they can affect their users. To handle all these changes and reuse as much as possible it was decided to divide the project into two:

1. A component project with only stateless React components. No other dependencies related to state
2. A main project which has all the business logic and state handling, running on Cerebral

The workflow up to this point was creating specific components for each new concept and they were all implemented with the business logic. Jumping back and forth between business logic, UI structure and styling is a messy process for a developer. But not only the developers was happy about this change to focus on UI and styling separately from business logic, also Arne got excited about this. The pure focus on well defined and reusable components gave strong relations to his previous work.

The workflow

Arne still designs the “big idea” which is discussed with the whole team, but as a concept is decided upon the real practical work starts. This is a picture of a github issue created by Arne:

They are divided into five parts:

1. The expected result
2. Composition blueprint
3. Optionally properties and/or style deviation
4. Example sequence
5. Links to components composing this component

Now, this issue is related to building a component inside the main project. It is an application specific component, a stateful React component. But it is composed by multiple stateless components. A stateless component usually only consists of point 1. and 3.

The expected result

The expected result is very often what designers gives to developers as an implementation specification. The problem with this approach is:

1. The developer will probably write a lot of duplicate styling and UI structure
2. Margins, paddings, colors etc. is very hard for a developer to extract from a design mockup, missing out on the importance of these smaller details
3. The end result and impression of the application as a whole will not be coherent
4. Developer takes a lot of shortcuts, especially with CSS, risking a messy codebase

With an industrial design mindset we can solve these issues. The reason is that this mindset has more focus on how something is going to be manufactured (implemented), rather than just the expected end result.

Composition blueprint

This is the real specification. This is what tells the developer what components that composes an application specific component. And this is where the magic happens. Instead of the developer being concerned with producing multiple components, implementing their UI structure and styling, the developer can focus only on the business logic. So either you build small stateless components defining UI structure and styling on one project, or you sit on an other project composing them together and hooking them up to stateful components and the business logic.

Properties and deviations

In design there are always small deviations, often related to colors. In these situations Arne defines what these properties and deviations are. A typical example would be that a Wrapper component should have a specific background color.

Example sequence

Users interacts with the interface and it can have many different states. This is what makes application design different from web design. You have to imagine all the states and ideally also design them. You have hover states, disabled states, loading states, dynamic lists etc. And this is where it gets tricky. Often these states are related to waiting on data from server, but the designer usually has no idea about that. In Ducky we just keep a fast feedback loop to identify when a description is missing a state related to data fetching or something else.

Links to components

All components, being in the main project or the components project, has their own github issue. Application components in the main project has links to the components they are composed by. This makes it easy for us to identify that the base components are implemented and ready to be composed into our main project.

Github also links the other way around, so when we click a base component in our components project we can see what application components composes it.

Scoping components

So on one side we have these large application components and on the other side we have these small base components. What about abstractions in between? Let me give an example.

One stateless component can be an icon, <Icon type="favorite"/>. But now we want to use that icon in a button. How do we handle that?

1. We can create an <IconButton type="favorite">My button</IconButton>
2. We can configure a button <Button icon="favorite">My button</Button>
3. We can compose it <Button><Icon type="favorite"/>My button</Button>

So what is the right answer? There is really no right answer, there is only consequences.

The first suggestion will increase the number of components and give very subtle differences that can be hard to reason about. Like: <IconButton/>, <IconTooltipButton/> etc.

The second example risks getting a lot of props, causing multiple if (someProp) {} in their implementation. <Button icon="favorite" tooltip="some text">My button</Button>. Also its behaviour has to be implemented in multiple components: <Hyperlink tooltip="some tooltip"/>

Here at Ducky we favor composition over abstraction any day. In other words, we prefer example 3. :) And this is why:

• It is safe to build small basic components as they are very unlikely to change. And if they do it is highly likely that you want the same change wherever the component is used
• Very few props are passed to each component
• We rarely pass a prop from our application component to a stateless component which just passes that prop down to another component. That way we keep the UI structure less rigid
• We can easily introduce new compositions. For example maybe we wanted to wrap our <Icon/> in a <Tooltip text="wheeee"><Icon/></Tooltip>. With the two other approaches we would have to move back to the components project and implement new components or props with if (tooltip) {}.

But some components should be abstracted? Well, ideally not. I think we need to move ourselves from traditional thinking where we imagine the tabs actually has something to do with the tab content. They really do not, let me explain.

Your application is in a state where the current tab index is 1.

<Wrapper>
  <TabButton active={currentIndex === 0}>Overview</TabButton>
  <TabButton active={currentIndex === 1}>Something else</TabButton>
</Wrapper>
<Wrapper>
  {currentIndex === 0 ? 'Some awesome content' : null}
  {currentIndex === 1 ? 'Some other awesome content' : null}
</Wrapper>

This is a much more flexible approach than going all “abstracty”:

<Tabs
  buttons=['Overview', 'Something else']
  contents=['Some awesome content', 'Some other awesome content']
  activeIndex={currentIndex}/>

What if our buttons suddenly needs an icon? We move over to components project to implement and refactor our existing tabs and our new tab to:

<Tabs
  buttons=[{icon: 'favorite', label: 'Overview'}]...]
  contents=['Some awesome content', 'Some other awesome content']
  activeIndex={currentIndex}/>

But our content should not only be text, it should support any kind of content. We move over to components project to implement and then move back:

<Tabs
  buttons=[{icon: 'favorite', label: 'Overview'}, ...]
  contents=[<p><a href="">Link</a></p>, ...]
  activeIndex={currentIndex}/>

This is a really annoying workflow that constantly gets you into issues. To make these changes to our initial approach we could just:

<Wrapper>
  <TabButton active={currentIndex === 0}>
    <Icon type="favorite"> Overview
  </TabButton>
</Wrapper>
<Wrapper>
  {currentIndex === 0 ? <p><a href="">Link</a></p> : null}
</Wrapper>

You are completely free to create variables and iterators to more effectively produce these components of course, but they are all built by completely basic stateless components.

Design spec vs. implementation

These application components can get pretty big with lots of composition. So this is a key difference from design spec and implementation. Even though Arne creates abstractions in his design specification it does not necessarily mean we are going to implement the same abstractions in our code. Lets look at an example, the “activity modal”:

Here we see that Arne has composed the “activity modal” into two main components. But these components contains many sub components. So what we do is dive into these components and locate their smallest pieces which will be implemented in our components project.

When we reach the “bottom” we start composing by “walking up the design spec” until we reach the issue that is the “activity modal”. Everything happening in our main application project. We are completely free to make small abstractions, extra render methods etc. to make our code clean and dry, but we do not pass a lot of props into isolated magical components. Everything can be changed around inside our main application project.

Summary

This workflow has been a game changer for us. It builds a great foundation for moving faster and faster as the project grows, even with a lot of changes. It has also made us realize the complexity of the applications we try to build. This inspires us to look into other tools to help us define and build our components. Hopefully we can share that with you later :-)

If you have questions, or maybe you have similar experiences, please share in the comments below. And thanks so much for reading!

The ingredients of an application

To create a web application you need the following ingredients:

• State that describes the current state of the application
• Effects to talk to the outside world
• Logic to run effects and change the state
• Html as a product of state
• Styling to configure the layout and decorating the html elements with CSS or inline styles, often as a product of state

The current popular abstraction to do all of this is what we call a component. It is a powerful abstraction because it allows us to compose endlessly complex user interfaces by building a tree of components.

But this power also captures different concerns. There is no doubt that components should concern itself with consuming state and producing html and styling based on that state. But what about the state itself? The effects and logic? Should components concern themselves with that? What would happen if we made a strong separation of consuming state to produce a UI and the effects and logic required to manage that state?

“But hey… separating UI from logic is something we have done for ages”. And yeah, we have and still do. What this article tries to convey is rethinking the responsibility of components, as they are blurring out the line between the UI and the state, effects and logic needed to build that UI. What can we do with our development experience if we let components only concern themselves with the actual production of html and styling?

Creating an app without UI

Have you ever thought about how brilliant the development tools for html and styling are? The browser gives your really great insight into what actually builds up what you see on the screen. You can even manipulate it. But what about the state, effects and logic we write for our applications? The only tools we have natively in the browser is the Javascript runtime debugger. Of course it has to be this way, because application state, effects and the logic we write to manage them is not a set API, it is not a standard. As we now want to distance ourselves from html and styling it might be that the browser is not such a good tool to develop our application. Let us see how we can do this differently.

What if you did not fire up a browser and connected to localhost:3000, but rather fired up something like this:

Just like a browser you connect to your running application, but instead of showing a white blank screen you get an empty object:

This object represents the state of your application, which currently is not defined. Let us take a look at an application we all know and love, and start defining the required state for that application:

But wait… we just said that we are not going to concern ourselves with html and styling and that is exactly what we are looking at. Let us discuss this a bit. A typical development process uses design mocks. A design mock has multiple purposes. One thing is discussing the overall user experience, another is discussing component boundaries. But you can also use a mock to discuss interaction and what state needs to be present for that interaction to work. And that is what we are doing here. We dissect the mock to figure out what state, effects and logic needs to be present to handle interaction. Ideally we would have several mocks, but this will do.

We define the state in our code and now the development tool gives us:

As you can see both remainingTodosCount and currentTodos has a label of derived. That means there is logic deriving that state rather than it being explicitly set. Specifically they derive the todos and the filter.

So now that we have prepared our state let us move on to some logic to change that state. Our TodoMvc application needs to do the following:

• Change the title of a new todo
• Submit a new todo
• Change filter
• Remove an existing todo
• Set a todo in editing state
• Change the title of an edited todo
• Submit the edited title on a todo
• Cancel the editing state of a todo
• Toggle todo completed

Let us now implement an action that allows the application to change the title of a new todo. We fire it off in the development tool with some text and indeed we can see that the state is being changed as expected:

Now let us add an other action that uses the newTodoTitle state to add a new todo to the todos. Since we are using hot reloading in our application the previously state changed is kept and we can just run our new action:

As we can see a new todo is indeed added to the todos and we also emptied our newTodoTitle. What is especially interesting here now is that we have an indication that tells us that two derived state values were affected by the change. If we now go back to our state we can see that both the remainingTodosCount and the currentTodos state has changed:

Now let us implement the changeFilter action, fire it off and again see that the derived state values has changed.

Now the currentTodos is empty because the filter does not match the state of the todo.

Now you have started to see what is achievable when we think differently about the concerns. When there is no UI we do not think about what category of state we are defining. We just describe what is needed for the application to operate. It does not matter what will eventually consume the state and trigger our logic later.

What about UI state?

You might be thinking now that we are mixing UI state, for example newTodoTitle with other state like filter and todos. This is a very difficult topic to discuss. What is UI state and what is not? Is it defined by where the state comes from, like from a UI element or the server? Is it the boundary of the state, like is it only contained within a component or shared between components? Maybe state used related to html attributes and styling is considered UI state?

I think this confusion is often rooted in focusing on what will consume the state. If we defined newTodoTitle inside a component we would probably name it newTodoInput or something more related to what piece of UI actually consumes that state. But we are not working with any UI now. We free ourselves from thinking UI state at all. Everything is just state. Something that needs to be defined for the application to operate… without a UI.

For me personally this is such a freedom developing applications. I do not care about what consumes the state and where it is consumed. What is important is to define the state within a domain of the application and make it available wherever it is needed, without having to think about things like performance, and its availability to what pieces of the UI. You also avoid the complexity of architecting your state, effects and logic around and in between pieces of UI that mounts and unmounts.

Talking to the world

Most applications does rely on APIs from the environment and/or other tools. Our TodoMvc application for example wants to store the todos in local storage whenever we add, remove or change a todo. Let us implement an effect in our application that does just that. We name it localStorage and add the methods getTodos and setTodos. When the application fires up we grab the todos from localStorage and populate it as initial state:

Ops! I seemed to have made a mistake. There is no method named get on the localStorage API of the browser. Let us fix that:

We see that we are using our effect and we set the todos initial state. Let us add a new todo and see it being stored:

As you can see our localStorage effect does not conform to the API of the browser. Effects are rather your domain specific APIs that are custom tailored for their purpose. We do this for the following reasons:

1. Other APIs has no knowledge of the domain of your application and thus the method names and arguments passed to those methods are generic in nature, reducing the readability of your application logic. By defining effects between your app and the other APIs allows you to keep your logic domain specific. As the example shows
2. The APIs of the tools rarely does exactly what you want. You might want to combine multiple APIs for a single purpose or do some additional work. An example of this is the effect above that does the stringifying and parsing of JSON to store the todos in local storage
3. You can now easily mock out the effects either related to testing or if access points are not ready/available when you implement the logic
4. You can easily lazy load effects when they are needed, reducing the initial payload of your application
5. Execution of the effects can be traced, giving you more insight
6. The effects can change its behaviour depending on the environment they run in
7. If you use Typescript you ensure that you have typing for your effects and you avoid having to type generic API calls, like: axios.get<User>(…)

As you can see there are only benefits to having a concept of an effect.

Where do we go from here?

Now that our application has its state, logic and effects we can start thinking about implementing the UI. We could go straight ahead and expose the state to components that needs it and trigger actions to change it, but let us think bigger here. For the sake of bringing perspective on concerns in this article, let us leave the world of state, effects and logic and only think UI.

A project called Storybook allows you to build and style your components separately from your application. This allows you to think about your application from a different perspective. Previously we used the image of the TodoMvc app to identify what state, actions and effects are required for the application to work and used a tailored environment to achieve that. Now we are going to identify what components are needed to produce the visual style of the application. Storybook is an environment tailored for that.

Here is an example of the TodoListItem where we show it off in different states.

What is important here is that this component does not have any internal state. So for example putting the component in edit state is actually a property passed from the outside. We could introduce state inside the component to do this, but it reduces its flexibility. By managing state from the outside you can for example in this case decide if you want to allow editing multiple todos at the same time. You could stop editing a todo when some other interaction occurs, for example changing the filters. Components are more flexible when they do not have internal state and state is more flexible when you define it unrelated to the UI.

Bringing it all together

Now we have our application running and our components defined. That means when you fire up the actual environment the application will run in, you really only have to care about layout, exposing state where it is needed and bind events from components to actions.

I have worked on a lot of projects in my career and in my experience the typical way to develop apps is by feature. One developer grabs one feature and dives into all aspects of it at the same time, in the same environment. Html, styling, state, effects and logic. These are the consequences I find most noticeable:

• It is frustrating because you are constantly moving between the different concerns. Especially when you spend 10x the time on styling compared to implementing logic
• The ownership in the project is split on features instead of implementations. It is always good to have multiple developers involved in a feature, even though they implement different parts of it
• The designer mock becomes a “design handover”. It should rather be a reference for discussion between multiple developers and the designer
• You often get into a situation where you want to implement state, logic and effects for a single component, but find yourself working on different components for state, effects and logic as it needs to be shared

Separating the concern of building the application, and producing a UI for it, gives us a perspective where new tools can be built. Tools that can help us improve the developer experience creating our apps, maybe even the process of developing apps all together.

Summary

The tool you just saw is part of the Overmind developer experience and we are just getting started. Just like Storybook removes complexity of state, effects and logic, we can use the Overmind devtools to remove the complexity of producing html and styles. Thanks for reading and I hope this at least was a friendly poke at your current assumptions on how applications can be created.

UI as an implementation detail was originally published in The Startup on Medium, where people are continuing the conversation by highlighting and responding to this story.

1. Define state and the domains of that state
2. Write logic to change the state
3. Consume the state in components to produce a UI for the users

When my line of code expresses one of these points I produce actual value for the customer/company. This is where I write the actual application.

In the last few years working with different state management solutions I find myself spending less time writing code covering these three points and more time writing code orchestrating the relationship between them. You might argue that this orchestration creates value in the long run, but there is a threshold. At some point this promise of maintainability, predictability and scalability made my developer experience suck big time.

TLDR; In this article we are going to look at why I think we are spending too much time orchestrating our apps. Then we will look at a solution that minimizes the orchestration required to define, change and consume state, without giving up guarantees of maintainability, predictability and scalability.

Disclaimer. I will be referencing existing tools in a negative way. That does not mean I do not respect the authors or think the tools has no value. On the contrary, that tools mentioned in this article has been very important for the community in general and for my personal learning and productivity.

Orchestrating what now?

To build an application we have three core ingredients. State, logic to change the state and the UI which is produced by consuming the state.

When you spend time with these concepts as a developer you feel productive, you are building the app! As complexity grows we need tools to help us handle the relationship within and between these concepts, and there is no lack of tools. These tools promises maintainability, predictability and scalability. Managing complexity. But even though these tools are here to help, and they do help, they also come with a cost. This is nothing new, but as a developer I have come to a point now where I get really upset by all the time I spend managing the tools, rather than building the app. So let me point out some of these pain points and then tell you how I think they should be solved.

The itches

Typescript

Everyone who knows Typescript also knows that adapting to it is rather painful. What is not always pointed out though is that this has really nothing to do with Typescript itself, it has to do with using tools that was never intended to be used with Typescript. Javascript is a dynamic language which allows a lot of creativity defining APIs, APIs that Typescript simply is unable to express, or the types are not implemented at all. Where I have especially felt pain is with Redux and React component libraries. Redux has as many typing approaches as there are apps, and component libraries does not define their Higher Order Component typing correctly, causing all sorts of weird errors when trying to compose together a component. This is not to say Redux or the component libraries are bad, it is just an unfortunate consequence that creates friction when developing apps.

Flux architecture

When the one way data flow was revitalized by Facebook it got me really excited, cause the concept of having an external state store with logic solved one of the biggest challenges I had developing apps. Now any piece of UI could consume any state and trigger well defined logic to change that state without orchestrating the relationship between the pieces of UI.

That said, even at this day with Redux I think there is still way too much orchestration. Redux`s promise of predictability, by only allowing state changes inside reducers, has a high cost. In addition to defining functions to run logic, you have to define the action types, a switch statement to perform the actual state change, dispatch actions and you ideally have to introduce an immutable state layer. This is a lot of friction to do a simple state change.

You might argue that all this is worth it, but in my experience it is definitely not. There is absolutely no reason to do all these things to get the guarantees of predictability, maintainability and scalability.

Connecting dependencies

I will be bashing a bit on Redux here. Not because I think the library is bad, but it has taken the position as the “holy grail” of state management, despite its high cost. We have already mentioned one cost above, but an other cost is connecting state and actions to components.

For every component that wants access to external state and/or actions needs to explicitly define a function which extracts whatever you want to expose to the component. This in itself is just some additional syntax. Where it becomes a cost is that you have to evaluate what nested level of state you can expose related to how often the component should render. And all this falls back to understanding the concept of reference checking (immutability). If you expose the top level state to a component, the component will render on any state change. If you expose a nested dictionary of posts, the component will render on any change to any post. In certain situations, and those situations always occur in any mid sized app, you have to use shouldComponentUpdate. This is friction and it reduces the developer experience. Defining these connectors and shouldComponentUpdate does not help you build the app, it is primarily you helping Redux and React avoiding unnecessary rendering.

Imperative vs functional

There will always be discussions on where imperative and functional programming shines. To me imperative programming is more straight forward, it is more “how my brain thinks about stuff”. I instruct the computer to make changes to my state, I do not “reduce” or “scan” over state. But that is not my point. My point is that we seem to go for one or the other. If you choose RxJS, everything needs to be RxJS. Or if you choose redux-sagas or redux-loop, everything needs to be defined that way. I think that is wrong. Simple state changes should be done imperatively as it reduces the required syntax and concepts around it. Complex state changes should be done functionally as it reduces the required syntax and concepts around it. Let me explain with an example.

You want to toggle some state. There is absolutely no reason to go through all the hassle of creating action types, implement switch statements and dispatch, or create a stream with RxJS, set up a saga etc. You express this toggling best by simply:

state.stateToToggle = !state.stateToToggle

But then we have something more complex. We want to perform a search. This search should only run when the query is of a certain length and only when the user has stopped typing for 200ms. This would be “a complete mess” implementing imperatively, but functionally you could say something like:

export const search = pipe(
  setQuery,
  filterValidQuery,
  debounce(200),
  getSearchResult
)

Having an API that allows you to move between these two worlds, without locking yourself to one or the other, I believe to be ideal.

Props drilling and events

One of my biggest itches is orchestrating the relationship between components. One thing is composing actual UI made up of multiple components, but when we start orchestrating state and logic between them things gets bad quite quickly in my experience. If you need to pass state multiple components down or you start firing off events which bubbles multiple components up you have created an abstract dependency chain which requires you to jump into multiple files to get your head around it. Another thing is that it becomes fragile. Your actual UI does not necessarily relate to this state/logic dependency chain you have created and as soon as you start moving components around due to changes in the UI itself, things start to break.

Component vs application state

The first reason I got into the open source business of state management tools was an intense itch I had building complex UIs. Whenever I defined state it was in some sense unavailable. The reason was because it was defined within a view/component. As I developed my apps I was constantly refactoring where that state was defined to reach whatever views/components needed access to it. The solution was to move this “application state” outside of the view/component layer. That is not to say component state is not useful, but in my experience you have a better developer experience treating your state as “application state” primarily, cause then by default it will always be available to whatever needs it without any props drilling or refactoring the state to a different view/component. Secondly you use isolated “component state” where that makes sense.

Scratching the itches

All of the before mentioned issues I call “friction”. Things I have to do as a developer that annoys me, breaks my flow or I simply feel is completely unnecessary. The project I am going to tell you about now reduces all the before mentioned friction to a minimum, making application development a more enjoyable experience without disregarding the importance of predictability, maintainability and scalability.

I want to start by giving a shout out to Michel Weststrate and his Mobx project. This project gave a much needed counter weight to Redux and immutability. It also heavily inspired me and my band of open sorcerers to work really hard on choosing the API, and the underlying implementation needed, to lower the friction of app development.

The project never left its working title and is now officially named Overmind. The project has been in development for over 6 months and it could not have seen the light of day any sooner. The reason is that we have been heavily dependent on latest Typescript releases and also getting Proxies into all modern browsers.

Let us now look at how this project reduces the friction of developing apps by revisiting these itches. To get more information about the API and how it works you can visit the official website: https://www.overmindjs.org.

Defining state

Overmind can be used with any of the popular frameworks. It being Vue JS, Angular or React. When you bring Overmind into your project it is encouraged that you primarily define your state in Overmind and you define it as a state tree. That means you do not need any classes or reducers, you just create plain objects which describes the state of your app. You can scale your state into different domains, even lazily load state, and at the end of the day it is all merged together into one state tree.

What we achieve here is to remove concepts like classes, decorators, reducer functions and the likes. You define your state as plainly as possible. This has the benefit of being serializable as well, allowing you to move the state to development tools, rehydrate the state from the server etc.

Changing state

One of the promises of Redux is that the state you define in a reducer can only be changed inside the reducer. That is a great promise and gives predictability. That said, you have to pay for it with action types, dispatching and reducing over state. You do not need a reducer to have predictable state changes. In Overmind you change the state directly with the rest of your logic. There is no action types, dispatching or reducers. Instead, the state changes are scoped to actions. These actions are the only place you are allowed to change the state and the Overmind devtools shows you what actions changes what state.

An additional benefit here is that the actions can safely do asynchronous mutations as well. No need to call a new action or use generators to express asynchronous changes of state, like you do in Mobx.

When your state changes becomes complex you have a natural stepping stone to a functional API exposed by Overmind. You can even reuse your existing actions and compose them with functional operators like filter, map, debounce etc. This allows you to think in simple imperative terms for simple logic and then go functional where it actually gives value. (The search example above is actually Overmind API).

Consuming state

Since Overmind is based on proxies it knows exactly what state your components access. That means there is no reason to map state and actions to props. You just use the state directly and whatever is being used is tracked. That means Overmind optimizes component rendering and it does it a lot better than you would ever do by manually mapping the state. Even though all of this happens implicitly it does not happen out of your control. The Overmind development tool, which is a standalone application, gives you all the information you need. What state is defined, what actions are run, what do they do and what components depends on what state.

I often get the question of, “but I like to explicitly declare the props my component uses”. My theory is that this is a comforting argument as it helps you identify why your component renders, I should know… I have used that argument many times. But now you are relived of thinking about this at all, there is no “will my component render too much” friction.

Typescript

Typescript has evolved a lot since it was first released. It has almost become its own type scripting language, allowing you to express types correctly in a variety of dynamic APIs. One example of this in Overmind is that you can define derived state in your state tree with a function. This function has access to all the state of your app and you return a value based on it. This value is cached and updates when the accessed state changes. When you consume this state in a component though it is typed and accessed as a plain value.

The most important thing though is that Overmind is written in Typescript from the ground up with a focus on the types being part of the actual API. This flips the coin. Typescript is always a help to you in Overmind, it is never a chore which it too often feels with tools not written in Typescript.

Summary

Maybe this article only provoked you. Maybe you are super happy with the state management solution you are using today and it solves building your app beautifully. Good for you! The important thing is to find tools that makes you and your team productive and happy developers. I have only been scratching my own itches and it turns out other developers share those itches and that is why Overmind exists. I hope at least this project has contributed with discussions and questions around what you expect from the tools you use and maybe it even scratches an itch you have, if so head over to https://www.overmindjs.org and learn more about the project!

📝 Read this story later in Journal.

🗞 Wake up every Sunday morning to the week’s most noteworthy Tech stories, opinions, and news waiting in your inbox: Get the noteworthy newsletter >

Dan Abramov on Twitter

I also think it's a miracle that React, for all its "unconventional" choices like immutability, top-down data flow, lack of mutation tracking, transactional updates, ever became so popular. Maybe it was a temporary anomaly, and it's time to dial it down a bit. 🙂

As a library author I have explored implementing application state management from the perspective of value comparison and mutation tracking. In this article I will explain how these two approaches work and why I personally think one is better than the other for keeping UIs in sync with your application state.

Preface

In this article we are going to compare how two different approaches to detecting state changes affects how you structure that state, how you write logic to change that state and ultimately how it affects UI performance.

What is important to remember reading further is that immutability (value comparison) and proxies (mutation tracking) are tools that can be used to solve many different challenges in different environments. In this article we are discussing value comparison and mutation tracking to tackle the challenge of updating UI when state changes. Also note that when I say “UI update” I do not mean actually touching the DOM. I am referring to the work a component does to figure out if and what needs to be updated.

I will be using React in the examples, but you are not required to know anything about it to get value out of this article.

Value comparison explained

I remember immutability being a big question mark when I was first exposed to it. And even when I understood how it worked, I still did not understand what it was used for. To better explain immutability I will first explain how value comparison works and then how immutability makes this possible:

Imagine a simple component:

This component receives a user state and it renders the name and age of this user. That means whenever either the name or the age changes, we need this component to update. We could solve this without immutability. We could explicitly check if the name and or age has changed:

But manually optimizing all components like this would be tedious and fragile. As complexity increases it becomes increasingly difficult to debug when a component updates when it should not, and when it does not update when it should.

If our user was immutable we would no longer have to check the name and age. It would be enough to check if the user itself had changed. Let us see how we would update the age using a mutable and immutable approach:

If we used the mutable approach the user itself would not change, only the age property. With immutability we also create a new user object. And that is immutability in a nutshell. Bluntly put, whenever properties in objects or arrays change, also all the direct parent objects and arrays change.

In our component we can now make sure it updates by only comparing the old user value with the new:

React has no logic to optimize updates of components in itself, unlike Vue. It gives you the shouldComponentUpdate lifecycle hook to do value comparison. In combination with immutability this is a simple and effective approach to detecting when the UI needs to update.

Before we start talking about benefits and challenges, let us look at the other approach.

Mutation tracking explained

A radically different approach to the same challenge is allowing the developer to just mutate state as normal, but rather track what is being mutated. By using the new Proxy feature in JavaScript we track what state a component accesses and where mutations are made. By comparing these two pieces of information we know what components should update related to what mutations.

Unlike value comparison, mutation tracking is arguably more tricky to implement. That said, the implementation itself is hidden from the developer, unlike value comparison where you likely have to compare values manually to optimize updates.

With React as an example we need to introduce a wrapper to our components, which nicely highlights how it actually works:

Our User component is wrapped by logic that will take care of tracking state access. When the component renders we access two different properties on the user, name and age, this is stored by the trackStateAccess wrapper.

When our user is defined we do the same kind of wrapping, only for tracking mutations:

We now track state access and mutation and have the ability to figure out what mutations affects what components. If a component depends on user.name and we we do a mutation on user.name, they match.

Now that we have an idea of how the two different approaches work we can start to compare them.

State structure

Value comparison requires you to be aware of what state you bring into your components. The reason is that a nested change will cause a change to all direct parent objects and arrays. If you look at this example:

Every time you change the content of the file any component depending on workspace, workspace.files or workspace.files[0] will update. Due to this fact you will quickly meet the concept of state normalization. State normalization is not specific to the value comparison approach, but unlike mutation tracking you can get into performance issues if ignored. Specifically in this scenario you would want to change the structure to:

This makes sure that when file content changes it does not affect the workspace or the files array. Normalization does not fix the problem completely though. Any change to a file will affect any component depending on the file itself, even though it did not care about the actual property changed. It also introduces the need for additional logic that maps the ids of the files array to the dictionary of files.

Mutation tracking allows you to structure your state however you want. Since it tracks the exact state being used in components it does not matter how it is structured. With the example above only the components actually pointing to workspace.files[0].content would be affected by a change to the content. That does not mean you will never use normalization. For example users can be authors of posts, but also authors of comments. To avoid having duplicate versions of a single user in your state you can use normalization to ensure that when you change the name of a user, both the post and the comments will update. Unlike immutability you do not need to do this for performance reasons.

Conclusion is that value comparison causes an extra mental load in certain applications where you have to be careful about how state is structured, or you get into performance issues. Arguably you should always normalize your state, though it is not necessarily normalize-able state that causes the performance issue. With value comparison you will have unnecessary updates to components due to the fact that it is way too tedious to compare every single value. With mutation tracking you put your faith in the system. It relieves you of the mental load of figuring out how components update, it just works and optimally so.

Syntax

Value comparison can increase the amount of syntax needed to express state changes as JavaScript does not have Immutability built in. The example above can be improved by using spread and you can also use libraries like Immer to express immutable changes with a traditional mutable API. Immer actually uses proxies under the hood. As a library author Immer can be integrated in such a way that the immutable nature of the library is completely hidden.

Mutation tracking allows you to mutate your state as normal. There is really no difference when the tracking is integrated into the library.

One could argue that the mutation tracking approach encourages imperative style in your code, where immutability encourages a declarative functional style.

Conclusion is that syntax should never really be the deciding factor. We have different opinions about how to express code and that is perfectly okay!

Performance

Value comparison is very performant in the sense that there are really no implementation details related to components. We just compare values. That said, any state change will require every single component to verify if an update is necessary, unless you use a library with a lenses concept. If you are specific about the state needed in components you will normally be okay, but when you are not careful it can have huge implications. For example changing the text of an input in a complex form can easily cause the whole form to update, just because of the way the state is structured and used by other components.

There is also a cost to performing the state changes. Because all direct parent objects and arrays needs to be replaced you will consume more memory, which triggers the garbage collector more often. Immutable libraries uses structural sharing to aid the issue, but it will have a cost at the end of the day.

Mutation tracking uses proxies which has an overhead on accessing properties, it being for tracking state usage or state mutation. Just like immutability there are techniques that lowers the cost of this tracking.

Conclusion is that performance is incredibly hard to compare with two very different solutions. And there are also three completely different things that needs to be benchmarked:

1. Performance cost of mutations
2. Performance cost of detecting change
3. Performance cost of UI updates

The last point here is interesting. If mutation tracking has a higher cost on detecting change, but has less UI updates, how do you compare that? I have not done any benchmarking of this myself, and I think it is pointless. It depends on the application and there are so many other unrelated and more important types of performance metrics that affects your application.

Main conclusion and a release

Personally I favour mutation tracking for handling UI updates and these are my reasons:

• Mutation tracking tracks exactly what state changes should affect the component. It automatically optimizes based on whatever state you access. Just knowing that value comparison causes a lot of unnecessary updates makes me feel out of control
• Even though I favour a declarative functional approach to programming, you will always write imperative code to some degree. What I think is important is to have a clear separation. There is nothing preventing you to abstract the imperative code your write in a mutation tracking world into a declarative functional world
• Mutation tracking is arguably a lot easier to get going with. And I deliberately use the term easy here. Our tools can be smart as hell, but the public facing API should not be
• Mutation tracking can produce more information about the relationship between changes and what is affected by those changes. Meaning you can get a report of your current state, what reacts to that state and what state changes has been made

With this last point, and really the whole article, I want to announce a tool for library authors called proxy-state-tree, which is currently in beta. It has implemented the logic needed to track state access and mutations, exposed with a simple API and debugging information. I built this with Fabrice (big hug to Fabrice) to help developers iterate on the really problematic parts of building web apps: “Where and how should state be defined and where and how should state be updated?”. How you detect the changes and update the UI should just work and be performant!

As an example of using this tool I built a demo library on top of Preact. It allows you to wrap your application in a Provider which receives state and actions. The state and actions are exposed to all connected components. What to take notice of in this simple demo is the implementation of components and devtools, as it shows how powerful and flexible the proxy-state-tree API is. With information from proxy-state-tree you can easily build a debugging experience that gives you a lot of insight into what is happening in the application. In the demo take note of the following:

• You get a list of components active in the UI and what state paths they depend on and how many times they render
• You get a list of mutations performed on what paths
• The toggleItemCompleted action actually takes an item state and mutates it, but the devtools gives you the full path to its location in the state tree
• Try out checking/unchecking items etc. and see how the render counts behave compared to mutations performed. You see there is a one-to-one relationship between mutations and components. This happens automatically
• You can not mutate state outside actions, an error is thrown

Thanks for reading! I hope this was useful and maybe inspired you to try out some state management ideas you have! :-)

Updating UIs: value comparison VS mutation tracking was originally published in ITNEXT on Medium, where people are continuing the conversation by highlighting and responding to this story.

A brief history

When Codesandbox.io was released last year I immediately got a bit upset. A 19 year old kid just kicked my 33 year old ass. My Webpackbin project got some serious competition! But being an open source enthusiast I saw this as an opportunity to share ideas. I contacted Ives and was very happy to know that he felt the exact same way. We started collaborating on handling NPM packages, which both Webpackbin and Codesandbox needed. During this time we talked frequently about merging our efforts into one project, but I think we both felt the timing was not right.

A year later Codesandbox.io has increased a lot in popularity and features. At the same time another project I have been working on, Cerebral, has moved to a stable API and proven itself a valuable tool to manage complex applications. After meeting… and drinking… face to face at ReactiveConf 2017 we decided it was time to make this happen.

Why refactor?

So lets talk about why changing out the stack and do a refactor was even needed.

The first issue was the normalization of the sandbox. A sandbox includes what is called modules (files) and directories. Due to Redux immutable nature this structure causes a performance issue. When for example the code of a module is changed, the module itself is changed, also the modules array and even the sandbox object. Since several components depends on the sandbox and the modules, this would cause a lot of unnecessary renders whenever you typed in the editor. The level of granular shouldComponentUpdate and/or props passing that would be needed to ensure optimal rendering was challenging. So to improve the situation the directories and modules are moved into their own separate state and reference back to the sandbox with an id. This helps the situation because a code change now only changes the module. But it also causes a problem. It exchanges the performance issue with a boilerplate issue. Normalization itself adds additional code and concepts developers needs to understand and reason about, but more importantly you have to add code to bring the modules and directories back together in different scenarios. This typically happens in a Redux selector or manually in the components. Codesandbox also has a lot of helpers to figure out things related to modules and directories, these helpers would typically take a modules and directories argument, instead of just passing in the sandbox.

Normalizing for the sake of keeping for example the change of a user consistent between related entities is one thing, but when it is used only for performance it indicates that Redux might not be the best fit for this project.

The second issue is more general. Projects that evolves quickly benefits taking a few steps back now and then to refactor. This is how you keep codebases manageable. During this new refactor I told Ives that I was really impressed how he was able to keep the codebase quite manageable while pushing all these new features. I think both Ives and Redux deserves credit here. But even though the different domains of the application was nicely split into folders containing actions, reducers and selectors, the codebase was hurting a bit by the fast pace of new features. The domains had started to become overloaded and it slowly became difficult to reason about for new contributors.

The third issue was also a matter of overloading. The components were in some situations quite difficult to reason about. As an example:

1. You open a component file
2. You scroll past styled-components definitions, which could be over 50 lines of code in some situations
3. You scroll past flow typings
4. You get to the mapping of state where you reason about how state and selectors produces props for the component
5. You get to the component definition where you reason about what is internal component state, what state came from the connected props and what props came from the parent, which might have been connected props as well

The fourth issue is related to how Redux with its immutability converts a state change to imperative logic. The code editor and preview window of Codesandbox needs to be manually handled by calling methods on them. Things like refreshing the preview iframe, executing preview code etc. The codeeditor has its own set of imperative methods that needs to be called based on changes to the state. With Redux it was necessary to render these components again and again, checking changed props in componentDidUpdate to evaluate if a method should be called. This just does not feel right and can be difficult to manage, as we see in this example from the old code.

Ives van Hoorne is all about producing value, so the stack itself is not a religion to him. Suggesting a refactor with Cerebral did not require a lot of convincing. Mobx-state-tree had caught his eye though. Cerebral ships with a state store, but it can be replaced by for example mobx-state-tree. So we agreed that replacing Redux with Cerebral and mobx-state-tree as state store would fix the before mentioned issues. Cerebral, with its declarative approach, would improve the readability and scalability of the complex business logic, while mobx-state-tree would give us type safety, avoid normalization, translate state changes to imperative logic using reactions and do optimal rendering out of the box.

I was ready to dive into refactoring!

Getting to know a new codebase

The biggest challenge refactoring Codesandbox.io is that I did not know the codebase at all. Luckily I have experience writing Redux applications so I did know the general pattern of reducers, selectors and actions. That said, understanding the pattern does not instantly give you a mental image of how the application works. You need to know the actual state inside the reducers, what the actions do and how the selectors brings state together to produce component specific state.

To start building my mental image I decided to just dive into it. I removed Redux, plugged in Cerebral and started handling one error after the other. As I did this I got to know the main components, what actions they triggered and what state they needed. As I went through the code I started to make improvements like optimistic updates. It started to feel doable and I thought it would be a good idea to create a WIP pull request. Of course I did not expect it to be able to merge instantly, but rebasing my changes on top of latest master made me realize that I was pretty much f*****. There were so many new features and other changes, it was impossible for me to get these two versions together. I must admit I felt a bit discourage. I had to leave it for a few days, not in frustration, but because procrastinating is my number one tool for problem solving.

The strategy

A week later the back of my brain had done its work. Instead of removing Redux I would rather use the “strangle strategy”. I had experience with this at a previous employer many years ago, putting a modern HTML5 layer on top of a legacy frame based project. With Codesandbox I would just expose Cerebral on top of Redux and implement the business logic and state needed one component at a time. For every Redux action, a Cerebral signal was triggered as well. A copy of the state from both reducers and the components were put into Cerebral, typed with mobx-state-tree. With the Cerebral debugger it was easy to validate that the correct state, side effects and state changes were made. That means Cerebral handles the business logic and state in addition to Redux, meaning no changes were made to the original application. This ensured that the application would run as normal and new features and other changes would merge in without much problems.

So the first critical milestone was to get through all connected components and create the Cerebral equivalent of Redux. When this was done the second critical milestone was to replace the Redux component connector with mobx-react. Instead of mapping actions and state we just inject all the Cerebral signals and state. Whatever state the component uses is automatically observed and a new render happens when the observed state is changed. Here is an example of how such a component was refactored:

Original Redux version

New Cerebral version

Cleaning up components

The third milestone was to clean up and restructure the components. In Redux there is a concept of “Container components”. Basically they are responsible for mapping state and actions and pass them down to “Presentation components”. With Cerebral you do not think this way. You connect state and signals exactly where you need them. That means the containers folder needed to go. Instead the existing pages folder would act as the connected components and the components folder would be the “not connected” reusable components.

The second part of this cleanup was to make every component a folder. That way all the style definitions, using styled-components, could be moved into their own files. For example:

Original Redux version

New Cerebral version

Creating a mental image

I believe creating a mental image is core to solving any problem. You have to understand what you are looking at as a whole to make changes to it. This is exactly what declarative code helps us with, and is why I started the Cerebral project. As an example we can look at the editor module. The file contains a declarative description of the initial state, any getters, computed and what events in the application causes what business logic to run. By looking at this one file you get a complete mental image of what the “editor” domain manages in the application.

Also the business logic in Cerebral is written declarative. It gives you an instant mental image of what is expected to happen when for example a user clicks a button. Looking at the sequence handlePreviewAction you see what can happen when the Codesandbox preview triggers this signal. There is no disturbing instructions to the computer, just domain specific labels for you as a developer to understand what is happening. Cerebral allows this syntax with the Function-Tree project, which is a functional composition tool.

Last but not least you also need to build mental images of executing code, what actually happened when you clicked the button. This is where the Cerebral debugger helps you. It has insight into all the running logic of your application, helping you understand what data has passed through any execution, what side effects has run and what state changes has been made.

Lessons learned

To summarize this article I want to point out some lessons learned. We changed out the stack to solve some issues in this project, but that does not mean everything became rainbows and butterflies. Redux, Mobx and Cerebral are all tools that manages the surprisingly complex problem space of state and UIs, but they have radically different approaches. That said, none of these tools are a silver bullet. They are all good tools to build applications, with their advantages and disadvantages. This is what I want to leave you with before sharing the good and the bad we experienced during this refactor:

Mobx-state-tree — The good parts

• Type definitions gives predictability out of the box. By looking at the model of your state you always know exactly what values are valid for any state. If you mess up, mobx-state-tree politely yells at you
• Observing state in components has the benefit of you getting access to the whole state store in any component. You point explicitly to the state you need and Mobx handles the component renders
• Getters and computed are one of the really great features of Mobx. It is challenging to optimally keep a calculated state value up to date when it is based on changes to other state values. Mobx handles this very well as it knows exactly when this calculated state value needs to update
• Reactions are a really good way to react to any state change and trigger imperative logic. This feature optimized the Codesandbox code editor and preview window as there was no rendering involved to run imperative logic. Original Redux version VS New Cerebral version

Mobx-state-tree — The not so good parts

• Implicit renders can be a problem when they do not work. This happened to me a few times. It is not always obvious what is actually being observed. Sometimes I just forgot to make the component an observer, other times I was confused by passing observed values as props to child component that did not observe. Also reactions is not always straight forward . For example I needed to run imperative logic when an array of errors changed. To handle this correctly I had to: store.editor.errors.map(error => error). The array reference itself does not change when an error is added er removed, so the map ensures that when the reaction runs due to a change it will return a new array which tells the reaction that it has updated… pretty mind bending
• Missing or bad errors happened in two different scenarios. There is no error if I try to add state that is not defined in the model. I experienced the state being ignored, throwing me down the rabbit hole as it was not available in the components. When you insert state with wrong type you get this huge error serializing the whole state tree and at the end the actual path to the wrong state value. Would be enough with the last part
• Mobx Observable Map is a needed inconsistency in the API. Where all other state values behaves as normal JavaScript values, a map of dynamic property keys requires you to use .set() and .get(). This often ends up in pointing to undefined values, due to forgetting to use .get()
• Mobx values are not plain JavaScript values. I feel rather dirty looking at arrays and objects defined by Mobx. They have been tampered with to enable observation. I am really looking forward to Proxy becoming available in all browsers, as I believe this will clean up the Mobx footprint on your values quite nicely

Redux — The good parts

• Handling state as plain JavaScript values is really great. It is also a really good match with React as you have life cycle hooks to inspect changes. Another great benefit is that a connected component and a component just receiving props from a parent is handled the same way. There is no observing or other special mechanisms. We actually had a challenge converting the code editor and preview to the new stack because it was shared with the embed application, which is only React. This was solved allowing access from the outside component
• Flow or Typescript support seems to be a given with the simple and minimal approach of Redux

Redux — The not so good parts

• Jumping files is a common routine in Redux applications. You are looking at an action prop in a component. To figure out where the prop came from you have to move up to the parent component which is in a different file. Then you have to move to the mapping function in the connector to figure out where the action is coming from. When you jump into the action it is probably a thunk that does multiple dispatches. To figure out what reducers handles the action dispatched you can end up having to search through your reducers
• Immutability is a great concept for avoiding unwanted mutations and change detection is as easy as checking the previous value with the new. The big problem with immutability though is that a nested change will also make a change to all parent values. For example a change to the code in a file, makes a change to the file, the array of files, the sandbox, the editor and to the whole store. If you are not careful about how you connect state you will get into problems. One way to reduce the effect of changes is to split up nested state into a more flat structure (normalize). So files are not children of sandboxes for example, but rather separated and linked by the id of the sandbox. The problem here is that you need additional logic to link them back together where needed. It also ruins your mental image of how things actually relate. One thing is normalizing authors as users, as users might be part of other entities… but the files and directories of a sandbox is related to only that one sandbox
• Containers separates state and actions from where they are actually used. It is not uncommon that you have to jump into a parent component or even another parent to figure out where the heck a property came from. Personally I really dislike this. In my component I want to know if I am using something from my state store and exactly where in the state store it came from. With mobx-state-tree I can say: props.store.preferences.settings.zenMode, where the equivalent in Redux would be: props.zenMode. You do not know if props.zenMode is just a normal prop or if it is state from your state store. You have to traverse up the component tree to verify

Cerebral — The good parts

• Functional concept for managing business logic, has not been explored much in frameworks. Redux has its addons, but other frameworks usually depends on a single function to contain all the logic needed for often very complex flows. In Cerebral you have a functional composition tool called Function-Tree which allows you to express business logic declaratively
• The Cerebral Debugger is pretty awesome. It gives you insight into your running logic. You always know what state has been changed, when it was changed and what side effects were run related to those changes. It is also a tool for beginners to understand what is happening in the application without even looking at code

Cerebral — The not so good parts

• Highly decoupled and composeable are not good concepts for Typescript and Flow. They try their best at inferring how your code runs, but when that code is dynamic in nature it gets tricky

An exciting progress in the Cerebral project is the fluent addon. This gives full type safety using Typescript. But this is for a later article!

A special thanks goes to Wayne Bamford for helping out with the initial refactoring. Mobx-state-tree is a really great project and I want to express my thanks to that team as well! And of course, last but not least, a big thanks to Ives van Hoorne for putting all his time into this very special project. I am really looking forward to what 2018 will bring in terms of features and other fun stuff :-)

The hardcoded React example gave high hopes, but there were still huge challenges to overcome.

• How would the Webpack server perform with many sessions?
• How would I get the users to install NPM packages to be bundled with the bin code?
• How could I make Webpack loaders configurable?

In this article we will not dive into the story behind the project and how these questions got answered, but rather look at the current state of the project. What makes it tick, how is it used on Codesandbox.io and Webpackbin.com. At the end I will tell you about future plans.

Separating user code from NPM packages

I quickly realized that bundling the bin code with the NPM packages would be way too slow. I had to separate them. Luckily Webpack has a concept called DLL bundles. They are basically separate bundles that your application bundle can hook into using a manifest. That means the user code can be bundled in isolation, making it insanely fast.

When the bundled bin code is loaded a separate script tag is injected in front of it, containing the dll bundle of the packages you chose for your bin. This dll feature of Webpack and the choice to take advantage of it was the critical point that lead to where we are today.

Creating the DLL bundle

My initial approach to creating a DLL bundling service was to manually grab packages from NPM and extract them into memory. There were two problems with this approach.

1. I was basically creating a really shitty NPM install… and even shittier Yarn install
2. When installing the packages and bundling the dll, the service was blocked from taking any more requests, only allowing one user to create a bundle at any time

In the current project the bundler runs with Yarn, which is super fast and caches packages across installs. The service is also split into two. It has a webpack-dll service which uses multiple webpack-packager services. That way requests are never blocked. All packagers might be busy, but at least then you get instant feedback on that.

webpack-dll

This service is responsible for taking requests for bundles. It has a list of webpack-packager instances which it can contact. It does so with load balancing, handling any errors, retrying etc. Any requests are put into a queue, meaning that if someone else is requesting the same set of packages they will wait for the same response. This logic also handles scenarios where the client retries before the bundler is done, the request will be put into the same queue. Last, but not least, the dll service also inserts the responded bundle from the webpack-packager instance into a database. That means when someone else is asking for the same bundle later, it will grab it from the database. Webpack-dll sits behind the jsdelivr.net CDN as well. Big thanks to Dmitriy Akulov for being such a great and patient person, I did bug him a lot :-) With the CDN users might never reach the webpack-dll service at all, it is returned immediately from the cache.

webpack-packager

This is where the dll bundling happens. It uses Webpack and its DLL plugin, though it is actually not as straightforward as you might think. You see, creating a completely separate and generic dll bundle is not what the DLL plugin does. By default a dll bundle actually needs to run with all packages installed, to resolve entries. That means webpack-packager has a lot of logic related to figuring out what entrypoints to include in the bundle. This is surprisingly difficult to do because there are no conventions on what to include from an NPM package. Webpack-packager has an alghoritm that figures out what to include based on filenames and folders related to properties in package.json. But this is not enough, we also need to define how to reach the entrypoints included using externals, with and without the file extension. And just recently we also added support for css files as entry points. I am breaking a sweat just listing this stuff, it has been some long nights :-)

NPM packages mayhem

And this brings us to a surprising reality I do not think the common developer is aware of. There are no strong conventions on defining a package.json file, what files to include and which folders to include them in. For example there is a property in package.json called “main”, which defines the entry point of your library. The big question is, “What is a valid entry?”. During development of webpack-packager there has been so many variations:

• It points to a prebundled version of the library
• It points to a prebundled and minified version of the library
• It points to a file without its exension, making it impossible to know if it is a file or a folder without checking the file system
• It points to a folder, because library has no specific entrypoint
• It points to nothing
• It points to an object with one property that points to the entry

In addition to this developers are adding new properties like “browser”, “module”, “unpkg”… but they sometimes point to different kinds of builds depending on the library. Some NPM packages includes the tests and the source code with the NPM package. This makes it especially tricky to figure out what should be included or not. Some use “-min.js”, while others “.min.js”. Other suffix names like “.es.js”, “.umd.js” and “.bundle.js” differs.

It would indeed be great to have an NPM package validator that created some consistency to this… even only for the sake of consistency. But you know, this is just me bitching about it, I should really do something about it myself… but yeah, thought I would mention it at least :-)

Webpackbin

Webpackbin is an application served from Firebase, which it also connects to directly from the client. It also connects to a service called webpack-sandbox which handles sandbox sessions. The files in your bin is passed to this sandbox service along with what packages and loaders to run. The service grabs the manifest.json, if needed, from webpack-dll and puts it into the configuration of your webpack compile middleware. When the sandbox responds, Webpackbin refreshes an iframe which talks to the same service. An index.html file is returned with injected scripts for the dll.js from webpack-dll and your app bundle. So Webpackbin grabs the manifest on the server and the dll file on the client.

Codesandbox

Recently I got a a partner in crime, Ives van Hoorne, creator of codesandbox.io, which has inspired the last architectural decisions and generally improved the service a lot. This is how his service uses the dll service.

CodeSandbox consists of a frontend application and a separate Phoenix server to handle API requests. Until last week we also had a separate node service to bundle the dependencies, but that’s not needed anymore now that we’ve created a common packager. In CodeSandbox we let the client evaluate all files, this means that we need to have the dependencies and the manifest ready in the browser. The client first requests the manifest for the dependencies from the dll service. This manifest contains the externals, which are mappings from dependency path to module id, and the manifest itself, this is a mapping to all entry points. The generated build from the dll service gets added to the iframe as soon as the manifest.json is downloaded. This dll file is a umd build, so it exposes a variable (in this case a function) on the window which we can call. As soon as the dll.js has been loaded we continue with transpiling and evaluation of the user written code, every time the require function encounters a dependency it checks in the externals of the manifest if it exists. In case it does exist it takes the module number from this mapping and executes the global function with this module number, the result is returned.

The future

The great thing about this architecture is that we ask people using the service for their own applications to contribute with a webpack-packager instance. That way it is free, but you are rather expected to contribute to the common good. All applications using the dll service can hit any instance of packagers. That way the service also scales well.

Currently the dll service is a bit of a black box, but we are planning to create a website which gives stats on the packagers, what they recently bundled, if anyone of them are down and so on.

And of course in addition to this we will keep working on supporting as many configurations of libraries as possible. Both webpack-dll and webpack-packager is open source and we will gladly assist you if you have your own application that could benefit from what it delivers.

Every event in your application triggers a signal that normally leads to one or multiple state changes. This is not special to Cerebral, this is how all applications work. A url change is also an event in your application, just like a button click or a websocket message. In Cerebral you treat URL changes the same way as any other event in your application, with a signal. The router does not affect your view/components layer at all. The benefit of this approach is consistency and flexibility. You can make a url change be anything you want.

Adding the router

The router is its own package, cerebral-router. You instantiate it simply by adding it to the Cerebral controller:

This means that when the root url is hit the signal rootRouted will trigger.

Simple page transitions

Let us imagine that our application has 2 pages:

How do we make our components render each page? Well, first of all we need a state that tells our components what page to display. Let us also add the two signals which will set the correct page:

As you can see we moved the router to its own file, this is recommended. We now have state that represents what page we are on, let us use it in a component to display the correct page:

The url triggers an event, which triggers a signal, which sets the application in the correct state. The components now update and renders based on the current state of the application. With Cerebral you think about url changes as any other event in your application.

Loading data on url change

The great thing about urls firing off signals is that you can run any side effect you need, also deciding when the page change actually occurs. Lets say the items page needed to grab the items to be listed. We add a couple of new states related to this and update our signal:

So now we change the page immediately and we indicate that we are loading the items before getting them. But we could flip this around:

Now we rather indicate with a state that we are preparing some data for a page. This could for example show a progress animation at the top of the page, typically what you see on Youtube and linkedIn. When the data is ready, the page is changed.

This already shows you the flexibility of treating url changes as events in your app instead of making it part of your component tree.

Dry up code with factories

Factories is an important concept in Cerebral and we can clean up our code a little bit:

We have now created a factory that allows us to define what page to change to. We did not clean up a lot here, but the changePage factory might do many different things related to moving from one page to an other.

Initial data

We have already looked at how to load data on a specific url event, the /items url, where we load the items. But sometimes you want to load some initial data no matter what url is triggered. We could implement this logic into changePage like this:

But you might not want to load initial data on all page changes. Maybe you have a welcome page, or an about page. Going directly to those should not load the initial data. To solve it you would just create a separate factory for it:

Authentication

In our simple application we want the user to be authenticated only when moving to /items.

As you can see we again use a factory, only we wrap changePage. That way we do not even change the page if the authentication fails. The authenticate factory could look something like this:

We just check to see if we have a user and continue the sequence of actions if we do. If not, we redirect back to front page. This is of course simplified and you might do lots of different things here, but the point is that you can easily compose this factory into whatever signal you want to prevent it from moving on when the user is not authenticated.

Nested routes

So what if we wanted to bind a route to show a single item? The single item is not a page by its own, it is a modal inside our items page. The way we solve this is simply by composing. We run the same logic as opening the items and then we add the logic for opening a single item:

There are thousands of way to handle urls, related side effects and UI. The Cerebral router gives you freedom to compose how all this fits together without constraints. It is up to you to build your “lego blocks” and put them together in a way that makes sense for your application.

Animate transitions

So a fancy feature of routing is to transition one route to the next with an animation. This is not integrated into the Cerebral router, because there is no need to. You would handle this like any state transition. For example with a React Transition Group we could change our App component to animate between the pages instead:

There really is nothing more to it.

Summary

In this article we looked into what a simple, yet powerful concept the Cerebral Router is. You map urls to signals and compose these signals in a way that makes sense for your application. When mapping to a signal you are free to run any state changes and side effects needed to resolve the url. Animations are introduced in the components like any other state change. The concept of factories allows you to compose together pieces of logic, even into new factories. No matter how complex this composition becomes it will all be displayed as one coherent flow in the debugger.

TL;DR — Cerebral is a JavaScript framework with a debugger that gives you great insight into how your application works. We often label applications as complex when it is hard to build a mental image of what is going on. Cerebral helps you handle this complexity both in code and with the debugger.

It all started about two years ago. I wanted to create a code teaching tool that was able to record and replay code changes and other interactions in the browser. At this time I was looking into React and Flux, but for some reason did not like (understand) React. Flux made a lot of sense to me though, so I created an implementation called jFlux. The ideas of Flux fixed many of the challenges I had met earlier building complex applications

The good things about jFlux was:

1. The view layer was separated from the state and business logic
2. Any component in the view layer could access any state of the application without depending on any other parts of the view layer
3. Any component could trigger any state change in the application

And this is where I had gone wrong so many times. As explained in the video above you will get into all sorts of problems when application state is intertwined with the view. When you build a small widget it is completely fine to put all the state inside the component, but then that component IS your “application”. When you have tens or even hundreds of components that depends on your application state, moving the state into a central state store allows any component to reach any state.

But there were also some bad things with jFlux:

1. It was crazy slow compared to angular/react (It actually used jQuery for components)
2. Defining actions inside stores made it difficult to follow complex flows of changes
3. I had also completely underestimated the need and complexity of asynchronous flows

So even though things were a lot better than my previous experiences, I was still not happy. Then I found Baobab.

A single state tree

The Baobab project was exactly what I needed. Instead of defining actions inside multiple stores, I could flip it around. I could have a single tree and do controlled state changes from the outside. I could also run whatever asynchronous stuff I needed with the defined state changes.

Instead of multiple stores, splitting state changes and the flow of state changes into separate files (pseudo code):

class MyStore extends Store {
  constructor() {
    this.foo = 'bar'
    
    this.listenTo('changeFoo', this.changeFoo)
  }
  changeFoo(value) {
    this.foo = value
  }
}

I could do everything in one function (pseudo code):

function getSomething() {

  tree.set(['something', 'isLoading'], true)
  ajax.get('/something')
    .then((result) => {
      tree.set(['something', 'list'], result)
      tree.set(['something', 'isLoading'], false)
    })
    .catch((error) => {
      tree.set(['something, 'error'], error.message)
    })

}

I could make my view layer ask for a change and then just do whatever state changes and complex asynchronous flows needed. Note here that this is still the “one way dataflow” of flux. But instead of creating rather verbose stores/reducers we just insert the new value on the path… because at the end of the day, that is exactly what a store/reducer does. Then the state tree tree will emit change events on the paths the components subscribes to. I wrote an article about this pattern here.

It was a success, but…

Even though I was happier and felt more in control than I ever had building complex web applications, I wanted to improve the developer experience. So when I saw that Elm had its own debugger…

…I got really inspired.

At this time I was also looking into immutability related to React and after watching “the database inside out”…

… it dawned on me how this actually worked. My view layer had to create a request for a state change, not actually do it. Then the application had to keep a history of these requests. When the application is in its initial state and these historic requests are rerun, well… my application should go to its historic state.

As it turned out, I was already requesting state changes:

tree.set(['foo', 'bar'], 'foo')

If I store the method name “set”, its path [‘foo’, ‘bar’] and its value ‘foo’, I had all the information I needed to rerun the state change.

A better debugger

So I implemented a debugger with time travel debugging. What I realised though is that the time travel debugging was not the thing that made the debugger so great, it was the log of state changes. And this is where I realised: We have these great tools for looking into our JavaScript, but it is very low level. What if we had a debugger on the same abstraction level as the application itself?

So I had some work cut out for me. First of all it was not enough to just show the log of state changes. In traditional examples we think of “increment” and “decrement” as “requesting a change”, but in real applications we might say “openNewsFeed”. Opening a newsfeed is crazy more complex than incrementing and decrementing a counter. We need to do many things like ensuring the user is logged in, maybe request multiple things from server, maybe the data returned requires new requests to the server. Also any of the requests might fail, which is also scenarios that needs to be handled. I wanted to show all of this information in the debugger and to do so I needed a way to express the flow. After experimenting a bit back and forth I realised that JavaScript actually has a really good way of defining flows:

[
  doThis,
  doThat
]

So doThis and doThat are functions that makes specific state changes. The array just indicates the order of how these state changes should run, one after the other. But what about asynchronous requests, how would I describe their conditional success and error outcomes? As it turns out, objects are good for that:

[
  doThis,
  getThat, {
    success: [
      setThat
    ],
    error: [
      setError
    ],
  },
  finallyDoThis
]

So now we have a structure the debugger can understand and visualise. They got a name, signals, and Cerebral was born. Combined with a single state tree it became evident how the debugger should work and after hundreds of hours and contributions, this is how it looks:

Running the flow of changes

We say that signals executes chains of actions. Where the chains are the arrays and actions are the functions referenced in the arrays.

As we kept experimenting we suddenly realised how powerful these arrays actually are. For example we can define two different chains and compose them together:

const chainA = [doThis, doThat]
const chainB = [doSomething, doSomethingElse]

[
  ...chainA,
  ...chainB
]

Composing chains like this is a very useful feature and you find yourself splitting existing chains into smaller chains to reuse parts of them in other chains.

Also factories proved themselves as a useful concept:

[
  set(['foo', 'bar'], true)
]

Using factories we could describe state changes directly in the chain, without even creating a custom action for it. This concept became so useful that we decided to create a core set of action factories we call operators:

[
  copy('input:foo', 'state:app.foo'),
  delay(200),
  set('state:app.bar', true)
]

We could even make chain factory operators. Like:

[
  copy('input:title', 'state:app.title'),
  ...debounce(500, [
    getTitles, {
      success: [
        showResults
      ],
      error: []
    }
  ])
]

We have spent a lot of time with these signals and they have proven again and again to be a really great way of describing what you want your application to do. You do not even have to be a programmer to understand what these chains describe. It is conceptually just a decision tree with some labels on it. Describing how our applications updates their state is where most of the complexity comes from, in my opinion.

Render performance

When we talk about view layers there are two things that affects its performance.

1. Its pure speed of recalculating what changes is needed in the DOM
2. Its ability to do recalculations at specific points in the component tree

Snabbdom is a superfast virtual dom implementation, but you can not tell a single component somewhere in your component tree to do a new recalculation. You always have to recalculate the whole application. React may be slower in pure speed, but you can point to a specific component, which Cerebral takes advantage of. Inferno is fast no matter what, but Cerebral also here takes advantage of its ability to recalculate a specific component in the component tree.

The way this works is that each component defines what state paths it is interested in. When Cerebral notifies the view layer about a change of state it actually tells what paths changed. Unlike Redux where each connected component needs to reiterate its state dependencies and see if their values changed, Cerebral can just iterate this small object defining what paths has been affected and tell specifically what components needs to recalculate. This means that Cerebral does not depend on immutability to optimize rendering. With this approach we can also visualise in the debugger how state changes affects your components, as seen in the video introduction above.

The team

A big part of the Cerebral story is also the team. Many people have contributed, but I want to mention specifically the initial core team of Aleksey, Garth and Brian. Aleksey is the super organised, low level and structured guy. Garth is the thoughtful, considerate and responsible guy. Brian is the very outgoing, funny and super optimistic guy. I am the impatient, always with a plan and always executing something guy. That does not mean we are purely only these personalities, it is more of how we balance each other out I think. And the funny thing is that this is completely coincidental. There were no interviews, no tests and no references to previous work… it was only enthusiasm for the project itself.

And this is what makes open source such a fantastic process. I still think a lot about how a guy from Russia, another in Vienna, one in Florida and me from Norway can find each other online, get together around a project and squeeze in an insane amount of hours of private time. Why do we do it? I can not speak on behalf of the other guys, and all the other contributors who have made Cerebral such a great experience, but I think they all can relate to making a difference for others is a fantastic feeling. I would not be doing this if it was not helpful to others. Of course it is not the perfect solution, no solutions are… but it is a real tool, solving real challenges of application development and I think it is worth a look :-)

Thanks for reading and if you want to know more, take a look at our website.