christianalfoni

True isomorphic apps with React and Baobab

Sun, 01 Mar 2015 09:21:30 +0000

So this little library Baobab continues to surprise me. The previous article I wrote on this used a strategy where you would lock up all your components, but have a dependency to the state tree of the application in each component that needed it. The individual components could point cursors into the state tree, allowing the component to extract state from the state tree and render itself whenever the cursor notified about a change. This optimized the rendering of React JS and gave a very good FLUX structure to your application.

When going isomorphic though... wait, let me explain what an isomorphic app is before we move on. Typically with a single page application you pass only som basic HTML and script tags on the initial page request. When the page and scripts load, your application starts. You probably have a loader indicating the scripts loading, or if not, just a white screen. This might not seem like such a big problem, but it is. Visitors on your page or application really does not like waiting, not even for a few hundred milliseconds. The google bot collecting page information does not like this either. It requires a complete HTML page to be served when hitting your URL.

So, when going isomorphic, you will actually render your application on the server and deliver it along with your base HTML and script tags. That way the user will instantly see content. React JS is especially elegant in handling this because it will piggy back the existing HTML. What I mean is that when React JS has loaded and you render your application again on the client it will notice that the existing HTML on the page is rendered by React on the server. So instead of doing a normal render, it will just register event listeners etc.

Why change Baobab strategy?

When loading the application components on the server it will load all the dependencies of each component also. If you are depending on business logic, like some module that changes the state of the tree, that module will probably have its dependencies too. What you end up with is loading your whole client side application on the server, when you only wanted to load the components. This could get you into trouble. There is also a matter of trying to find a way to isolate components to a level where they really are just components.

The current injecting possibilities with React

There are two strategies to injecting state into your application. The first one is using props and the other is using context.

Props

var Baobab = require('baobab');

var store = new Baobab({
  items: []
}, {
  shiftReferences: true
});

var AppComponent = React.createClass({
  render: function () {
    return (
      <h1>Hello app, you have {this.props.store.items.length} left</h1>
    );
  }
});

var render = function () {
  React.render(<AppComponent store={store.get()})/>, document.body);
};
store.on('update', render);

Okay, so now we are passing the complete store down to our components and whenever the tree changes, we pass it down again. Since the store shifts references up the tree when a change is done, we can safely use the PureRenderMixin on our components. But we have a problem.

Imagine all the sub components that makes up your app. Most of them will need access to this store object. They can only get that access if their parent passes it down. This pretty much means that all your components has to pass a store prop down to its children. That is a lot of work and it couples your components, which is not ideal.

Context

A different strategy is using something called a context. Now, this is not very well documented, but good research is done with this article. withContext is deprecated in favor of using getChildContext. Lets have a look at that:

var Baobab = require('baobab');

var store = new Baobab({
  items: []
}, {
  shiftReferences: true
});

var WrapperComponent = React.createClass({
  childContextTypes: {
    store: React.PropTypes.object
  },
  getChildContext: function () {
    return {
      store: this.props.store
    };
  },
  render: function () {
    return <AppComponent/>
  }
});

var AppComponent = React.createClass({
  contextTypes: {
    store: React.PropTypes.object
  },
  render: function () {
    return (
      <h1>Hello app, you have {this.context.store.items.length} left</h1>
    );
  }
});

var render = function () {
  React.render(<WrapperComponent store={store.get()})/>, document.render);
};
store.on('update', render);

As you can see we use a wrapper that sets a context for the application. Any sub component, regardless of their parent, can use the contextTypes property and extract the store. That is great! We have removed the need to pass the store down as properties. But we have a problem.

In the Q&A at react-conf 2015, around 09:00, there is a question about context. The answer does not flesh out exactly why it is a bad idea, but I think I know why. The problem is two fold, but they are both related to using PureRenderMixin.

The PureRenderMixin does not check if the values on the context object has changed, making it unable to verify that a render is necessary
A parent component might not be using the context, but the child does. If the parent uses PureRenderMixin it will not render the child when the context updates

A third challenge to mention here, which exists both using props and context, is that we loose the possbility to just render components that actually needs to update. The store is injected from the top on every change.

So can we get the best of both worlds?

I will go through this section showing how this works on the client and server in parallell. Lets get going.

The injected state

We will not inject the state the same way on the client and the server. On the client we will inject the Baobab tree itself, but on the server we will just inject a plain object. Lets see it in action:

client

var React = require('react');
var Baobab = require('baobab');
var WrapperComponent = require('./AppWrapper.js');

var store = new Baobab({
  items: []
}, {
  shiftReferences: true
});

// As you can see we are not using store.get(), but passing the actual store
React.render(<WrapperComponent store={store})/>, document.render);

server

var React = require('react');
var WrapperComponent = require('./app/AppWrapper.js');

// We just create a normal object and inject that
var store = {
  items: []
};

// We will see later what we will do with this html
var html = React.renderToString(<WrapperComponent store={store})/>);

How the wrapper exposes the context

Now, this works exactly the same on the server and client.

WrapperComponent.js

var React = require('react');
var AppComponent = require('./AppComponent.js');

var WrapperComponent = React.createClass({
  childContextTypes: {
    store: React.PropTypes.object
  },
  getChildContext: function () {
    return {
      store: this.props.store
    };
  },
  render: function () {
    return <AppComponent/>
  }
});
module.exports = WrapperComponent;

The wrapper component will expose either the Baobab state tree itself or just a plain object, depending on it being the client or the server.

A mixin to extract state

As we know from the existing mixins for Baobab it is possible to extract state by using a cursors object defined on the component itself. Since we are using the Baobab state tree a bit differently here, we have to create a new mixin. I actually created a pull request for this. It ended up in a discussion that brings up a different approach. It uses an application event hub to decouple business logic from the components. I encourage you to check it out! But now lets see how we use the mixin on a component

SomeComponent.js (client and server)

var React = require('react');
var ContextMixin = require('./ContextMixin.js');

var SomeComponent = React.createClass({
  mixins: [ContextMixin],
  cursors: {
    list: ['admin', 'list']
  },
  render: function () {
  
    // Notice we point to the state and not the context
    return (
      <h1>There are {this.state.list.length} items in this list</h1>
    );
  }
});
module.exports = SomeComponent;

The only thing we depend on is the mixin. As the state tree is injected into the context of our application there is no direct dependency to it. The mixin will move the value from the context to the state of the component to allow PureRenderMixin to do its work.

And now how the mixin actually works:

ContextMixin.js

var React = require('react/addons');

// We have to know if we are on the client or the server
var isBrowser = !(global && Object.prototype.toString.call(global.process) === '[object process]');

var ContextMixin = {
  
  // We add the PureRenderMixin for optimized rendering
  mixins: [React.addons.PureRenderMixin],
  
  // We grab the store from the context
  contextTypes: {
    store: React.PropTypes.object
  },
  componentWillMount: function () {

    if (!this.context || !this.context.store) {
      throw new Error('You have to pass a store to you app wrapper');
    }
    
    // If no cursors present, just return
    if (!this.cursors) {
      return;
    }

    // Prepare a map of listeners to
    // state update
    this.subscriptions = {};
    
    // This is where we create subscriptions to cursors so that
    // the component knows about changes
    var component = this;
    var createSubscription = function (key, cursor) {
      return function (value) {
        var state = {};
        state[key] = cursor.get();
        component.setState(state);
      };
    };

    // We go through the cursors
    var state = {};
    Object.keys(this.cursors).forEach(function (cursorKey) {

      // If we are in the browser we move the current state of the
      // cursor over to the state object, using the key defined on
      // the cursor as the key on our state object. We also register
      // a listener for state changes
      if (isBrowser) {

        var cursor = this.context.store.select(this.cursors[cursorKey]);
        var callback = createSubscription(cursorKey, cursor)
        state[cursorKey] = cursor.get();
        this.subscriptions[cursorKey] = {
          cursor: cursor,
          callback: callback
        };
        cursor.on('update', callback);

      // If we are on the server we use the same cursor path defined.
      // But instead of using the Baobab API, we use the path to drill 
      // into the state object and set the state
      } else {

        var path = this.cursors[cursorKey];
        var value = path.reduce(function (contextPath, pathKey, index) {
          return contextPath[pathKey];
        }, this.context.store);
        state[cursorKey] = value;

      }

    }, this);
    
    // Then we actually put that state on the component
    this.setState(state);

  },
  
  // Unregisters listeners of state change
  componentWillUnmount: function () {
    Object.keys(this.subscriptions).forEach(function (subscription) {
      this.subscriptions[subscription].cursor.off('update', subscription.callback);
    }, this);
  }
};
module.exports = ContextMixin;

The complete flow

Now let us take a look at the complete flow from server to client. We are going to use the jsx file extension as we want to use components on the server too. The benefit of using the jsx extension is that node will only transpile jsx files, not normal js files. Let us first look at the index.html file that we want to load up:

index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8"/>
  </head>
  <body>
    {{APP}}
    <script>
      window.store = {{STORE}}
    </script>
    <script src="app.js"></script>
  </body>
</html>

We create a placeholder for where we want to put the HTML of our app. We also put the state we created on the global window object. This allows our client store to grab that state and that way being in sync. We will see this soon.

server.js

// We make jsx syntax available to node
require('node-jsx').install({extension: '.jsx'})

var express = require('express');
var fs = require('fs');
var path = require('path');
var React = require('react');

// We use a factory as our main server file does not support JSX, only required files
var AppWrapper = React.createFactory(require('./app/AppWrapper.jsx'));

// We fire up an express server
var app = express();

// We read the contents of an HTML file we have
var index = fs.readFileSync(path.resolve(__dirname, 'index.html')).toString();

app.get('/', function (req, res) {

  // First we build up the contents of the store. This could be fetching database stuff
  // or whatever
  buildStoreContent()
    .then(function (store) {
    
      // We render the application to an HTML string, passing in the store
      var app = React.renderToString(AppWrapper({store: store}));
      
      // We replace our placeholders with both the app html itself and the state of the store. 
      // You might prefer loading the store state with ajax after initial page load in case 
      // it is quite large. It is a balance you have to decide
      var html = index.replace('{{APP}}', app).replace('{{STORE}}', JSON.stringify(store));
      
      res.type('html');
      res.send(html);
    });

});
app.listen(3000);

So when our client now goes to localhost:3000 the HTML responded will have the HTML of our app and a store object containing the state it was based upon. The browser will also load up app.js. This is a bundled file using either browserify or webpack, so let us look at the main entry file:

main.js (entry point bundled into app.js)

var React = require('react');
var Baobab = require('baobab');

// Coponent uses our ContextMixin
var WrapperComponent = require('./app/WrapperComponent.jsx');

// We grab the state from the window
var store = new Baobab(window.store, {
  shiftReferences: true
});

React.render(<WrapperComponent store={store}/>, document.render);

So when our app.js file launches it will do the exact same thing as the server did, only with a Baobab store instead. The beauty of it is that React JS understands that the current HTML is part of the application. It will basically just wire up the listeners to the store, and do updates when the store has a change. The really cool thing about this is that the components listens to the store completely decoupled from their parent components. This means that the rendering of the application is still as optimized as the strategy explained in the previous article.

Changing the state of the store with actions

But how do we actually go about changing the state of our store from within the components? It would not be a good idea to give each component a dependency to the store, as that is actually what we wanted to avoid. Well, why not use the context? Actions will never be triggered on the server side. They are triggered when the user interacts with the application or some other client module interacts with the store, maybe a websocket service. So how would we do this? Let us extend our wrapper and mixin to also handle actions:

WrapperComponent.jsx

var React = require('react');
var WrapperComponent = React.createClass({
  childContextTypes: {
    store: React.PropTypes.object,
    actions: React.PropTypes.object
  },
  getChildContext: function () {
    return {
      store: this.props.store,
      actions: this.props.actions
    };
  },
  render: function () {
    return <AppComponent/>
  }
});
module.exports = WrapperComponent;

ContextMixin

var React = require('react/addons');
var isBrowser = !(global && Object.prototype.toString.call(global.process) === '[object process]');

var ContextMixin = {
  mixins: [React.addons.PureRenderMixin],
  
  // Adding actions
  contextTypes: {
    store: React.PropTypes.object,
    actions: React.PropTypes.actions
  },
  componentWillMount: function () {

    if (!this.context || !this.context.store) {
      throw new Error('You have to pass a store to you app wrapper');
    }
    
    // We reference the actions on the component itself, to
    // shorten the syntax. this.actions, instead of this.context.actions
    this.actions = this.context.actions;
    
    // ... rest of mixin

  },
  componentWillUnmount: function () { ... }
};
module.exports = ContextMixin;

Okay, so now we are able to pass actions down through our components. We do not have to do any changes on the server, as actions will not be triggered there. But let us pass some actions on our client, looking at our entry point file again:

main.js (entry point bundled into app.js)

var React = require('react');
var Baobab = require('baobab');
var WrapperComponent = require('./WrapperComponent.jsx');

// Just looking at window.store
window.store; // { list: [] }

// We grab the state from the window
var store = new Baobab(window.store, {
  shiftReferences: true
});

// We create an action to update the store
var actions = {
  addItem: function (item) {
    store.select('list').push(item);
  }
};

// And we pass those actions down
React.render(<WrapperComponent store={store} actions={actions}/>, document.render);

So inside our WrapperComponent somewhere we have a component that wants to trigger our addItem action. Lets imagine:

ListComponent.jsx

var React = require('react/addons');
var ContextMixin = require('./ContextMixin.js');

var ListComponent = React.createClass({
  mixins: [ContextMixin, React.addons.LinkedStateMixin],
  cursors: {
  
    // We grab the list from the store and put as "list"
    // on the components state object. We also listen to
    // any changes to this list value
    list: ['list']
  },
  
  // We return an initial state for our input that
  // will be the interaction of adding a new item to
  // the list
  getInitialState: function () {
    return {
      title: ''
    };
  },
  
  // We just point to this.actions and run
  // the method
  addItem: function () {
    this.actions.addItem(this.state.title);
    this.setState({
      title: ''
    });
  },
  renderItem: function (item) {
    return <li>{item}</li>
  },
  render: function () {
    return (
      <div>
        <form onSubmit={this.addItem}>
          <input valueLink={this.linkState('title')}/>
        </form>
        <ul>
          {this.state.list.map(this.renderItem)}
        </ul>
      </div>
    );
  }
});

module.exports = ListComponent;

As we can see, using the mixin, we can point to actions on the component itself. This rather than this.context.actions. If your application has a lot of actions you could just namespace them into this.actions.todos.add, this.actions.notifications.fetch etc.

Summary

In my opinion this is exactly how I want to build my apps. I want to inject state on the server and render the application there, but still allow for highly optimized rendering on the client. I want my components to be as pure as possible. Depend on as little as possible. Everything the components needs to know about, they know through the context they are running in.

I have used this technique on a project I am working on called EmptyBox. It is a hackable blog service using React JS. It also has some other cool features you can not achieve without React JS.

To see a more simple example using this technique you can check out this repo.

Please feel free to use the mixin documented here or check out the alternative strategy explained in the pull request. Thanks for reading!

The great Angular component experiment

Sun, 22 Feb 2015 09:21:30 +0000

My last months has been heavily devoted to understanding React JS and FLUX patterns. In parallell with this I have been helping out on an Angular project. Angular was chosen because the guy who got me involved is a Java developer, and of course he likes Angular. In these months working together there has been a lot of discussion on, "Why does Java developers love Angular?". I have given my cents on React JS, using components, and the one way flow of FLUX. The discussions has not been in the form of "one is better than the other", but despite his open mind, it was very difficult to explain what makes React JS and FLUX so great.

So I got this idea. What if I did an experiment. What if I found a way to make Angular use components heavyily inspired by React JS, and to boot, a strong FLUX pattern. Would the typical Angular developer see the benefits of React JS and FLUX? And even more interesting, could React JS and FLUX learn something from Angular?

Enforcing the experiment

If you are an Angular developer you probably already know that the Angular team is encouraging you to use directives as a component concept, preparing you for the next versions of Angular where they will indeed use components. If not, read this article. You can also see an introduction to components in Angular 2 here.

React JS will have a huge impact on the JavaScript community, it already has really. It is not just a View layer for writing DOM. It is a generic JavaScript component concept that can be used to render anything. Canvas, WebGL, Gibbons (netflix TV platform), iOS native, Android native etc. FLUX on the other hand is a pattern for handling state. In my opinion it is currently evolving in the direction of being a single state store you "inject" into your main application component. This single injected state store and React JS allows you to render the whole application server side in an initial state and deliver it over the wire, where React JS takes over. It does not matter what UI technology is underneath, as what you send over the wire are the calculated operations needed to put your app in the correct state. That being an HTML string or a data structure for a native layer.

So to sum up. I want to bring React JS and FLUX concepts into Angular so that you can see the benefits in an environment an Angular developer can more easily relate to. It is also interesting to see how concepts in Angular actually merges quite well with FLUX. Maybe FLUX could take some inspiration from Angular? Last but not least I have been working on flux-angular which could benefit from using the evolved FLUX pattern introduced here. Follow that discussion on this issue.

Nailing the concepts

First we have to settle on the concepts. At no surprise we will of course have a component concept. It will look a lot like a React JS component. But we also need the FLUX parts. Since Facebook released information on how they implement FLUX it has evolved quite a bit. I wrote an article about Baobab which is a single event emitting and semi-immutable state tree. I will take those concepts and bring it into the experiment. This specifically results in an actions concept and a store concept.

You can play around with the experiment, try out the syntax and build something by going to this repo. I encourage you to try it out, get into the mindset of components and FLUX. I promise it will at least give you inspiration on how you think about building applications. The demo application is the todomvc.com todo application.

The requirements

There are a couple of things that Angular fundementally does differently, which we have to find a way to handle.

Immutability

There is one very important part we have to handle to make this experiement work. Completely immutable state in the store. So what does that mean? And why do we need it? Immutability, in this context, refers to that Angular, or you for that matter, can not change objects and arrays located in the stores directly. This solves two things. First of all it prevents Angulars two-way-databinding to interfere with our application state. With a FLUX pattern we need full control of state flow. Secondly it prevents Angular from changing application state with e.g. hashes in ng-repeat and yourself from making changes that will affect other parts of your application using the same state.

The before mentioned Baobab is only semi-immutable, meaning that a change in the tree will indeed change references, but the state grabbed from the store can still be mutated and affected by other parts of your code. So what to do?

I started looking at Freezer, which is a great project. Freezer is the same concept as Baobab, a state tree, but at the same time is completely immutable. Whenever you do a change to the state tree, you get a completely new state tree. Though the concepts are great I met a couple of issues, so I decided to create my own immutable-store. It is running under the hood of this implementation and gives a very simpe API to change the state of your application, without allowing Angular or components interfere with that state. In other words, your app and UI state gets very predictable.

Monkeypatching

For this experiement to work it has to look like something the Angular team could have come up with themselves, if they had a split Google/Facebook personality :-) This means we will add three new methods to Angular modules, in addition to the existing controller, directive, factory, service etc. Those methods are: component, actions and store.

Lets implement!

So first of all we need our component. Let me just throw the code down there and then we will go through some concepts:

angular.module('app', ['experiment'])
  .component('myComponent', function () {
    return {
      message: 'I am a component',
      componentWillMount: function () {
        // Runs in the pre link lifecycle (before children are rendered)
      },
      componentDidMount: function () {
        // Runs in the post link lifecycle (after children are rendered)
      },
      render: function () {
        // Using the ES6 multiline syntax
        return `
          <h1>Hello world - {{message}}</h1>
        `;
      }
    };
  })

Using this component would look like this:

<my-component></my-component>

What we have basically done here is wrap the generic and powerful directive concept into a component specific concept, inspired by React JS. Let us explore this component a bit more.

Changing internal state

To change the state of the component you can define a method, call it and just change the state. When changing the state of the component you do want it to render again. Two-way-databinding is powerful in that sense. With React JS you would have to specifically tell the component to update with a method. Take a look at the this example:

angular.module('app', ['experiment'])
  .component('myComponent', function () {
    return {
      message: 'I am a component',
      color: 'red',
      flipColor: function () {
        this.color = this.color === 'red' ? 'blue' : 'red';
      },
      render: function () {
        return `
          <div>
            <h1 style="color: {{color}}">Hello world - {{message}}</h1>
            <button ng-click="flipColor()">Flip color</button>
          </div>
        `;
      }
    };
  })

And with React JS:

var MyComponent = React.createClass({
  getInitialState: function () {
    return {
      message: 'I am a component',
      color: 'red'
    };
  },
  flipColor: function () {
    this.setState({
      color:  this.state.color === 'red' ? 'blue' : 'red'
    });
  },
  render: function () {
    return (
      <div>
        <h1 style={'color:' + this.state.color}>Hello world - {this.state.message}</h1>
        <button onClick={this.flipColor}>Flip color</button>
      </div>
    );
  }
});

Props (attributes)

<my-component showMessage="{{true}}" message="Passing props to a component"></my-component>

And our component:

angular.module('app', ['experiment'])
  .component('myComponent', function () {
    return {
      render: function () {
        return `
          <h1>
            Hello world 
            <span ng-if="props.showMessage" ng-click="logMessage(props.message)">
              - {{props.message}}
            </span>
          </h1>
        `;
      }
    };
  })

So we have the well known attributes concept here, but it works a bit differently. In React JS we call these attributes props and they are normal JavaScript expressions passed to the component. Angular requires you to hardwire this relationship with a "scope" definition in a directive. It is very confusing that some attributes are evaluated as JavaScript and some are not. In my opinion it is better to define this when passing the attribute, not receviving it. Now you clearly see what is JavaScript and what is just a string.

But where is logMessage() defined? This is where things start to become a bit interesting. The properties you add to your components in this experiement are attached to the scope of the component. The component pretty much IS what you earlier thought of as $scope. Now scope in Angular is actually a really cool concept. It creates a decoupled relationship between the components. What this means in practice is that if some component used myComponent defined above the component would only need to define a logMessage method and it could be used. Let me show you:

angular.module('app', ['experiment'])
  .component('myParent', function () {
    logMessage: function (message) {
      console.log(message); // Will log: "whatup"
    },
    render: function () {
      return `
        <my-component showMessage="{{true}}" message="whatup"></my-component>
      `;
    }
  })
  .component('myComponent', function () {
    return {
      render: function () {
        return `
          <h1>
            Hello world 
            <span ng-if="props.showMessage" ng-click="logMessage(props.message)">
              - {{props.message}}
            </span>
         </h1>
        `;
      }
    };
  })

What is not so good about this is that it is harder to reason about how the logMessage method is being called. I would prefer passing the function as a prop just like React JS, but that is not possible with Angular without the reverted hard wiring we want to avoid.

React JS has pretty much the exact same syntax, though it is transpiled into normal JavaScript. No parsing and evaluating, but you do have to pass the callback:

<my-component showMessage={true} message="Passing props to a component" logMessage={this.logMessage}></my-component>

And you would build your component something like this. Allowing for more of a traditional JavaScript mindset.

var MyComponent = React.createClass({
  renderMessage: function () {
    return (
      <span onClick={this.props.logMessage.bind(null, this.props.message)}>
        - {this.props.message}
      </span>
    );
  },
  render: function () {
    var message = this.props.showMessage ? this.renderMessage() : null;
    return (
      <h1>Hello world {message}</h1>
    );
  }
});

So this shows you clearly that React JS is "JavaScript first". You solve dynamic behavior of your UI using traditional JavaScript, not HTML attributes. This is also partly the reason why React JS is so fast.

Building a small app

So now we have begun to look into how a component works. Now let us see why components are great! Let us create, yes, a todo application. What we need first is our main app component. I will be writing the HTML inside the components, which you would do with React JS. I hope this will show you why it is a good idea to have your tightly connected HTML with the component logic. I will be using ES6 multiline string to write the HTML. This is to give you an impression of how it would look like using React JS where you actually would write HTML (JSX).

angular.module('TodoMVC', ['experiment'])
  .component('todoMvc', function () {
    return {
      render: function () {
        return `
          <div>
            <h1>My awesome Todo app</h1>
            <todo-creator></todo-creator>
            <todo-list></todo-list>
          </div>
        `;
      }
    };
  });

Our first component is our wrapper for the application. It holds the title and fires up two other components.

angular.module('TodoMVC', ['experiment'])
  .component('todoMvc', function () { ... })
  .component('todoCreator', function () {
    return {
      title: '',
      createTodo: function () {
        // Add todo coming soon...
        this.title = '';
      },
      render: function () {
        return `
          <form ng-submit="createTodo()">
            <input ng-model="title"/>
          </form>
        `;
      }
    };
  });

So now we have created a completely isolated component. It does not depend on anything and you can use it as many times as your want throughout your application. Or just move it somewhere else, if you wanted to. Now you start to see how small these components are. The fear of putting lots of HTML inside your JavaScript is not really valid when you think components. They are small, pure and specific.

Moving on to the list:

angular.module('TodoMVC', ['experiment'])
  .component('todoMvc', function () { ... })
  .component('todoCreator', function () { ... })
  .component('todoList', function () {
    return {
      render: function () {
        return `
          <ul>
            // Todos coming soon...
          </ul>
        `;
      }
    };
  });

And now lets create a component for each todo. Again, we see how the scope helps us create a relationship between parent and child components. When we insert the todoItem below with ng-repeat on our todos, Angular implicitly creates a scope for each todoItem component. Think of it as Angular pre-attaching todo and $index to the todoItem component. So we can just start using it:

angular.module('TodoMVC', ['experiment'])
  .component('todoMvc', function () { ... })
  .component('todoCreator', function () { ... })
  .component('todoList', function () { ... })
  .component('todoItem', function () {
    return {
      remove: function () {
        // Removing a todo coming
      },
      toggle: function () {
        // Toggling a todo coming
      },
      render: function () {
        return `
          <li>
            <input 
              type="checkbox" 
              ng-checked="todo.completed" 
              ng-click="toggle(todo)"
            /> {{todo.title}} <button ng-click="remove(todo)">remove</button>
          </li>
        `;
      };
    };
  });

So now you see how we think very differently than one would traditionally with Angular. We are thinking each part of our application as a very focused and isolated component, instead of thinking our application as a piece of HTML and adding behavior to it. It is more JavaScript first, than HTML first. Our render methods are returning a UI tree description which happens to be HTML. If we used React JS it would use this render method several times to figure out if the returned tree had changed. When changes are detected a specific operation to sync that change with the actual UI layer would be triggered. This is not possible with Angular of course, but now you start to see why React JS is so extremely fast.

Store

So what about our todos? Where do we want to put them? In traditional Angular you would probably put them into a controller, or maybe a service if you are thinking scalability. We are going to use a concept called a store. A store holds some state for a section of your application and acts like a branch on the application state tree. This allows you to access any state anywhere in your application and you can prepare all the state on your server on the initial load. Just put it into the application state tree and you are ready to go.

Think of the state tree as the puppet master of your application, and the components as puppets. You should be able to force any UI state in your application just by changing properties in the state tree.

angular.module('TodoMVC', ['experiment'])
  .component('todoMvc', function () { ... })
  .component('todoCreator', function () { ... })
  .component('todoList', function () { ... })
  .component('todoItem', function () { ... })
  .store('todos', function () {
    return {
      list: []
    };
  });

Thats it! We have now made todos.list available to all current and future components, but none of them are able to change either the list or the todos directly. Lets take a look at how we use this state in our todos list:

angular.module('TodoMVC', ['experiment'])
  .component('todoMvc', function () { ... })
  .component('todoCreator', function () { ... })
  .component('todoList', function () {
    return {
      render: function () {
        return `
          <ul>
            <todo-item ng-repeat="todo in todos.list track by $index"></todo-item>
          </ul>
        `;
      }
    };
  })
  .component('todoItem', function () { ... })
  .store('todos', function () { ... });

As we learned each component in the ng-repeat will have todo and $index attached to it. This means that the todo is available inside the todo-item component.

Actions

So lets look at how we would change the state of our store. In this experiment we are exposing a new method on the angular module called actions. It is pretty much just a factory:

angular.module('TodoMVC', ['experiment'])
  .component('todoMvc', function () { ... })
  .component('todoCreator', function () { ... })
  .component('todoList', function () { ... })
  .component('todoItem', function () { ... })
  .store('todos', function () { ... })
  .actions('todosActions', function (flux) {
    return {
      add: function (title) {
        var store = flux.get();
        store = store.todos.list.push({
          title: title,
          completed: false
        });
        flux.set(store);
      },
      remove: function (todo) {
        var store = flux.get();
        store = store.todos.list.splice(store.todos.list.indexOf(todo), 1);
        flux.set(store);      
      },
      toggle: function (todo) {
        var store = flux.get();
        
        // The todo is an object from the store. All mutations on store
        // objects returns the store
        store = todo.set('completed', !todo.completed);
        flux.set(store);
      }
    };
  });

And now let us update components using the actions:

angular.module('TodoMVC', ['experiment'])
  .component('todoMvc', function () { ... })
  .component('todoCreator', function (todoActions) { 
    return {
      title: '',
      createTodo: function () {
        todoActions.add(this.title);
        this.title = '';
      },
      render: function () {
        return `
          <form ng-submit="createTodo()">
            <input ng-model="title"/>
          </form>
        `;
      }
    };
  })
  .component('todoList', function () { ... })
  .component('todoItem', function (todoActions) { 
    return {
      remove: function (todo) {
        todoActions.remove(todo);
      },
      toggle: function (todo) {
        todoActions.toggle(todo);
      },
      render: function () {
        return `
          <li>
            <input 
              type="checkbox" 
              ng-checked="todo.completed" 
              ng-click="toggle(todo)"
            /> {{todo.title}} <button ng-click="remove(todo)">remove</button>
          </li>
        `;
      };
    }; 
  })
  .store('todos', function () { ... })
  .actions('todosActions', function () { ... });

So there we have it. Our application using components and an immutable state tree.

Summary

If you are an Angular developer I hope this little experiment gave you some insight into why React JS developers loves thinking components. Angular 2 will have a very similar component concept, though they will still rely on templates. In my opinion you are missing out on one of the really good parts of components. Having UI logic and description in one and the same file. That said, maybe Angular has a different "team target". It is of course easier for a team with split HTML/CSS knowledge and JavaScript knowledge to build Angular apps. But as the complexity of web applications will just increase, I think a pure HTML/CSS developer will be a thing of the past. Hopefully Angular 2 will allow JSX, or at least something similar.

If you know a bit about React JS and specifically FLUX it is interesting to look at Angulars $rootScope. You can "inject" state at the top of your application and make it available to all components. This is something React JS is not able to do. You have to pass that "injected state" as properties down through your components, making them very dependant of each other. The challenge with bringing a "scope concept" into React JS though is that you might have a parent component that depends on one state, and a child component depending on an other. Since rendering a component is determined by a change in the dependent state you would get into situations where the child would not update, due to the parents state did not change. Hopefully some very smart people at Facebook is working on this :-)

Okay, so thanks for going through this experiement and hopefully it had some value to you!

Plant a Baobab tree in your flux application

Fri, 06 Feb 2015 09:21:30 +0000

All standards, libraries, practices, architectures and patterns needs some time to evolve before becoming widely accepted. The flux architecture is no different. After Facebook released their React JS project the suggested flux architecture has evolved into many different shapes and colors. Some of them more accepted than others. In this article we are going to look at what challenges exists today with the flux architecture. We are also going to look at a solution that I think is a great contribution to the evolution of flux.

Flux and Flux history

If you have never heard about flux before I will give a very short decription. Component -> Action Dispatcher -> Store -> Component. It is a one way flow of state where you components do not change the state of your application directly, but goes through a dispatcher to do so. There are several implementations of this architecture and initially we had the offical dispatcher and store from Facebook. So why did developers start to implement their own versions of flux? I believe there are five main reasons for this: verbosity , async operations, handle the same action in multiple stores, sharing state between stores and immutability.

Verbosity

Developers in the JavaScript world have become accustomed to very expressive and easy to use API's. The Facebook dispatcher and store does not really provide much of an API at all, there is a lot of manual checking and defining to do very simple things. It also becomes quite repetitive.

Async operations

When you test your application it is better to do so if you can change the state of your store synchronously. The reason is that synchronous tests are easier to write and you will also get less dependencies to the store itself. What you want to test is how your components render in the different states of the store. If the API changing the state of the store is synchrounous it will be easier to prepare the state of the store before running a test.

Handle the same action in multiple stores

Facebook suggests a waitFor method that can reference the other stores in your application. If an action is dispatched and multiple stores react to that action, the waitFor method allows you to control which stores handles the action first. Even though you clearly see that something else should happen first, you have no idea exactly what happens. It is much like calling super in a constructor. You have to change file and compose how it works in your head.

Sharing state between stores

You probably do not know exactly what state is going to live in the application beforehand, and even less how that state will flow through the application. And even if you are a wiz at planning, you can not look into the future. The state and flow will change. The thing with traditional flux is that the state is split into multiple stores that other stores are interested in. That is initially not a problem, but it quickly becomes a problem if two stores depend on each other. You get circular dependencies.

Immutability

Immutability can be a difficult concept to grasp, but a more important question to answer is; "why would you want to use it"? There are two sides to this story. Immutability is a general concept that makes sure that whenever an object or array is changed, the object/array itself will change its reference. This makes sure that one part of your code can not mutate the state of other parts of your code. To my understading this is something that gives value on very large projects, with huge codebases and a large team. Much like type checking. But the other side of this story is related to React JS and its rendering. You can use immtability to allow for shallow comparison when verifying if a render should occur in a component. The React.addons.update method, or the immutability-js lib, will help you do this. The problem is that it is both difficult to use and understand why you need to use it.

The solutions

There are many alternatives out there. Just have a look at the React JS wiki. What I think all of them have in common is that they are more expressive in regards of syntax, they are not as verbose as the Facebook dispatcher and store. Some of them handle async operations as a layer in front of the dispatcher, called action creators. To handle the same action in multiple stores some libraries have different implementations of waitFor, and some uses mixins to merge stores into one single store. There are not many that handle the circular depdendency issue, but mixins is one solution that will handle that too. Some of them has immutability built in either by update methods to change state, or pure cloning.

So now we have some background on what challenges flux has and what still needs to be evolved until we reach a widely accepted implementation... if we ever get there, or should for that matter :-) Now we are going to look at one specific implementation that I think solves all these issues very elegantly.

Meet Baobab

Even though I have a very hard time remembering the name of this library it has a very interesting solution to handling state. We have to forget about dispatchers, actions and stores for a moment. A Baobab tree is strictly the state of your application. All of it. Everything exists in one tree. What makes this tree so special is that any changes will trigger an event, but not as you might expect. Let us get into some code and explore how the tree works and then we will see how we can implement a complete flux architecture around it, using React JS and a layer for handling state changes.

Creating a tree

var Baobab = require('baobab');
var stateTree = new Baobab({
  admin: {
    users: []
  },
  home: {
    news: []
  }
});

As you can see the tree is basically one object with nested objects and arrays. It is like a tree with branches. You can traverse this tree using a select method.

var Baobab = require('baobab');
var stateTree = new Baobab({
  admin: {
    users: []
  },
  home: {
    news: []
  }
});

var adminCursor = stateTree.select('admin');
var admin = adminCursor.get(); // { users: [] }

adminCursor? What is that? Well, a cursor is a pointer to some data in your tree, in this case the admin object. To actually extract the value you use the get() method on the cursor. So what is this all about? The brilliant thing that cursors give you is the ability to listen for changes, but not only changes to the value the cursor points to. Let me give you an example:

var Baobab = require('baobab');
var stateTree = new Baobab({
  admin: {
    notifications: {
      list: []
    }
  },
  home: {
    feeds: []
  }
});

var adminCursor = stateTree.select('admin');
var notificationsCursor = adminCursor.select('notifications');
var feedsCursor = stateTree.select('home', 'feeds');

adminCursor.on('update', function () {
  console.log('I saw a change'); // I will trigger
});

notificationsCursor.on('update', function () {
  console.log('I saw a change'); // I will trigger
});

feedsCursor.on('update', function () {
  console.log('I saw a change'); // I will not trigger because I am on a different branch
});

notificationsCursor.push('foo');

As you can see, the update event propagates up the tree. This is really powerful as you can narrow down the interest of changes in different parts of your application. Maybe one part of your application is interested in all changes within the admin object, but an other part is only interested in the notifications array.

Combining our state tree with React JS

Now we have been looking at how Baobab works "under the hood". The real power of Baobab though is how it integrates with React JS. Let us first see how we can combine our state tree with a React JS component to both react to changes in the tree and grab data from the tree. After that I will explain why it is a very good thing that we specify what state changes the component is actually interested in, instead of listening to general changes to state.

When connecting your state tree to a component you have two strategies. Let us take a look using the state tree defined above.

Connecting a single cursor to a component

var stateTree = require('./stateTree.js');
var React = require('react');

var listCursor = stateTree.select('admin', 'notifications', 'list');
var MyComponent = React.createClass({
  mixins: [listCursor.mixin],
  renderNotification: function (notification) {
    return (
      <li>{notification.title}</li>
    );
  },
  render: function () {
    return (
      <ul>
        {this.state.cursor.map(this.renderNofication)}
      </ul>
    );
  }
});

Connecting multiple cursors to a component

var stateTree = require('./stateTree.js');
var React = require('react');

var MyComponent = React.createClass({
  mixins: [stateTree.mixin],
  cursors: {
    notifications: ['admin', 'notifications', 'list'],
    feeds: ['home', 'feeds']
  },
  renderFeed: function (feed) {
    return (
      <li>{feed.title}</li>
    );
  },
  render: function () {
    return (
      <div>
        <div>You have {this.state.cursors.notifications.length} notifiations</div>
        <ul>
          {this.state.cursors.feeds.map(this.renderFeed)}
        </ul>
      </div>
    );
  }
});

So here we see how simple it is to wire up state to a component. You bring in a mixin of the whole tree if you want to create multiple cursors, but you can also bring in a specific cursor to just grab that state. When changes are made to these cursors the component will automatically render again and the new values are available on the state object of the component, via a "cursors" or "cursor" property.

So how do you change the state in a Baobab tree?

A state change layer

As we know from flux a component should not update the state of the application directly, there should be a different layer handling that. I am referring to actions and the dispatcher.

When using action creators with flux the state changes would happen when a component (or something else) triggers an action that in turn triggers dispatches to the store. The action creator method itself runs logic, typically async stuff, and possibly does multiple dispatches to the store.

Architecture using traditional flux
  
            |-------------------------|
        |-- | Action (Action Creator) | <--|          
        |   |-------------------------|    |
        v                                  |
  |------------|     |--------|     |------------|
  | Dispatcher | --> | Stores | --> | Components |
  |------------|     |--------|     |------------|

With Baobab you get a bit more freedom. With a Baobab tree you already have an API for changing the state and trigger an update (change) event. In other words, you do not need to create methods to change the state like you would in a store. Also considering that you only have one state tree there is never a dispatch to a sequence of handlers. What I mean by that is that in Facebook flux you can have multiple stores that reacts to the same action dispatch. A waitFor method allows you to let other handlers run before the current one. This is not necessary with a Baobab tree. Also by having one state tree you prevent circular dependencies and you will always have one method describing the intent of a specific action. In my opionion this gives you a better overview of what happens when an action is triggered.

So to compare this with an architecture using Baobab it will look more like this:

Architecture using Baobab
  
            |------------|
        |-> | State tree | --|           
        |   |------------|   |
        |                    v
  |---------|         |------------|
  | Actions | <------ | Components |
  |---------|         |------------|

The actions are the business logic of your application. Actions will probably depend on other modules to run business logic, like fetch for http request etc. But you state tree does not depend on anything. Your components will only depend on a single state tree, other components and maybe you have some helpers etc. This gives a very simple overview of how your application works. Lets expand and take another look:

Architecture using Baobab
  
                             |------------|
                         |-> | State tree | --|           
                         |   |------------|   |
                         |                    v
                     |---------|         |------------|
 Q, fetch etc. --->  | Actions | <------ | Components | <-- ClassHelper etc.
                     |---------|         |------------|

As we can see the State tree is left all alone. It lives at the top of your application where actions changes it and components grab those changes from it, when notified. So let us move on to the "Actions" part of this architecture. There really is not much to it. It is just a module you define with methods that has access to the state tree.

var stateTree = require('./stateTree.js');

var actions = {
  addItem: function (item) {
    stateTree.select('items').push(item);
  }
};

module.exports = actions;

So this is a very simple action. Lets ut look at something a bit more complex, but before we do that lets talk about how you would structure the state of your application in a Baobab tree.

Application state

Traditionally I think we web developers has thought of state as a session object and/or entities in a database, and with good reason, that was all the state we had in traditional server side web applications. When more advanced web applications were developed in the client we got some new state we could control, application state. Application state is everything from your list of todos to UI loading state. So with Baobab, all state related to your application goes into the tree.

So how would you go about structuring this state in the tree? There are many ways to do this, and I can not tell you what is the best way to do it. That depends on the project and what you feel comfortable with. But I will give you some alternatives, as food for thought.

var Baobab = require('baobab');
var stateTree = new Baobab({
  models: {
    notifications: [],
    contacts: []
  },
  views: {
    createContact: {
      isLoading: false
    }
  }
});
module.exports = stateTree;

In this setup we have chosen to split by models and views, which are our traditional state concepts in modern web applications. Anything related to entities are put in the models domain space and everything related to UI state is put into views. Models might not come to much of a surprise, but maybe views does. The reason you would want to define views is that you probably have many components building up one view. By putting this state into your state tree you ensure that any changes to those components, or the addition of new components, all relate to the tree. Not each other.

var Baobab = require('baobab');
var stateTree = new Baobab({
  admin: {
    notifications: []
  },
  home: {
    posts: []
  }
});

In this setup we have chosen to split up the tree by sections of your application. I would suggest this kind of setup for larger applications. This will make it easy to let components that are part of specific sections of your application to listen for state changes they relate to, but again would allow for "cross section state". Maybe the home section would want to display the number of notifications. That would not be a problem.

var Baobab = require('baobab');
var stateTree = new Baobab({
  notifications: []
});

module.exports = stateTree;

A third setup could be just adding state directly to the tree. This would be for smaller applications.

My message here is that there is no specific structure for building state. State structures differs as much as applications differs. But now you have a concept where you do not have to divide your state artifically to avoid circular dependencies, you do not have to use a waitFor method that makes your code harder to reason about and you can easily change the structure of your state as your application grows. That is great!

A bit more complex example

A process I have become a fan of is boxing in your layout to define components. This is introduced in Thinking in React. What I noticed is that you can use this concept to also define your Baobab state tree. Let us use the "Thinking React" example to define the Baobab state tree, but let us also get that data from the server:

stateTree.js

var Baobab = require('baobab');
var stateTree = new Baobab({
  query: '',
  onlyProductsInStock: false,
  products: []
});

module.exports = stateTree;

Our actions could look something like this:

actions.js

var stateTree = require('./stateTree');
var ajax = require('ajax');
module.exports = {
  showOnlyProductsInStock: function () {
    stateTree.set('onlyProductsInStock', true);
  },
  showAllProducts: function () {
    stateTree.set('onlyProductsInStock', false);
  },
  searchProducts: function (query) {
    stateTree.set('query', query);
    ajax.get('/products', query)
      .done(function (products) {
        stateTree.set('products', products);
      });
  }
};

Thats it! We have pretty much created a "backend" for our components. An API our components can use to ask for changes, much like you would communicate with a backend API. The changes are reflected in the components by the authority of the state tree. What is kind of cool about this is that you can very easily store this state in local storage so the user will get right back to where they were coming back:

main.js

var stateTree = require('./stateTree');
window.addEventListener("beforeunload", function(e){
   localStorage.state = JSON.stringify(stateTree);
}, false);

Optimizing

A very nice feature with Baobab is that it lets you very easily control rendering. By adding two options to your Baobab instance React JS will only render components when it actually needs to.

var Baobab = require('baobab');
var ReactAddons = require('react/addons');

var stateTree = new Baobab({
  notifications: []
}, {
  mixins: [ReactAddons.PureRenderMixin],
  shiftReferences: true
});

module.exports = stateTree;

These options does two important things.

The PureRenderMixin from React addons will ensure that the component will only render if the props passed to it or its own state has actually changed
When Baobab changes a value in the tree it will propagate up and give all objects and arrays new references. The Baobab tree is immutable in that sense. That way a shallow check by PureRenderMixin is enough to verify that a render is needed. The nice thing is... you do not have to think about it!

So why does this matter? Lets have a look at how React JS renders and you will see what these two options fix.

1. React JS cascading renders

One important detail about React JS that is often overlooked is how setState on a component affects the nested components. When you use setState the nested components will run a check to verify if they need to update the DOM. That means if a change event is being listened to on your application root component and a change event is triggered from the store, all your components will do a render and a diff to produce any needed DOM operations. Lets visualize this:

[Cascading render]

               |---|
               | X | - Root component renders
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          | X |    | X | - Nested components also renders
          |---|    |---|

But if a nested component does a setState it will not affect parent components.

[Cascading render]

               |---|
               |   | - Root component does not render
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          |   |    | X | - Nested component renders
          |---|    |---|

This actually means that you could get away with only pointing to the state tree on the root component and then grab state directly from it in all other components, without attaching cursors. The drawback is that the whole application would render on all state changes.

2. Repeated rendering

What is even more important to understand about setState is that using a general change event will not only cause cascaded rendering but will also cause repeated rendering in components. Let me explain:

[Repeated rendering]

               |---|
               |   | - Root component listens to change
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          |   |    |   | - Nested components listens to change
          |---|    |---|

When a change event now occurs the root component wil first trigger a render:

[Repeated rendering]

               |---|
               | X | - Root component reacts to change event and rerenders
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          | X |    | X | - Nested components render
          |---|    |---|

And after that, the nested components will actually rerender themselves again:

[Repeated rendering]

               |---|
               |   |
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          | X |    | X | - Nested components react to change event and rerenders
          |---|    |---|

Now if there were deeper nested components this would cause the same effect, but with even more repeated rendering due to each nested level causes an extra rerender.

Thankfully you do not have to worry about this at all when using Baobab.

Isomorphic app

There is a lot of talk about isomorphic apps. An isomorphic app is able to render your application on the server and pass the complete HTML of it on the first request. Then React JS takes over on the client side. The examples shown this far is optimized for rendering on a "non-isomorphic" app. If you do want to explore this concept you would have to do something like this:

client side

var React = require('react');
var stateTree = require('./stateTree.js');
var AppComponent = require('./AppComponent.js');
var renderApp = function () {
  React.render(<AppComponent state={stateTree.get()}/>, document.body);
};
stateTree.on('update', renderApp);
renderApp();

module.exports = AppComponent;

server side

var React = require('react');
var defaultState = require('./defaultState');
var AppComponent = require('./AppComponent.js');

var html = React.renderToString(AppComponent({state: defaultState}));
// Pass html as response

This effectively passes a state prop through your top component. The top component then has to pass this further down to the other components. This can be tedious and you loose the optimized rendering. There are developments in React JS, like withContext, which might make this easier to handle. I do not have much experience with this, so please enlighten the readers in the comments below if you do :-)

Summary

As stated in the beginning of this article flux is still evolving. I personally think Baobab has a lot to offer this evolution in regards of all the challenges mentioned. If you have any questions or comments, please fire away in the comments section below. You can read more about Baobab at this repo and take a look at this clip from ReactConf 2015, Making your app fast with high-performance components that also highlights the issue in this article. Thanks for reading!

Think twice about ES6 classes

Thu, 01 Jan 2015 09:21:30 +0000

I got into JavaScript about 5 years ago and I have no to very little experience with other languages. That can sometimes be a bad thing, but it can also be a very good thing. In this article I am going to talk about classes, which is coming to the next version of JavaScript. I am going to talk about why I do not understand developers simulating classes and class inheritance in JavaScript and why I think it is not a very good idea to bring the concept into JavaScript at all.

"When asked what he might do differently if he had to rewrite Java from scratch, James Gosling suggested that he might do away with class inheritance and write a delegation only language." delegation vs inheritance

If you want to know more on this topic please head over to Kyle Simpsons article on http://davidwalsh.name/javascript-objects and Eric Elliotts talk on Fluent 2013 https://www.youtube.com/watch?v=lKCCZTUx0sI. The first part of this article will bring up different concepts related to objects in JavaScript, the second part will show how you can use composition and delegation, instead of class inheritance to build objects with JavaScript.

Creating an object

In any application you would probably like to have more than one instance of an object. You need some kind of construct to create instances of objects that looks and behaves the same. In traditional JavaScript you do that with either a constructor or you can do it with a normal function. With ES6 you get the ability to define a class:

// With a constructor
function MyObjectA () {};
new MyObjectA(); // {}

// With a function
function MyObjectB () {
  return {};
};
MyObjectB(); // {}

// ES6 class
class MyObjectC {}
new MyObjectC(); // {}

The constructor

So why do we use a constructor? As stated above it is a construct to instantiate multiple instances of objects that looks and behaves the same. An object instantiated by a constructor, a normal function or ES6 class does not differ in that sense. Where it differs though is a property on the constructor function called "prototype". Now, you have probably heard about "prototypal inheritance" and we will take a look into that now. Let us compare again by adding a method to the object:

// With a constructor
function MyObjectA () {
  this.myMethod = function () {};
};
new MyObjectA(); // {myMethod: function () {}}

// With a function
function MyObjectB () {
  return {
    myMethod: function () {}
  };
};
MyObjectB(); // {myMethod: function () {}}

// With ES6 class
class MyObjectC {
  constructor () {
    this.myMethod = function () {};
  }
}
new MyObjectC(); // {myMethod: function () {}}

Now, these instantiators will create a new myMethod method for each object instance. Unless you have to create hundreds of thousands of objects, adding a new version of the method for each instance will not get you into performance issues. I believe you should stick with describing your object as it will look like when instantiated, not create less comprehensable code for performance sake. That said, there are situations where you want to use delegation.

When I say delegation I specifically mean that we link one object to an other. The object linked to the object you are instantiating will be able to act on behalf of it. You do this by adding an object on the prototype property of a constructor function. When using the normal function pattern we use the Object.create method. With ES6 you just add methods. It has the same effect:

// With a constructor
function MyObjectA () {}
MyObjectA.prototype = {
  myMethod: function () {}
};

var obj = new MyObjectA(); // {}
obj.myMethod(); // Prototype object acts on behalf of obj

// With a function
var proto = {
  myMethod: function () {}
};
function MyObjectB () {
  return Object.create(proto);
}

var obj = MyObjectB(); // {}
obj.myMethod(); // proto object acts on behalf of obj

// ES6 class
class MyObjectC {
  myMethod () {
  
  }
}
var obj = new MyObjectC(); // {}
obj.myMethod(); // Prototype object acts on behalf of obj

The term prototypal inheritance is a bit misleading. Inheritance suggests that it is the instantiated object the somehow receives the look and behavior of parent objects on the prototype chain, but actually it is the other way around. A prototype object acts as a delegate, an object that can act on behalf of the instantiated object.

Try to think of this like event delegation in the DOM. Lets say you have a list with items. Instead of registering a click on each item in the list, you register the click on the list itself. When a click occurs on an item it will try to trigger click listeners, but there are none, so the click moves up to the list element. Now it tries to trigger click listeners on the list element and there it is.

DOM delegation

|----------------|
| |------------| |
| |   Item 1   | | 1. Clicking on item
| |------------| |
|                | 2. The list acts upon the click on behalf of the item (delegation)
| |------------| |
| |   Item 2   | |  
| |------------| |
|----------------|

Now think about an instance of our MyObjectA here. When you run new MyObjectA().myMethod() it will try to find the method on the instance, but it will not find it. Then it checks the object linked to the instance and there it finds it. The linked object will run that function in the context of the object that called the method. There you go, delegation, not inheritance.

var objectA = Object.create(); // Object.create() creates a plain object
objectA // {}

var proto = {doSomething: function () {}};
var objectB = Object.create(proto);
var objectC = Object.create(proto);

objectB // {}
objectC // {}
objectB === objectC // false

// The proto object acts on the method call on behalf of objectB (delegation)
objectB.doSomething();

// The same proto object acts on the method call on behalf of objectC (delegation)
objectC.doSomething();

So this is quite powerful. Lets say we wanted to use the methods from EventEmitter in combination with our own. We could do this:

// With a constructor
function MyObjectA () {
  this.myMethod = function () {};
}
MyObjectA.prototype = EventEmitter.prototype;

// With a function
function MyObjectB () {
  var object = Object.create(EventEmitter.prototype);
  object.myMethod = function () {};
  return object;
}

// ES6 class
class MyObjectC extends EventEmitter {
  constructor () {
    this.myMethod = function () {};
  }
}

Every instance is linked to the EventEmitter.prototype object. It is a delegate, an object acting on the behalf of the instantiated object. At the same time we create a new myMethod method for each instance. We could actually have made everything unique to each instance by doing this:

// With a constructor
function MyObjectA () {
   Object.assign(this, EventEmitter.prototype, {myMethod: function () {}}); 
}

// With a function
function MyObjectB () {
  return Object.assign({}, EventEmitter.prototype, {myMethod: function () {}});
}

// With ES6 class
class MyObjectC {
  constructor () {
    Object.assign(this, EventEmitter.prototype, {myMethod: function () {}});
  }
}

In this case we are not using delegation, because we actually do create new properties on each instance. Though this increases memory usage and takes a performance hit in its instantiation (copying all properties) it is not as bad as you might think. Every function, object and array are copied by reference. So even though each instance will have their own "on" and "off" property, the actual function they reference is the same on all instances. What is very powerful here though is that we are starting to see composition in action. You could keep adding objects as arguments to Object.assign.

So now we have been playing around with the concept of delegation, and pointed out that it is not really inheritance. You should also have a good idea of why we use the constructor and the power of delegation and that we can achieve the same effect with just a simple function.

ES6 classes vs object factory

Lets us now go through the class syntax in ES6 and see how it compares to this simple function that creates objects. I will call the simple function pattern an "Object factory".

Instantiate an object

// ES6 Class
class MyObjectA {}
new MyObjectA(); // {}

// Object factory
function MyObjectB (obj = {}) {
  return obj; // Return passed object or a new object
}
MyObjectB() // {}
MyObjectB({foo: 'bar'}) // {foo: "bar"}

So we already see the advantages of the object factory. First of all we do not have to worry about the "new" keyword. We also see that we can pass an existing object if we want to, or just let it create a clean instance.

Instantiation function (constructor)

// ES6 Class
class MyObjectA {
  constructor () {
    this.list = [];
  }
}
new MyObjectA().list === new MyObjectA().list; // false

// Object factory
function MyObjectB (obj = {}) {
  obj.list = [];
  return obj;
}
MyObjectB().list === MyObjectB().list // false

As you can see in the object factory pattern the function itself is the instantiating function, there is no constructor function that implicitely gets called whenever you use the new keyword in front of the class, calling it as a function.

Privates

A fantastic feature in JavaScript is closures and you can use those to hide implementation details in your objects. In ES6 you would have to do that in the constructor definition:

// Class
class MyObjectA {
  constructor () {
    let myPrivate = 'foo';
    this.getPrivate = function () {
      return myPrivate;
    }
  }
}
new MyObjectA().getPrivate(); // "foo"

// Object factory
function MyObjectB (obj = {}) {
  let myPrivate = 'foo';
  obj.getPrivate = function () {
    return myPrivate;
  };
  return obj;
}
MyObjectB().getPrivate(); // "foo"

Sorry about the bad example, but I hope you see that I am just making a point :-) Hiding details in ES6 classes requires you to move methods accessing privates to the inside of the constructor. If not you would have to wrap the class in its own scope, with an IIFE or a module.

Adding methods

// ES6 Class
class MyObjectA () {
  constructor () {
    this.list = ['foo'];
  }
  getFirstInList () {
    return this.list[0];
  }
}
new MyObjectA().getFirstInList() // "foo"

// Object factory
function MyObjectB (obj = {}) {
  obj.list = ['foo'];
  obj.getFirstInList = function () {
    return this.list[0];
  };
  return obj;
}
MyObjectB().getFirstInList() // "foo"

There is not much difference in syntax, but the methods added in ES6 classes will not be attached to the instance, but a prototype object created "under the hood", causing delegation. That is initially a good thing, but might also surprise you. The object you are describing will not look like this when console logging it in the browser. There is also a hidden feature of the object factory pattern. When using this you actually make methods dynamic. What I mean is that you can change the context of the method when it runs:

function MyObjectB (obj = {}) {
  obj.list = ['foo'];
  obj.getFirstInList = function () {
    return this.list[0];
  };
  return obj;
}
var someObj = {list: ['bar']};
MyObjectB().getFirstInList.call(someObj); // "bar"

Extending a function call with call or apply will set the this of the function to whatever you pass as the first argument, in this case someObj. But we can actually lock the context of the methods using the object factory, making them more predictable:

function MyObjectB (obj = {}) {
  obj.list = ['foo'];
  obj.getFirstInList = function () {
    return obj.list[0];
  };
  return obj;
}
var someObj = {list: ['bar']};
MyObjectB().getFirstInList.call(someObj); // "foo"

Since we point to the actual object being built it is not possible to change the context of which it is run.

Inheritance

So a class in ES6 has the possibility to extend from an other class, but not only a specific "class" definition, but actually any constructor and its prototype. It also takes JavaScript to a new level of abstraction. A function, called super. It can be used inside the constructor function to call the extended constructor, which is bound to the object. You can also use super.someMethod to call methods on the extended class, that are also bound to the object. "It just works that way, accept it" is not something you are used to in JavaScript.

The challenge with thinking inheritance is that you have to compose in your head how an object actually looks like by looking into different classes AND follow the usage of super, it can get very complex. The classes also become completely dependant on each other because you do not compose smaller parts, only build on top of existing functionality. inheritance is evil and must be destroyed.

With an object factory it is not encouraged to think inheritance at all, but composing. Think that you already have an object and you add behavior to it, rather than describing behavior that produces an object. Let us create an example with a Backbone Model.

// Class
class MyModel extends Backbone.Model {
  constructor (options) {
    super(options.attributes);
  }
}

// Object factory
function MyModel (model = {}) {
  model = Object.assign(Object.create(Backbone.Model.prototype), model);
  Backbone.Model.call(model, model.attributes);
  return model;
}

So in this example the ES6 syntax of course wins the prize. What worries me a great deal though is that with such simple, but restricted syntax, you risk loosing some of the best features of JavaScript. So to compensate for the syntax I created a tiny lib that will give you more than enough sugar to see the full benefit of composing and delegation. Syntax should really not be the winning argument anyways, but of course it is important.

Objectory (Object + factory)

So objectory allows you to compose objects while still taking advantage of delegation. Please let me show you with some examples:

Instantiating

var MyObject = objectory(function (obj) {
  obj.foo = 'bar';
  obj.getFoo = function () {
    return obj.foo; // Forced usage of obj
  };
});

MyObject(); // {foo: 'bar', getFoo: function () {...}}
MyObject({name: 'Roger'}); {name: "Roger", foo: "bar", getFoo: function () {...}}

So as you might expect this looks much like a normal constructor, but it has some benefits:

You can pass your own object to extend, instead of the default
You can use forced context on the methods
You do not have to use the "new" keyword or return the object created form the constructor

Composing objects

So lets dive in to the power of objectory and JavaScript. In the example above everything added to "obj" would become instance properties. But lets see what happens when we start to compose.

var DEFAULTS = {
  name: 'no name',
  age: 18
};
var Person = objectory(function (person) {
  person.compose(DEFAULTS);
});

var personA = Person(); // {}
personA.name; // "no name"
personA.age; // 18

var personB = Person({name: 'Roger', age: 30}); // {name: "Roger", age: 30}

As you can see, by composing a normal object with a person object we created a delegate. We link the DEFAULTS object to instantiated person objects.

Composing constructors and their prototypes

Most libraries are based on constructors with prototypes. An example of that would be Backbone.Model or EventEmitter. Let us turn our Person into a Backbone Model.

var Person = objectory(function (person) {
  person.compose(Backbone.Model, {
    name: 'no name',
    age: 18
  });
});

var personA = Person(); // {_events: {...}, attributes: {...}...}
personA.get('name'); // "no name"

In this example the prototype property from "Backbone.Model" (Backbone.Model.prototype) will be linked to the "Person" objects created. When the Person constructor runs it will run the "Backbone.Model" constructor and pass in an object representing attributes of the model.

This example also shows an advantage over Backbones own "extend" method. If any attributes passed was objects or arrays they would all be unique for each instance of Person. That would not be the case and is often confusing with Backbone.

But we can also take advantage of our defaults and do this:

var DEFAULTS = {
  attributes: {
    name: 'no name'
  }
};
var Person = objectory(function (person) {
  person.compose(DEFAULTS);
  person.compose(Backbone.Model, person.attributes);
});

var personA = Person(); // {attributes: {name: "no name"}...}
personA.get('name'); // "no name"

var personB = Person({attributes: {name: 'Roger'}}); // {attributes: {name: "Roger"}...}
personB.get('name'); // "Roger"

In this example the delegate for Person will consist of the "DEFAULTS" object AND the prototype of "Backbone.Model" (Backbone.Model.prototype). When the "Person" constructor runs it will call the "Backbone.Model" constructor and pass in the attributes. Either by delegation from DEFAULTS or any passed attributes.

And now lets take a look at something really awesome. Lets say we wanted to use EventEmitter instead of the default event system in Backbone.

var Person = objectory(function (person) {
  person.compose(Backbone.Model, person.attributes);
  person.compose(EventEmitter);
});

var personA = Person(); // {attributes: {name: "no name"}...}
personA.on('change', function () {}); // works

This of course requires that the API of EventEmitter works the same way as Backbone, but you start to see what is available to you.

Composing other factories

You can of course also compose other factories.

var Person = objectory(function (person) {
  person.age = 18;
});
var Student = objectory(function (student) {
  student.compose(Person);
  student.grade = 'A';
});

var student = Student(); // {grade: "A", age: 18}

In this case Person does not have any compositions, which means there is no delegation either. Lets do something about that:

var DEFAULTS = {
  name: 'no name',
  age: 18
};
var Person = objectory(function (person) {
  person.compose(DEFAULTS);
});
var Student = objectory(function (student) {
  student.compose(Person);
  student.grade = 'A';
});

var student = Student(); // {grade: "A"}
student.name; // "no name"
student.age; // 18

Summary

I hope this gave you enough input to see how it is possible to use vanilla JavaScript with delegation and composition to create a construct more powerful than a class could ever hope to be. I must say I do worry that the ES6 class syntax hides too much implementation details about JavaScript and locks developers in a pattern that has its challenges, but worse it locks them out of using patterns available in JavaScript. Closure for private values and methods and composing. If you liked objectory, go to objectory repo. There are more examples and some perfomance and compatability info.

Thanks for hearing me out!

Creating a workflow with WebPack

Sat, 13 Dec 2014 09:21:30 +0000

Previously I have written a couple of articles about how to set up a workflow with React JS. The solution provided was browserify with gulp. If React JS is not your thing I think you still will get a lot of value out of this article, so please read on.

To build a workflow for React JS with browserify and gulp you need a lot of dependencies and you have to write quite a bit of code. You might appreciate the flexibility gulp brings, but as the requirements of bundling your project grows, your workflow implementation becomes very complex. Nevertheless there are some core concepts you want to bring in to your React JS workflow:

Bundle JavaScript with Common JS (to use components in Node JS)
Sourcemapping
Transform JSX (Coffe, TypeScript etc.)
Split your vendor dependencies and app specific dependencies (fast rebundling)
Bundle stylesheets (css, sass, less etc.)
Handle images and fonts
Make your code production ready

Depending on your project you will of course have less or more requirements, but this is what I believe to be the core of it. What we are going to talk about in this article is how WebPack can help you very easily set up a workflow to handle these core concepts and some pretty amazing stuff on top of that. How does lazy loading your code sound? Or hot swapping React JS components without refreshing the browser? Loading CSS, less and sass with require? What about loading images that automatically inlines below a specific file size? These are some of the things we are going to talk about. If you want to get your hands dirty as you read, please do so, but it is definitely not required. You can also find an example workflow over at this repo.

This article got pretty long, so here you got some shortcuts in case there is something you are more interested in or you are coming back to the article and just want to check something specific:

Creating a basic workflow
Running the workflow
Loaders
Handling vendors
Specifying chunks
Multiple lazy loaded entries
Common chunks
Live reload
Hot swap
CSS
Images and fonts

WebPack

Maybe like me you have also heard about WebPack. What motivated me to write this article was not my discovery of WebPack, but the presentation by Pete Hunt. He goes straight to the point of how WebPack differs and what makes it awesome. This is not the impression you get from looking at the WebPack site or reading its documentation. There is a webpack-howto that gives you a very simple and easy introduction to WebPack and we are actually going to go through the concepts mentioned there, though in more detail. We are also going to take it a bit further. We are going to use webpack-dev-server to introduce hot swapping of not only css, but also your JavaScript. That is pretty cool. Okay, so lets get going.

Installing and setting up webpack and webpack-dev-server

First of all you will need to install both webpack and webpack-dev-server, using NPM. npm install webpack and npm install webpack-dev-server. This will allow you to run the command webpack and webpack-dev-server directly in your terminal. You will be using webpack to deploy your code and webpack-dev-server to run your workflow. We will first look at the workflow.

Creating a basic workflow

Our project structure is:

/project
- /app
-- main.js
-- AppComponent.js
- /build
-- index.html
-- bundle.js (automatically built by webpack)
- webpack.config.js

Just like grunt and gulp you will need a file defining your setup. This file should by default be called webpack.config.js and looks something like this:

module.exports = {
  entry: ['./app/main.js'],
  output: {
    path: './build',
    filename: 'bundle.js'
  }
};

We just point to our application entry file and where we want our bundle to exist when it is produced. We will be looking more into this file later.

I also recommend using a package.json file to configure a script that will run webpack-dev-server with some options. This is how a basic package.json would look like:

{
  "name": "my-project",
  "version": "0.0.0",
  "main": "app/main.js",
  "scripts": {
    "dev": "webpack-dev-server --devtool eval --progress --colors --content-base build"
  },
  "author": "",
  "license": "ISC"
}

Let us just briefly talk about the script we have added here: "webpack-dev-server --devtool eval --progress --colors". When you run npm run dev in your terminal this is what will be executed. It runs webpack-dev-server with some arguments. --devtool eval will add source urls to your code, which will make sure that any errors point to the right file and line. It is really important that you do it like this. Sourcemapping can be achieved with --d, but that is a lot slower. Use that for production if you want sourcemapping. --progress and --colors will just improve the feedback you get in the terminal when running your workflow. --content-base build points to where you have your custom index.html located.

Running the workflow

Let us create an HTML file that our webpack-dev-server can serve when we fire up the workflow. Add an index.html file to the build folder and put something like this in it:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My project</title>
</head>
<body>
  <script src="bundle.js"></script>
</body>
</html>

We of course also have to create our /app/main.js file. It will require an AppComponent so that we have some Common JS in action:

var AppComponent = require('./AppComponent.js');
console.log('Loaded the app component');

And the AppComponent.js file just looks like this for now:

module.exports = {};

When we now run the following in our terminal, npm run dev, and go to localhost:8080 we will of course not see anything, but our console logs out: "Loaded the app component". If you do any changes to the files WebPack will rebundle your app automatically. So making a change and refreshing the browser will show your changes. Okay, so now we have the basics down. Let us install React JS and see how we would implement a transformer from JSX to JavaScript.

WebPack loaders

You will have to install the loaders we need for the workflow, and the first one is jsx-loader. Run npm install jsx-loader --save in your terminal and head into the webpack.config.js file and we will do a small configuration:

module.exports = {
  entry: ['./app/main.js'],
  output: {
    path: './build',
    filename: 'bundle.js'
  },
  module: {
    loaders: [
      { test: /\.js$/, loader: 'jsx-loader' }
    ]
  }
};

What we are basically doing here is telling WebPack that whenever we try to require something that ends with .js it should run the contents of that file through the jsx-loader. Thats it! No need for the JSX comment at top of file or the jsx extension. If you prefer creating .jsx files you just change to /.jsx$/. Now lets install React JS and create our first component, npm install react. And in our AppComponent.js file we insert:

var React = require('react');
module.exports = React.createClass({
  render: function () {
    return (
      <h1>Hello world!</h1>
    );
  }
});

We also want to render this component to the page, so in our main.js file we insert:

var React = require('react');
var AppComponent = require('./AppComponent.js');
React.render(<AppComponent/>, document.body);

Since we changed the configuration we need to stop the webpack-dev-server and start it again with npm run dev. When you refresh the browser, you see "Hello world!" on the screen. But we have met an issue here. When we do a change to a file it takes up to 300 ms to rebundle our application, and that with only two application files. In my book that is way too slow for a workflow.

Handling vendors

When you create a bundling process in your workflow you want it to be as fast as possible. In Browserify you would solve this by creating two different bundles, one for vendors and one for your application. The vendors bundle is only bundled once and your application bundle is being watched for changes and rebundled when that occurs. This strategy does not work with WebPack though, because WebPack can not have two completely separate bundles and allow one of them to require from the other. That does not mean there is no solution. It took me some time to figure this one out, but the solution is quite simple.

We are going to change things around a bit. Instead of depending on npm for our browser vendors, we are going to use bower. So go ahead and install bower, npm install bower -g and then React JS, bower install react --save. Now we have react installed in a bower_components folder instead. To add this file to your project, create the following configuration:

// For conveniance we create variable that holds the directory to bower_components
var bower_dir = __dirname + '/bower_components';

module.exports = {
  entry: ['./app/main.js'],
  
  // The resolve.alias object takes require expressions 
  // (require('react')) as keys and filepath to actual
  // module as values
  resolve: {
    alias: {
      'react': bower_dir + '/react/react.min.js'
    }
  },
  output: {
    path: './build',
    filename: 'bundle.js'
  },
  module: {
  
    // There is no reason for WebPack to parse this file
    noParse: [bower_dir + '/react/react.min.js'],
    loaders: [
      { test: /\.js$/, loader: 'jsx-loader' }
    ]
  }
};

So what we did here was bascially tell WebPack when require('react') is resolved in the code, it will use the react.min.js file located in bower_components. We also made sure that WebPack does not parse the file, because it is not necessary. You will actually get a warning if not using noParse. The reason is that WebPack more effectively compress a vendor by source, then a preminified file. We are talking about a few kilobytes, so it is up to you what is more important. Fast rebundling or an absolute minimum file size. The rebundle speed has now dropped from 250-300 ms to 50-100 ms. That is a huge difference and when working with UI it will be the difference of "instant browser reload" and "waiting for reload".

A small pro tip here is to create a method to add vendors. This makes it very easy to add, change and remove vendors:

// For conveniance we create variable that holds the directory to bower_components
var bower_dir = __dirname + '/bower_components';

var config = {
  addVendor: function (name, path) {
    this.resolve.alias[name] = path;
    this.module.noParse.push(new RegExp(path));
  },
  entry: ['./app/main.js'],
  resolve: { alias: {} },
  output: {
    path: './build',
    filename: 'bundle.js'
  },
  module: {
    noParse: [],
    loaders: [
      { test: /\.js$/, loader: 'jsx-loader' }
    ]
  }
};

config.addVendor('react', bower_dir + '/react/react.min.js');

module.exports = config;

This will also make it easy for you to use for example bootstrap:

var bower_dir = __dirname + '/bower_components';

var config = {
  addVendor: function (name, path) {
    this.resolve.alias[name] = path;
    this.module.noParse.push(new RegExp(path));
  },
  entry: ['./app/main.js'],
  resolve: { alias: {} },
  output: {
    path: './build',
    filename: 'bundle.js'
  },
  module: {
    noParse: [],
    loaders: [
      { test: /\.js$/, loader: 'jsx-loader' }
    ]
  }
};

config.addVendor('bootstrap', bower_dir + '/bootstrap/bootstrap.min.js');
config.addVendor('bootstrap.css', bower_dir + '/bootstrap/bootstrap.min.css')

module.exports = config;

So in your main.js file you can just require these two deps:

require('bootstrap');
require('bootstrap.css');

var React = require('react');
var AppComponent = require('./AppComponent.js');
React.render(<AppComponent/>, document.body);

Specifying chunks

Currently we have one chunk in our WebPack bundle that includes our application and react. The chunk is loaded with the javascript file bundle.js. Larger applications will probably need to split the bundle into more chunks, which means more files. WebPack has a fantastic feature we are going to look at shortly, but for now, let us put all our vendors into a specific vendors chunk.

// Add WebPack to use the included CommonsChunkPlugin
var webpack = require('webpack');
var bower_dir = __dirname + '/bower_components';

var config = {
   addVendor: function (name, path) {
    this.resolve.alias[name] = path;
    this.module.noParse.push(new RegExp('^' + name + '$'));
  },
  
  // We split the entry into two specific chunks. Our app and vendors. Vendors
  // specify that react should be part of that chunk
  entry: {
    app: ['./app/main.js'],
    vendors: ['react']
  },
  resolve: { alias: {} },
  
  // We add a plugin called CommonsChunkPlugin that will take the vendors chunk
  // and create a vendors.js file. As you can see the first argument matches the key
  // of the entry, "vendors"
  plugins: [
    new webpack.optimize.CommonsChunkPlugin('vendors', 'vendors.js')
  ],
  output: {
    path: './build',
    filename: 'bundle.js'
  },
  module: {
    noParse: [],
    loaders: [
      { test: /\.js$/, loader: 'jsx-loader' }
    ]
  }
};

config.addVendor('react', bower_dir + '/react/react.min.js');

module.exports = config;

Now we have to add the new vendors.js file to our html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My project</title>
</head>
<body>
  <script src="vendors.js"></script>
  <script src="bundle.js"></script>
</body>
</html>

Restart the workflow and everything works as expected. So why would you want to do this? It is very unlikely that your vendors will change, but you will probably do bug fixes etc. on your application. So when a user visits the application the first time both vendors.js and bundle.js will be cached. If bundle.js is updated due to a bug fix, vendors.js will still be cached and only bundle.js will be downloaded again.

Multiple lazy loaded entries

Okay, lets dive into one of the really cool parts of WebPack. Lets say you are building a single page application that has a home-page and an admin-page. When users arrive at the home-page you do not want to download all the JavaScript and CSS of the admin-page. That is very easy to achieve. Let me show you with a minimal configuration:

module.exports = {
  entry: ['./app/main.js'],
  output: {
    path: './build',
    filename: 'bundle.js'
  }
};

Our main.js file could look something like this:

var React = require('react');

// We create a function that will lazy load modules based on the current hash
var resolveRoute = function () {
  
  // If no hash or hash is '#' we lazy load the Home component
  if (!location.hash || location.hash.length === 1) {
    require.ensure([], function () {
      var Home = require('./Home.js');
      React.render(Home(), document.getElementById('app'));
    });
    
  // Or if route is #admin we lazy load that
  } else if (location.hash === '#admin') {
    require.ensure([], function () {
      var Admin = require('./Admin.js');
      React.render(Admin(), document.getElementById('app'));
    });
  }

};

// Resolve route on hash change
window.onhashchange = resolveRoute;

// Resolve current route
resolveRoute();

The index.html file looks like:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My project</title>
</head>
<body>
  <div>
    <a href="#">Home</a>
    <a href="#admin">Admin</a>
  </div>
  <div id="app"></div>
  <script src="bundle.js"></script>
</body>
</html>

If you follow along on the network tab of the web console you will see network requests fire when clicking the hyperlinks. So now we have optimized our project by not downloading admin specific code if you only visit the home page. If you would go to admin and then back to home it would not trigger a new download, as the chunk is already downloaded. WebPack by default loads the chunks from the root url ('/'), but you can define the public path in your config where the bundles should be loaded.

module.exports = {
  entry: ['./app/main.js'],
  output: {
    path: './build',
    filename: 'bundle.js',
    publicPath: '/public/'
  }
};

In this configuration React JS was included in the bundle.js file, but you could have created a specific vendors chunk like we did earlier. It all depends on how you want to load the files.

Optimizing with a common chunk

So what if both our Home.js file and our Admin.js required a third file, Shared.js. That would actually result in the contents of Shared.js to appear in both Home.js and Admin.js, which is definitely not what we want. We want WebPack to put modules used by multiple entry points into a common chunk. So let us do that:

var webpack = require('webpack');
module.exports = {
  entry: ['./app/main.js'],
  output: {
    path: './build',
    filename: 'bundle.js'
  },
  plugins: [new webpack.optimize.CommonsChunkPlugin('main', null, false)]
};

We create a CommonsChunkPlugin and pass three arguments. The first argument refers to what entry point we want to put the shared code. The default entry point name is "main", which points to ['./app/main.js']. The second argument would be the name of the file, that holds the shared code, but since we already have an output for our main entry point (bundle.js) we leave it at null. The third argument tells webpack to look for common modules in our lazely required modules. There is actually a fourth argument here too which is a number. The number states how many of these lazy modules that needs to share a module before it is put into our main bundle.

An important note here is that the modules (main.js, Home.js or Admin.js) themselves does not have to require the common module, any dependency within a dependency will count. An example of this would be if Home.js required a module named InnerHome.js and InnerHome.js required our Shared.js module. The Shared.js module would still be included in main bundle.

Live reload

Live reload is a common thing in a workflow, but we are going to take it a step further with WebPack. But lets first setup a normal live reload. webpack-dev-server supports this out of the box, all we have to do is put it in our config, fire it up in the right mode and add another script tag. Let us continue on the multiple entry point example:

var webpack = require('webpack');
module.exports = {

  // We add webpack/hot/dev-server to our main entry point
  entry: {
    app: ['webpack/hot/dev-server', './app/main.js'],
    Home: ['./app/Home.js'],
    Admin: ['./app/Admin.js']
  },
  output: {
    path: './build',
    filename: 'bundle.js'
  },
  plugins: [new webpack.optimize.CommonsChunkPlugin('common.js', 2)]
};

We also need to fire up the server in the "hot" mode simply by adding the "--hot" parameter in our package.json file:

{
  "name": "my-project",
  "version": "0.0.0",
  "main": "app/main.js",
  "scripts": {
    "dev": "webpack-dev-server --devtool eval --hot --progress --colors"
  },
  "author": "",
  "license": "ISC"
}

And finally we add a script tag to the index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My project</title>
</head>
<body>
  <div>
    <a href="#">Home</a>
    <a href="#admin">Admin</a>
  </div>
  <div id="app"></div>
  <script src="http://localhost:8080/webpack-dev-server.js"></script>
  <script src="common.js"></script>
  <script src="bundle.js"></script>
</body>
</html>

Fire up the server again with npm run dev and whenever you do a file change the browser will refresh. Now, you could actually omit this script insertion in the index.html file and go to localhost:8080/webpack-dev-server instead. At the top of the browser you will see a rebundle status and your application is put into an iframe. Personally I do not like this as it changes the environment of the application (iframe), but also visually breaks your app with the bundle indication at the top. But is very cool indeed :-)

Lets do the hot swap!

I will not go into detail about the general hot swapping in WebPack, but I will show you something quite awesome with React JS. Let us use the current example and update the main.js file:

var React = require('react');

var resolveRoute = function () {
  
  if (!location.hash || location.hash.length === 1) {
    require.ensure([], function () {
      var Home = require('./Home.js');
      React.render(Home(), document.getElementById('app'));
    });
    
  } else if (location.hash === '#admin') {
    require.ensure([], function () {
      var Admin = require('./Admin.js');
      React.render(Admin(), document.getElementById('app'));
    });
  }

};

window.onhashchange = resolveRoute;
resolveRoute();

// If hot swapping can be done, do it by resolving the current route
// and render the application again
if (module.hot) {
  module.hot.accept(resolveRoute);
}

So as stated in the comment whenever we now do a change to a component the application will actually rerender itself without refreshing the page. There are lots of possibilities with this hot swapping and you have to create your own strategy for it. This is an example of using routing and rerendering with React JS whenever any module has changed.

Loading CSS

So another very cool thing about WebPack is how you can require CSS files directly in your javascript. To allow for this we simply need to install a style-loader and a css-loader, npm install style-loader --save and npm install css-loader --save. We insert the loaders into our config:

var bower_dir = __dirname + '/bower_components';

module.exports = {
    entry: {
    app: ['./app/main.js']
  },
  output: {
    path: './build',
    filename: 'bundle.js'
  },
  module: {
    loaders: [
    
      // Adding a loader for css. To do this with less you download the 
      // less-loader and add it to the end of the load string here, and 
      // of course test for less files, not css
      { test: /\.css$/, loader: 'style-loader!css-loader' }
    ]
  }
};

Out of the box any changes to the css/less will update without refreshing the page. But the really cool thing is something that happens "under the hood". All url() and @import statements will be handled as a require expression. So how does that benefit us? Lets look at images and fonts.

Images and fonts

A typical css file that uses fonts and images. Now, webfonts is a science in itself and heavily depends on your target browsers. In font loading examples we normally see 4 different formats added. woff, ttf, svg and eot. But that is hard to optimize, because only one of those formats will actually be used. Converting the font files to inline base64 string would cause all 4 to be included, increasing the file size unnecessarily.

Looking at caniuse.com we see that modern browsers support woff and svg. So depending on your project I would suggest sticking to only one of those two formats. Doing so will let us optimize it. Let us look at the code so that you see what I mean:

@font-face {
  font-family: 'myFont';
  font-style: normal;
  src: url(./myFont.woff) format('woff');
}

body {
  font-family: 'myFont',
  background-image: url(./bg.png);
}

What WebPack does in this case is actually resolving the url paths and runs them through the matching loaders. Let us download the url loader, npm install url-loader --save, and change the config:

var bower_dir = __dirname + '/bower_components';

module.exports = {
  entry: {
    app: ['./app/main.js']
  },
  output: {
    path: './build',
    filename: 'bundle.js'
  },
  module: {
    loaders: [
      { test: /\.css$/, loader: 'style-loader!css-loader' },
      
      // Any png-image or woff-font below or equal to 100K will be converted 
      // to inline base64 instead
      { test: /\.(png|woff)$/, loader: 'url-loader?limit=100000' }
    ]
  }
};

The result of the file will be something like this, shortening the base64 string:

@font-face {
  font-family: 'myFont';
  font-style: normal;
  src: url(data:application/font-woff;base64...) format('woff');
}

body {
  font-family: 'myFont',
  background-image: url(data:image/png;base64...);
}

So now you see why multiple fonts would be a bad idea as you would inline content that would never be used. No matter, it is important to be careful with inlining as it will take longer to download the CSS and if changes to the CSS is made it will need to bring down also your inlined images and fonts, which would not be necessary if they were external files.

Deploying your application

To produce a production ready application we have to add a new script to our package.json file:

{
  "name": "my-project",
  "version": "0.0.0",
  "main": "app/main.js",
  "scripts": {
    "dev": "webpack-dev-server --devtool eval --progress --colors",
    "deploy": "NODE_ENV=production webpack -p"
  },
  "author": "",
  "license": "ISC"
}

This script runs node in production mode and runs the production packaging of WebPack. It will uglify, minify and so on. To specify where to put the result we have to update the config:

var bower_dir = __dirname + '/bower_components';

var config = {
  addVendor: function (name, path) {
    this.resolve.alias[name] = path;
    this.module.noParse.push(new RegExp('^' + name + '$'));
  },
  entry: ['./app/main.js'],
  resolve: { alias: {} },
  output: {
  
    // If in production mode we put the files into the dist folder instead
    path: process.env.NODE_ENV === 'production' ? './dist' : './build',
    filename: 'bundle.js'
  },
  module: {
    noParse: [],
    loaders: [
      { test: /\.js$/, loader: 'jsx-loader' }
    ]
  }
};

config.addVendor('react', bower_dir + '/react/react.min.js');

module.exports = config;

And thats it. Your application is ready!

Summary

WebPack is just an awesome tool. It takes application bundling to a whole new level. It is really too bad that documentation is lacking. Hopefully this article gave you some insight into what makes WebPack great. Have a look at this simple example that lets you enjoy all the functionality mentioned in this article. Also take a look at this webpack react cookbook @bebraw and I am working on: webpack-react-cookbook.

An alternative render strategy with flux and React JS

Thu, 04 Dec 2014 09:21:30 +0000

So, this new awesome FLUX architecture is starting to get some solid ground. There are several implementations of it, amongst those Yahoo Dispatchrı, Fluxxor, McFly and jFlux, which I have personally been working on. The core concept of FLUX is stores that will emit a change whenever any of the state held within the store changes. Any components listening to changes to these stores will then grab state from the stores and rerender. In this article we are going to take a look at what actually happens in React JS when a store triggers this change event. Not all FLUX implementations use React JS, but they would also benefit from the concepts we go through in this article. We are going to use flux-react in the examples as it has an API to handle this alternative strategy we are going to talk about.

The change event

So reading through documentation about the FLUX architecture you will surely meet the "change event". Basically whenever a store has done a change to some state it will emit this one type of event, change. By having one type of event your application will of course be more managable in terms of keeping all your components in sync with the stores when a state change occurs, but it also has a cost. Lets look at an example with a flux-react store:

var store = flux.createStore({
  todos: [],
  addTodo: function (todo) {
    this.todos.push(todo);
    this.emit('change');
  },
  removeTodo: function (index) {
    this.todos.splice(index, 1);
    this.emit('change');
  },
  exports: {
    getTodos: function () {
      return this.todos;
    }
  }
});

Any components listening to a change event on this store would use the getTodos method when todos are added and removed to update themselves. That makes sense and it is absolutely nothing wrong with that as it is highly likely that any component interested in adding todos would probably also be interested in their removals. But let us add another state:

var store = flux.createStore({
  todos: [],
  isSaving: false,
  addTodo: function (todo) {
    this.todos.push(todo);
    this.isSaving = true;
    this.emit('change');
    doSomethingAsync().then(function () {
      this.isSaving = false;
      this.emit('change');
    }.bind(this));
  },
  removeTodo: function (index) {
    this.todos.splice(index, 1);
    this.isSaving = true;
    this.emit('change');
    doSomethingAsync().then(function () {
      this.isSaving = false;
      this.emit('change');
    }.bind(this));
  },
  exports: {
    getTodos: function () {
      return this.todos;
    },
    isSaving: function () {
      return this.isSaving;
    }
  }
});

Now we are first triggering a change to notify our components that the store is in isSaving state and that we have a new todo. Later we notify our components again about the store not saving anymore. With this simple example we are starting to see where things are starting to go in the wrong direction. It is not because we are doing an async operation inside a store, but because we use a general 'change' event both for notfifying about our isSaving state and the update to our todos state. Lets visualize what I mean here. Imagine this HTML being components:

<div>
  <AddTodoComponent/>
  <TodosListComponent/>
</div>

We want the input inside <AddTodoComponent/> to disable itself while the store is in isSaving state. It does that by listening to a change event in the store. In addition to this we also want our <TodosListComponent/> to update itself when there are changes to the todos array and we of course listen to the same change event to accomplish that. So what happens is the following:

We grab both isSaving and todos when components are created
We add a new todo causing a "change" event to occur
The <AddTodoComponent/> grabs the new isSaving state and the <TodosListComponent/> grabs the mutated todos state
When the async operation is done we trigger a new change event causing again our two components to grab the same states, though the <TodosListComponent/> did not really have to, since there were no mutation on the todos array

But this is not the only challenge with React JS rendering. Lets look at a couple of other things, but remember this when we look at EventEmitter2.

React JS cascading renders

[Cascading render]

               |---|
               | X | - Root component renders
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          | X |    | X | - Nested components also renders
          |---|    |---|

But if a nested component does a setState it will not affect parent components.

[Cascading render]

               |---|
               |   | - Root component does not render
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          |   |    | X | - Nested component renders
          |---|    |---|

This actually means that if you had one store you could get away with only listening to changes on your root component, triggering a setState and then just grab state from the stores in the nested components. We can create an example of this with our TodoApp:

var TodoApp = React.createClass({
  componentWillMount: function () {
    AppStore.on('change', this.update);
  },
  componentWillUnMount: function () {
    AppStore.off('change', this,update);
  },
  update: function () {
    this.setState({}); // Just trigger a rerender
  },
  render: function () {
    return (
      <div>
        <AddTodoComponent/>
        <TodosListComponent/>
      </div>
    );
  }
});

This component is just listening to a general change event and triggers a rerender. As stated above this will cascade down to the nested components, so if we f.ex. in our AddTodoComponent do this:

var AddTodoComponent = React.createClass({
  render: function () {
    return (
      <form>
        <input type="text" disabled={AppStore.isSaving()}/>
      </form>
    );
  }
});

That is actually all we need to handle the disabled state. There is not need to listen for changes because our root component does this for us. Now I am not saying that this is best practice, I just want to clearify how React JS operates and make you think about how you would handle your rendering in React JS. The hidden message here though is that if you have a change listener to a store on your root component your whole application will rerender on every change from that store.

Repeated rendering

[Repeated rendering]

               |---|
               |   | - Root component listens to change
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          |   |    |   | - Nested components listens to change
          |---|    |---|

When a change event now occurs the root component wil first trigger a render:

[Repeated rendering]

               |---|
               | X | - Root component reacts to change event and rerenders
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          | X |    | X | - Nested components render
          |---|    |---|

And after that, the nested components will actually rerender themselves again:

[Repeated rendering]

               |---|
               |   |
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          | X |    | X | - Nested components react to change event and rerenders
          |---|    |---|

Now if there were deeper nested components this would cause the same effect, but with even more repeated rendering due to each nested level causes an extra rerender.

How to optimize

First I would like to take a minute to look at the shouldComponentUpdate method. This is used to control the behavior of cascading rendering. Lets look at our visualization again:

[Cascading render]

               |---|
               | X | - Root component renders
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          | X |    | X | - Nested components also renders
          |---|    |---|

If our nested components had the shouldComponentUpdate method and it returned false:

var NestedComponent = React.createClass({
  shouldComponentUpdate: function () {
    return false;
  },
  render: function () {
    return (
      <div></div>
    );
  }
});

This would be the result:

[Render cascading]

               |---|
               | X | - Root component renders
               |---|
                 |
            |----|---|
            |        |
          |---|    |---|
          |   |    |   | - Nested components do not render
          |---|    |---|

But it is a pain to add this to all your components though. I do wonder why React JS does not by default prevent rerender when there are no properties passed to the nested component, or even by default do a comparison of the new properties to verify that a rerender actually is needed. It would at least be nice to configure React JS to have that behavior. Anyway, there is probably a very good reason.

EventEmitter2 and flux-react

Now lets have a look at how we can use a different rendering strategy to control all this.

var TodosListComponent = React.createClass({
  componentWillMount: function () {
    AppStore.on('todos.*', this.update);
  },
  componentWillUnmount: function () {
    AppStore.off('todos.*', this.update);
  },
  update: function () {
    this.setState({});
  },
  render: function () {
    return (
      <ul>
        {AppStore.getTodos().map(function (todo) {
          return <li>{todo.title}</li>
        })}
      </ul>
    );
  }
});

As you can see I used an asterix wildcard. This actually means that the store emits the following event on adding a todo, this.emit('todos.add'), and, this.emit('todos.remove'), when removing a todo. Our list will act upon both events. This gives us some freedom because we do not want our input in AddTodoComponent to be disabled when removing a todo, only adding one. Since we have an async operation in our store it will also emit a this.emit('todos.added') after the async operation is finished. Letting us do this:

var AddTodoComponent = React.createClass({
  componentWillMount: function () {
    AppStore.on('todos.add', this.update);
    AppStore.on('todos.added', this.update);
  },
  componentWillUnmount: function () {
    AppStore.off('todos.add', this.update);
    AppStore.off('todos.added', this.update);
  },
  update: function () {
    this.setState({});
  },
  render: function () {
    return (
      <form>
        <input type="text" disabled={AppStore.isSaving()}/>
      </form>
    );
  }
});

So in this example you clearly see what events in the store the component acts upon. The important thing to notice here is that the store holds the actual state, isSaving. We just tell our component to rerender when these two events occur, but it is still the state of the store that defines what will actually be rendered. We would NEVER do something like this:

var AddTodoComponent = React.createClass({
  componentWillMount: function () {
    AppStore.on('todos.add', this.setDisabled);
    AppStore.on('todos.added', this.setEnabled);
  },
  componentWillUnmount: function () {
    AppStore.off('todos.add', this.setDisabled);
    AppStore.off('todos.added', this.setEnabled);
  },
  setDisabled: function () {
    this.setState({disabled: true });
  },
  setEnabled: function () {
    this.setState({disabled: false});
  },
  render: function () {
    return (
      <form>
        <input type="text" disabled={this.state.disabled}/>
      </form>
    );
  }
});

As this would ignore the whole concept of FLUX, keeping the state in your stores to make it easier to scale your application.

Keeping control of the rendering

Although we have given more specific behavior to our components they will still do this cascading rendering which is exactly what we are trying to avoid with this strategy. You could create your own shouldComponentUpdate method for each component, but flux-react has a mixin that does this for you. It also includes an update method to make it easier for you to refresh the component.

var TodosListComponent = React.createClass({
  mixins: [flux.RenderMixin],
  componentWillMount: function () {
    AppStore.on('todos.*', this.updateState);
  },
  componentWillUnmount: function () {
    AppStore.off('todos.*', this.updateState);
  },
  updateState: function () {
    this.setState({
      todos: AppStore.getTodos()
    });
  },
  render: function () {
    return (
      <ul>
        {this.state.map(function (todo) {
          return <li>{todo.title}</li>
        })}
      </ul>
    );
  }
});

The mixin will prevent the component from rerendering if the props or the state has not changed. This means that if the parent component of TodosListComponent would run setState this component would not render, as the todos array is the same.

Summary

So what we have done now is basically going from very loosely defined rerendering of your application to a very strict concept you have full control of. We did this by:

Use EventEmitter2 to specify what state and what changes to that state the component should be affected by
Use RenderMixin to avoid unecessary cascaded rendering and repeated rendering in nested components

Depending on your app you might not want to introduce this control as it does require more thought and effort, but again you will have more control of how your application performs related to rendering. Check out flux-react or use this pattern on your library of choice. You can also check out the cascading and repeating rendering over at this fiddle.

Using FLUX with Angular JS, revisited

Sun, 02 Nov 2014 09:21:30 +0000

After writing my initial article about Angular JS and FLUX I worked on bringing the experiences I had building www.jsfridge.com with jFlux to React JS. This also ended up in an article, My experience building a FLUX application.

So now, with some more experience, I thought it could be a good idea to write an article that brings up the concepts, the challenges with Angular and how you can start using FLUX in Angular JS with flux-angular.

You can have a look at a fiddle over at JSFridge if you want to. It is a small TODO-app with API implementation. Keep reading to explore how we make Angular JS work with FLUX.

Immutability

The first thing we have to fix, that goes totally against one of the coolest things about Angular JS is the two-way-databinding. Two-way-databinding is awesome, but there are situations it does more harm than good. It works very well when you define a state on the $scope of your controller and you use that in a template. It is a controlled environment because a controller and a template is a "one to one" relationship. If you were to use a service to handle the state though, you suddenly get a "one to many" relationship. The reason is that a service can be used by many controllers. If all those controllers are able to just mutate state in the service you risk loosing control. So two-way-databinding is a good thing between your controllers and templates, but not between your controllers and services.

This is where FLUX fits in nicely. It does not go against how Angular JS works, it just fixes the parts that does not work too well, which is state handling with services.

First lets look at the code that creates the state in a service and binds it to a $scope:

angular.module('app', ['flux'])
  .factory('MyStore', function (flux) {
    return flux.store({
      todos: [],
      exports: {
        getTodos: function () {
          return this.todos;
        }
      }
    });
  })
  .controller('MyCtrl', function (MyStore, $scope) {
    MyStore.bindTo($scope, function () {
      $scope.todos = MyStore.getTodos();
    });
  });

So what is happening here? When you bind a flux store to a $scope you have to define its behaviour. So in the callback of the binding process you collect state from the store and attach it to your $scope. What also happens in the background is that the store keeps a reference to the callback. Lets see a simple FLUX in action:

angular.module('app', ['flux'])
  .factory('actions', function (flux) {
    return flux.actions([
      'addTodo' // We add an action
    ]);
  })
  .factory('MyStore', function (flux, actions) {
    return flux.store({
      todos: [],
      actions: [
        actions.addTodo // We listen to the action
      ],
      addTodo: function (title) {
        this.todos.push({title: title}); // We update the state
        this.emitChange(); // We trigger a change
      },
      exports: {
        getTodos: function () {
          return this.todos;
        }
      }
    });
  })
  .controller('MyCtrl', function (MyStore, $scope, actions) {
    MyStore.bindTo($scope, function () {
      $scope.todos = MyStore.getTodos();
    });
    
    // This is a controller specific $scope property. Here it is
    // perfectly fine to have two-way-databinding
    $scope.newTitle = ''; 
    $scope.addTodo = function () {
      actions.addTodo($scope.newTitle);
    };
  });

So when the controller triggers an action and the store adds a new todo to the todos-array it triggers "emitChange". Under the hood the store will go through the bound callbacks and run them. You might think this is alot of extra effort and not very performant. If so, you are partly right. The extra effort is necessary because we do not want our controllers to change stuff in our stores directly, they should do it by using actions. This is really important because this is how you are kept sane, this is how you manage to scale your application and still understand how everything is connected. When it comes to perfomance it is of course extra calculations, but again, the dirty checking by Angular is neither very performant compared to other solutions, but it makes things easier for you. So dirty checking means less code, immutability in stores keeps you sane.

Building stores

So a store in flux has a very strong concept of state handling. Angular does not really have an application wide concept of holding state, it is often locked in controllers. Though you are able to share state in services, that is not their "selling point". What I means is that services are more often used as a link between your backend and controller or they do some heavy logic, not to just hold and share state between your controllers.

So a store definition looks something like this:

angular.module('app', ['flux'])
  .factory('MyStore', function (flux, actions, MyStoreMixin) {
    return flux.store({
      todos: [],
      mixins: [MyStoreMixin]
      actions: [
        actions.addTodo
      ],
      addTodo: function (title) {
        this.todos.push({title: title});
        this.emitChange();
        this.emit('todos:add');
      },
      exports: {
        getTodos: function () {
          return this.todos;
        }
      }
    });
  })

State

You put your state properties directly on the store, like the todos in the example above. These states are available in the handlers. Your export methods are bound to the store, making the state properties available there too.

Mixins

Your stores will hold quite a bit of logic and can grow pretty large. To handle scalability you could create multiple stores, but you have to be careful about that. The reason is that splitting up stores might make them dependant of each other and cause circular dependencies. In my experience it is better to identify a store as part of a section of your application, maybe a specific page or an isolated section of a page. Then you use mixins to divide the logic of the store. Again, looking at todos, you might have the logic for handling actions and update the todos array in the store, then you add a mixin to handle the server communication. Lets see a simple example:

angular.module('app', ['flux'])
  .factory('HTTPMixin', function ($http) {
    return {
      isSaving: false,
      postTodo: function (todo) {
        this.isSaving = true;
        this.emitChange();
        $http.post('/API/todos', todo)
          .success(function (newTodo) {
            todo.id = newTodo.id;
            this.isSaving = false;
            this.emitChange();
          }.bind(this));
      }
    };
  })
  .factory('MyStore', function (flux, actions, HTTPMixin) {
    return flux.store({
      todos: [],
      mixins: [HTTPMixin]
      actions: [
        actions.addTodo
      ],
      addTodo: function (title) {
        var todo = {title: title, checked: false};
        this.todos.push(todo);
        this.postTodo(todo);
        this.emitChange();
      },
      exports: {
        getTodos: function () {
          return this.todos;
        }
      }
    });
  })

So a mixin is just an object that will be merged with your store. All properties will merge as expected. As you can see in this example we have split the concern of the store into handling actions and handling HTTP communication. You can do this however you want, but the advantage is that all mixins has access to all state and all handlers.

Actions

Actions are a very simple concept. It is just an array with names. By looking at your actions service you can see what state changes can be done in your application. It is a good reference. You can call an action from anywhere in your application, it does not really matter. What matters is that an intent to change the state in a store should always start with an action. Even if your store needs to talk to the backend to get its initial state, that should be triggered with an action.

Handlers

When a store is configured with an action that action will map directly to a handler with the same name. So the action: "actions.addTodo" maps directly to a method in the store called: "addTodo". The handler can point to the store with this and mutate the state with whatever logic you need. When they are done mutating the state they can update the bound $scopes and/or broadcast an event to all the active $scopes in the application.

Emit change

The emitChange method will run all the binding callbacks registered to the store and update the bound $scopes. This will also guarantee that a digest loop is run. This means that whenever you run emitChange you can feel certain that the UI will update.

Emitting events

Very often you just need to notify your controllers about something. emitChange makes it easy for you to reflect updates in the UI, but sometimes you just need to notify about a state change. This could be when a model is loaded from the server and you want to trigger a transition. It could be an animation you want to run when a todo is added to the array etc.

Exports

Exports are necessary to let controllers grab state from the stores. The returned value from an export method will always be a copy of the value it returns. This is what ensures that the store is immutable. When using this in an export method it points to the store itself.

Summary

Using FLUX with Angular JS is absolutely possible and it makes it easier to scale your applications. It is different than what you are used to from MVC and you do a tiny bit more "wiring", but that is exactly what makes it easier to work with. You can safely move controllers around, change the UI and implement new controllers without ever worrying about how to grab "that state over there".

A quick summary:

Go bananas with two-way-databinding between your templates and your controllers, "ng-model it up!"
The only way to change states in a store is through an action, even loading initial data from the server. Remember, you can use actions anywhere
Use emitChange to notify about changes in your store and extend with emit when you need to notify controllers about a specific change in a store
emitChange ensures that the digest loop runs

A good mental image is that your state is now flowing on top of your controllers, not "in between". Enjoy building FLUX applications with flux-angular!

React JS and a browserify workflow, PART 2

Thu, 30 Oct 2014 09:21:30 +0000

I wrote an article on working with React JS in a browserify workflow. Well, I got some more experience with it and here is PART2. You can grab this boilerplate at react-app-boilerplate.

There were specifically two things we did not handle very well on the initial workflow:

External dependencies
Testing

External dependencies

When browserify rebundles your project it goes through all the require statements in your application code and figures out what to put into your bundle. Luckily we have watchify that makes sure that it does not rebundle what it already has bundled, BUT browserify still goes through the files and figures out if something should be done. You might not notice this when only React JS is part of the bundle, but as you load up more dependencies it can take several seconds on each save and rebundle of your project.

What we want to do is only touch these external dependencies once and never touch them again during the workflow session. You will not do any changes to React JS or underscore I suppose?

Testing

The initial version of this workflow used Karma for testing. Now Karma is great, but by including browserify as part of the testing it got very slow. By letting our current workflow bundle our tests with external dependencies and watchify we can make this a lot faster! It would also be nice that our tests run automatically when we do changes to our project.

Our Gulpfile.js

// We need a bunch of dependencies, but they all do an important
// part of this workflow
var gulp = require('gulp');
var source = require('vinyl-source-stream');
var browserify = require('browserify');
var watchify = require('watchify');
var reactify = require('reactify'); 
var gulpif = require('gulp-if');
var uglify = require('gulp-uglify');
var streamify = require('gulp-streamify');
var notify = require('gulp-notify');
var concat = require('gulp-concat');
var cssmin = require('gulp-cssmin');
var gutil = require('gulp-util');
var shell = require('gulp-shell');
var glob = require('glob');
var livereload = require('gulp-livereload');
var jasminePhantomJs = require('gulp-jasmine2-phantomjs');

// We create an array of dependencies. These are NPM modules you have
// installed in node_modules. Think: "require('react')" or "require('underscore')"
var dependencies = [
    'react' // react is part of this boilerplate
];

// Now this task both runs your workflow and deploys the code,
// so you will see "options.development" being used to differenciate
// what to do
var browserifyTask = function (options) {

  /* First we define our application bundler. This bundle is the
     files you create in the "app" folder */
    var appBundler = browserify({
        entries: [options.src], // The entry file, normally "main.js"
        transform: [reactify], // Convert JSX style
        debug: options.development, // Sourcemapping
        cache: {}, packageCache: {}, fullPaths: true // Requirement of watchify
    });

    /* We set our dependencies as externals of our app bundler.
     For some reason it does not work to set these in the options above */
  appBundler.external(options.development ? dependencies : []);
  
  /* This is the actual rebundle process of our application bundle. It produces
    a "main.js" file in our "build" folder. */
  var rebundle = function () {
    var start = Date.now();
    console.log('Building APP bundle');
    appBundler.bundle()
      .on('error', gutil.log)
      .pipe(source('main.js'))
      .pipe(gulpif(!options.development, streamify(uglify())))
      .pipe(gulp.dest(options.dest))
      .pipe(gulpif(options.development, livereload())) // It notifies livereload about a change if you use it
      .pipe(notify(function () {
        console.log('APP bundle built in ' + (Date.now() - start) + 'ms');
      }));
  };

  /* When we are developing we want to watch for changes and
    trigger a rebundle */
  if (options.development) {
    appBundler = watchify(appBundler);
    appBundler.on('update', rebundle);
  }
  
  // And trigger the initial bundling
  rebundle();

  if (options.development) {

    // We need to find all our test files to pass to our test bundler
    var testFiles = glob.sync('./specs/**/*-spec.js');
    
    /* This bundle will include all the test files and whatever modules
       they require from the application */
    var testBundler = browserify({
      entries: testFiles,
      debug: true,
      transform: [reactify],
      cache: {}, packageCache: {}, fullPaths: true // Requirement of watchify
    });

    // Again we tell this bundle about our external dependencies
    testBundler.external(dependencies);

    /* Now this is the actual bundle process that ends up in a "specs.js" file
      in our "build" folder */
    var rebundleTests = function () {
      var start = Date.now();
      console.log('Building TEST bundle');
      testBundler.bundle()
        .on('error', gutil.log)
        .pipe(source('specs.js'))
        .pipe(gulp.dest(options.dest))
        .pipe(livereload()) // Every time it rebundles it triggers livereload
        .pipe(notify(function () {
          console.log('TEST bundle built in ' + (Date.now() - start) + 'ms');
        }));
    };
    
    // We watch our test bundle
    testBundler = watchify(testBundler);
    
    // We make sure it rebundles on file change
    testBundler.on('update', rebundleTests);
    
    // Then we create the first bundle
    rebundleTests();

    /* And now we have to create our third bundle, which are our external dependencies,
      or vendors. This is React JS, underscore, jQuery etc. We only do this when developing
      as our deployed code will be one file with all application files and vendors */
    var vendorsBundler = browserify({
      debug: true, // It is nice to have sourcemapping when developing
      require: dependencies
    });
    
    /* We only run the vendor bundler once, as we do not care about changes here,
      as there are none */
    var start = new Date();
    console.log('Building VENDORS bundle');
    vendorsBundler.bundle()
      .on('error', gutil.log)
      .pipe(source('vendors.js'))
      .pipe(gulpif(!options.development, streamify(uglify())))
      .pipe(gulp.dest(options.dest))
      .pipe(notify(function () {
        console.log('VENDORS bundle built in ' + (Date.now() - start) + 'ms');
      }));
    
  }
  
}

// We also have a simple css task here that you can replace with
// SaSS, Less or whatever
var cssTask = function (options) {
    if (options.development) {
      var run = function () {
        gulp.src(options.src)
          .pipe(concat('main.css'))
          .pipe(gulp.dest(options.dest));
      };
      run();
      gulp.watch(options.src, run);
    } else {
      gulp.src(options.src)
        .pipe(concat('main.css'))
        .pipe(cssmin())
        .pipe(gulp.dest(options.dest));   
    }
}

// Starts our development workflow
gulp.task('default', function () {

  browserifyTask({
    development: true,
    src: './app/main.js',
    dest: './build'
  });
  
  cssTask({
    development: true,
    src: './styles/**/*.css',
    dest: './build'
  });

});

// Deploys code to our "dist" folder
gulp.task('deploy', function () {

  browserifyTask({
    development: false,
    src: './app/main.js',
    dest: './dist'
  });
  
  cssTask({
    development: false,
    src: './styles/**/*.css',
    dest: './dist'
  });

});

// Runs the test with phantomJS and produces XML files
// that can be used with f.ex. jenkins
gulp.task('test', function () {
    return gulp.src('./build/testrunner-phantomjs.html').pipe(jasminePhantomJs());
});

Getting in the flow

Run gulp
Start up a webservice in the "build" folder, f.ex. python -m SimpleHTTPServer 3000
Go to "localhost:3000", here you will find your app
Go to "localhost:3000/testrunner.html", here you will find your tests

To make LiveReload work you need to install an extension to Chrome, LiveReload. This puts a small button up in the right corner of your browser. When on you app and/or your tests, hit that button and you will see the little circle in the center will become a black dot. Now these pages will refresh on file changes either in your tests or application files... blazingly fast!

My experiences building a FLUX application

Mon, 27 Oct 2014 09:21:30 +0000

Background

A few months ago I started a project, www.jsfridge.com. In short it is a service that merges video education and fiddle services together in a new way to learn frontend web development. JSFridge has state up the wazoo. Actually it has exactly 35 application states, amongst those: "isPlaying", "isRecording", "isEditing", "currentScene", "duration", "isAudioReady" etc. In addition there is of course lots of view state. How can I say that my application has exactly 35 application states? Well, that is actually thanks to FLUX and we will get back to that.

I used Angular JS on the first iteration of building JSFridge, the ALPHA prototype. I had a pretty good idea of what I wanted and Angular JS makes you extremely productive. My solution to passing changes to application state was using events. I emitted events up the scope chain, and down the scope chain. My controllers had their own "event-controller" attached to them. There was a lot of state going all over the place. As I was working on the project every single day I managed to keep the complexity in my head, but my brain was constantly running on overdrive. Especially when I got to the bug-fixing part I had to lock myself in a room to not be disrupted, as I would totally loose may trail of thought. I could not continue using Angular JS going to BETA, at least not the way I was using it.

My first look into React JS and FLUX

My first read on React JS and FLUX was on the Facebook site, Facebook Flux. I also watched the Introduction to React JS. I thought; "This is what I need to keep me sane building the JSFridge BETA". I downloaded React JS and started to play around with it. I also had a look at the dispatcher and stores.

Its funny how we humans do not like things that are different and I am the first to admit that. Now having worked quite a bit with React JS I am comfortable with the API and I appreciate what it gives me. But there was a threshold. Initially I did not like the API. It felt like I was writing code even "below native JavaScript". What I mean is that "componentWillMount" and "componentDidUnmount" is nothing you are used to handling in other controller/view concepts in other frameworks. The fact that React JS and FLUX is not a complete toolset for building a webapplication was kind of a disappointment to me also. I was not used to choosing separate tools for routing, ajax etc. I wanted a complete framework. I wanted something like Backbone or Angular, only with FLUX.

Do it yourself sometimes work

So I decided to build my own FLUX framework inspired by the concepts of Facebook FLUX and React JS. I am not going to talk about that in this article, you can read more about it at jflux.io, but the point is that it helped me figure out exactly what I wanted from FLUX and React JS to build a complex application like JSFridge. It also made me realise how brilliant React JS is, and why I just could not settle with the Dispatcher and Store concepts.

In this article we are going to go through the architecture of JSFridge and look at how jFlux concepts helped controlling the application state. Then, to finish off the article, we will look at how you can take these concepts I explain and use them with React JS.

Application state in complex applications

So what FLUX initially helps us with is to introduce a strong concept of application state. Stores are what holds the state of your application, while a component holds the state of your view. A question quickly arises though and that is: "What is the scope of a store?". Do you want one store for your whole application or do you want to divide the responsibility of application state into multiple stores? Of course I could just answer that question with: "It depends", but there is actually a big problem with using multiple stores and that is the first thing we are going to look at.

Multiple or single stores?

This is pretty much the store setup of JSFridge:

| FLUX - Stores |

  |-----------| |-----------| |-------------| |-------------------|
  | UserStore | | HomeStore | | CourseStore | | CreateCourseStore |
  |-----------| |-----------| |-------------| |-------------------|

But actually it did not start out like that. It was something like this:

| FLUX - Stpres |

  |-----------| |-----------| |-------------| |-------------------|
  | UserStore | | HomeStore | | CourseStore | | CreateCourseStore |
  |-----------| |-----------| |-------------| |-------------------|
  
  |--------------| |---------------| |----------------| |------------|
  | ConsoleStore | | PlaybackStore | | RecordingStore | | SceneStore |
  |--------------| |---------------| |----------------| |------------|

What quickly became a problem with this setup was their circular dependencies. F.ex. the "isPlaying" state was stored in the "PlaybackStore" and the "isRecording" state was stored in the "RecordingStore", but both of them needed to know about each other in different scenarios. So what I realized is that you have two types of stores. You have application wide stores, like "UserStore" that is not dependant on any other stores. And then you have stores that represent a specific section in your application, like "CourseStore" and "HomeStore". It looks something like this:

| FLUX - Stores |

  |-----------|
  | UserStore |
  |-----------|
        |
        |----------------------------------
        |              |                  |
  |-----------| |-------------| |-------------------|
  | HomeStore | | CourseStore | | CreateCourseStore |
  |-----------| |-------------| |-------------------|

So stores that are part of one section of your application should be contained within a single store. Think of them like pages of your webapp, a modal or some other contained section. Stores that has nothing to do with a specific section, like "UserStore", can also be contained within one store. What we want to avoid is stores being dependant on each other both ways.

But now we run into a different problem. You can not put all your store code in one file, that will create quite a mess. The "CourseStore" of JSFridge is very big, but it is split into different files and handled much like "mixins" in React JS. We will look at a specific solution for this shortly.

Not only change events

A different issue I encountered was that not all state updates should trigger a change event. Let me use a simple example to explain this part:

In your store:

changeTitle: function (title) {
    this.title = title;
    this.emit('change');
  },
  getTitle: function () {
    return this.title;
  }

In your component:

componentWillMount: function () {
    store.addChangeListener(this.updateTitle);
  },
  updateTitle: function () {
    this.setState({
      title: store.getTitle()
    });
  },
  render: function () {
    return (<div>{this.state.title}</div>);
  }

Now, whenever the title changes it will be reflected in the component. That is all great, but what if we are not going to reflect a state in the UI, but react to the change of a state. An example of that would be toggling a duration.

In your store:

play: function () {
    this.isPlaying = true;
    this.emit('change');
    this.emit('play');
  },
  stop: function () {
    this.isPlaying = false;
    this.emit('change');
    this.emit('stop'); 
  },
  isPlaying: function () {
    return this.isPlaying;
  }

In your component:

componentWillMount: function () {
    store.addChangeListener(this.update);
    store.addListener('play', this.startDuration);
    store.addListener('stop', this.stopDuration);
  },
  startDuration: function () {
    this.interval = setInterval(function () {
      this.setState({
        duration: this.state.duration++
      });
    }.bind(this), 1000);
  },
  stopDuration: function () {
    clearInterval(this.interval);
  },
  update: function () {
    this.setState({
      buttonClass: store.isPlaying() ? 'red' : 'green'
    });
  },
  render: function () {
    return (<div><button className={this.state.buttonClass}>Toggle</button> {this.state.duration}</div>);
  }

It would not make sense to handle the starting and stopping of the duration with a change event, because then the component itself would have to know about the previous "isPlaying" state to know if it actually changed.

What does the dispatcher actually do?

What I also realized is that the dispatcher of the FLUX architecture does not really do much. Also the principle of calling all stores, no matter what action is dispatched did not quite make sense to me either. The important thing is the actions and since we are already using events, why not use events on them too? The concept is that you create a list of possible actions for your application and you trigger them by calling them, and passing optional arguments. The stores will then listen to actions directly and run methods when actions are triggered. It looks something like this in jFlux:

var actions = {
    'addTodo': createAction()
  };
  
  var myStore = createStore(function () {
    
    this.addTodo = function (title) {
      // Do something
    };
    
    this.listenTo(actions.addTodo, this.addTodo);
    
  });
  
  var myComponent = createComponent({
    buttonClick: function () {
      actions.addTodo(this.state.title);
    }
  });

As you can see we call the action from the component, we listen to the action from the store and that is how things connect. To me it just makes more sense.

Bringing it together

So to build a React JS application with these principles I have deviced a little library called flux-react. The initial version was based on an early article I wrote about FLUX and React JS, but as time passes and you get more experience, the tools change. So this is the new version.

Actions

So actions are what links your components (and anything else that wants to change state) with your stores. You define them just by naming them. When calling an action the arguments will be deepCloned to avoid later mutation of complex objects passed to the store.

var flux = require('flux-react');
var actions = flux.createActions([
  'addTodo',
  'removeTodo',
  'toggleTodo',
  'updateTodo'
]);
module.exports = actions;

Stores

Stores are where you define your application state, update it and notify components about changes.

var flux = require('flux-react');
var actions = require('./actions.js');
var TodosStore = flux.createStore({

  // We put the state directly on the store object
  todos: [],
  
  // Then we point to the actions we want to react to in this store
  actions: [
     actions.addTodo
  ],
  
  // The action maps directly to a method. So action addTodo maps to the
  // method addTodo()
  addTodo: function (title) {
    this.todos.push({title: title, completed: false});
    this.emitChange();
  },
  
  // The methods that components can use to get state information
  // from the store. The context of the methods is the store itself. 
  // The returned values are deepcloned, which means
  // that the state of the store is immutable
  exports: {
    getTodos: function () {
      return this.todos;
    }
  }
});
module.exports = TodosStore;

So lets just see how this is used in a component before going over the concept:

var React = require('react');
var store = require('./TodosStore.js');

var MyComponent = React.createClass({
  getInitialState: function () {
    return {
      todos: store.getTodos()
    };
  },
  componentWillMount: function () {
    store.addChangeListener(this.update);
  },
  componentWillUnmount: function () {
    store.removeChangeListener(this.update);
  },
  update: function () {
    this.setState({
      todos: store.getTodos()
    });
  },
  render: function () {
    return (
      <div>Number of todos is: {this.state.todos.length}</div>
    );
  }
});
module.exports = MyComponent;

Okay. So what I noticed building JSFridge was that my actions always mapped directly to a method. If the action was called "addTodo", the method handling that action in my store was also called "addTodo". That is why actions in "flux-react" map directly to a method.

An other concept is the "exports". You only want to expose a set of getter methods that your components can use. Three things happens with exports:

The exports object is the object that is returned when creating a store
All methods in exports are bound to the store, letting you use "this" to point to the state in the store
Exported values are automatically deep cloned

Now that last part needs a bit more explenation. The state, in your store should only be mutated (changed) inside the store. F.ex. returning a list of todos to a component should not allow that component to do changes there that is reflected in the store. This is because of debugging. If lots of different components starts to change state directly in your store you will get into trouble. So instead the "flux-react" store makes sure that any value returned from exports is deep cloned, right out of the box. The same goes for complex objects passed as arguments to an action. We do not want them to be changed later outside of the store and by doing so change the state of the store.

What about performance? Well, the thing is that values you return from a store are not big, neither are values you pass as arguments. Yes, maybe you have a phonebook of 10.000 people in your store, but your interface will never show all 10.000 of them. You may grab the 50 first of them and the rest requires searching or pagination. In that case it is only the search result, or next page, that is deep cloned. Never all the 10.000 people.

Mixing it up

Another feature implemented in the "flux-react" stores is mixins. This points back to my experience of building stores that depend on each other. Instead of creating separate stores and risk circular reference you create mixins instead. Lets check out an example where we use a mixin:

// FILE 1: My remove mixin
var actions = require('./actions.js');
var RemoveMixin = {
  actions: [
    actions.removeTodo
  ],
  removeTodo: function (index) {
    this.todos.splice(index, 1);
    this.emitChange();
  }
};
module.exports = RemoveMixin;

// FILE 2
var flux = require('flux-react');
var actions = require('./actions.js');
var RemoveMixin = require('./RemoveMixin.js');

var TodosStore = flux.createStore({
  todos: [],
  mixins: [RemoveMixin],
  actions: [
    actions.addTodo
  ],
  addTodo: function (title) {
    this.todos.push({title: title, completed: false});
    this.emitChange();
  },
  exports: {
    getTodos: function () {
      return this.todos;
    }
  }
});
module.exports = TodosStore;

As you can see you just create an object, just like a React JS mixin, and bring it into your main store file. The properties values that merge are: actions, exports and mixins. Any other methods and/or state properties will also be merged into the store. This will keep you sane and prevent you from hitting some kinda of dependency problem.

What I also found to be useful on JSFridge was putting all states in one mixin. That gives you a lookup of all states. The same for exports. Let me show you what I mean:

// FILE 1: All states are listed here
var StatesMixin = {
  foo: 'bar',
  moreState: {},
  listState: [],
  isDoingSomething: true
};

// FILE 2: Example handler
var Handler1Mixin = {
  actions: [
    actions.addToList
  ],
  addToList: function (item) {
    this.listState.push(item);
    this.emitChange()
  }
};

// FILE 3: All exports are defined here, along with bringing in the mixins
var MyMainStore = flux.createStore({
  mixins: [StatesMixin, Handler1Mixin, Handler2Mixin, Handler3Mixin],
  exports: {
    getFoo: function () {
      return this.foo;
    },
    getList: function () {
      return this.listState;
    }
  }
});

So any of the handler mixins contains actual actions and handlers for those actions. That is a sweet setup and now you can see how easy it is to say: "My application has 35 application states".

Summing it up

I was not trying to point out that Facebook Flux with its dispatcher and stores are the wrong way to go. I just wanted to share my experience using flux architecture and what I needed to keep me sane. If you want to check out flux-react, please do. If not, I hope this article gave you a couple of valuable points. Thanks for reading!

Nailing that validation with React JS

Wed, 22 Oct 2014 09:21:30 +0000

Validation is complex. Validation is extremely complex. I think it is right up there at the top of implementations we misjudge regarding complexity. So why is validation so difficult in general? How could we implement this with React JS? And do you get a prize for reading through this article? ... yep, you do! Look forward to a virtual cookie at the bottom of this article, you will definitely deserve it ;-)

At my employer, Gloppen EDB Lag, we are building a React JS component framework for application development. We have everything from grids and panels to calendars and forms. Think of it as React Bootstrap, but with bigger parts specific to our applications. So we have lots of forms in our applications and we needed a form that could handle both user input validation, server validation and be very flexible with the contents of the form.

This article will explain the challenges and the thought process of building such a form component. Forms and validation is complex no matter what framework you use, and even though we look at React JS here, the same principles goes for all frameworks.

As a result of writing this article I built an extension to React JS, formsy-react... and the same concept implemented for Angular JS: formsy-angular. This is a small extension that I think nails that "sweet spot" between flexibility and reuseability of building forms in your application and still get all the difficult wiring of validation for free.

Validation in general

Validation is most often related to forms and that is what we are going to focus on here. First of all we have to divide our validation into two:

Client side validation
Server side validation

You should of course always have server side validation, but to improve user experience we validate on the client side also. Bringing client side validation into forms has seriously made them more complex. It is not just the concept of handling validation state in the form, but we also have many different ways of indicating the actual validation error.

Red border on the input
Tooltip
Text to the right
Text underneath
Text on each form element or general text at the top... or bottom
Lock submit button until form is valid

If that is not enough, we also have a choice of handling validation as we type/blur and not just when submitting the whole form. And even worse, the form should not validate the inputs initially, except if you pass initial values or you have set that input as required.

A scaling related question

A form... is it view state or is it application state? Let me explain that in more detail. View state is handled in the controller of your UI. In Angular JS this would be the controller, in React JS it is the component and in Backbone JS it would be the View. Application state is handled further up in your application architecture. In Angular that would be a service, in React JS (with flux) it is a store and in Backbone JS it would have to be something you made up yourself. So, if nothing else in the application cares about the form we only need to care about view state. If some other part of the application cares about the state of the form, we have to implement application state.

So what is the case? View state or application state? In my experience a form is a completely isolated implementation, which means the only thing that cares about the form is the view (component). In Angular JS and Backbone JS that might not be such a hard choice, as you really do not have a strong concept of application state, but with React JS and FLUX it is a very important question to answer. Jump ahead to "Lets get an overview" if the FLUX part does not interest you.

React JS FLUX form validation

If you decided that the form was application state you would have to trigger an action to save the form, have a validation state in your store and you would have to grab that state when the request to the server was responded and the store emitted a change. This requires more implementation and most certainly more implementation than you really need. Another thing is that you would still have view state because the user input validation does not have anything to do with the store. Lets visualize just the server validation part:

| FLUX - Application state |

                    |------------|
  |---------------> | DISPATCHER | // 3. Pass submit to store
  |                 |------------|
  |                       |
  |                   |-------|
  |                   | STORE | // 4. Save to server, update state and emit change
  |                   |-------|
  |                       |
  |                 |-----------|
  |                 | COMPONENT | // 1. Get server validation state
  | 2. submit form  |-----------|
  |-----------------------|

This is of course a bigger implementation than:

| FLUX - Component state |

  |-----------|
  | COMPONENT | // Submit, update state based on server response and update component
  |-----------|

So I personally believe validation should be handled within the component, which of course is the simpler, but again least scalable solution. That said you can still notify your stores about the state of the form. You can add success and error handler to your form that triggers an action:

| FLUX - Application state |

                 |------------|
  |------------> | DISPATCHER | // 3. Pass action to store
  |              |------------|
  |                    |
  |                |-------|
  |                | STORE | // 4. Toggle some state based on success/error
  |                |-------|
  |                    |
  |              |-----------|
  |              | COMPONENT | // 1. Send success/error action on server response when form submitted
  | 2. action    |-----------|
  |--------------------|

So to summarise. An isolated component is the way to go here.

Lets get an overview

Okay, so what we want to do is create a generic form component for our application. The form itself should have a valid/invalid state and its inputs should also have individual valid/invalid states. We also want validation in both directions:

| FORM - Validation |

|--------|
| SERVER |
|--------|
    |
    | // Is form valid?
    |
|------|
| FORM |
|------|
    |
    | // Is input valid?
    |
|--------|
| INPUTS |
|--------|

When we change our inputs we want to validate the inputs themselves. If they turn out to be invalid we want to go up to the form and make the form invalid also. But also posting the form to the server could cause invalid state of the form, and we want that to propagate down to the specific inputs. An example of this would be inserting a username in an input. The validation of the input itself could be that the value is required and on the server it checks if the username is actually available. Regardless of where it fails we need to tell both the form and the specific input about it.

And this is where things are really getting tricky. How you choose to design validation user experience is a matter of choice, but wiring up all the validation can be a daunting task.

So how do we go about handling this?

Well, we want this to be generic. So first of all we need our own form component and then we need our own input components. We will only look at a typical input in this article, but you can use the same principal on any kind of component you want to build.

Let us take a quick look at how we want to use these two components:

var MyApplicationForm = React.createClass({
  changeUrl: function () {
    location.href = '/success';
  },
  render: function () {
    return (
      <App.Form url="/emails" onSuccess={this.changeUrl}>
        <div className="form-group">
          <label>Email</label>
          <App.Input name="email" validations="isEmail" validationError="This is not a valid email"/>
        </div>
      </App.Form>
    );
  }
});

We create a generic form component that takes a url and an onSuccess handler. The children of the form can be anything, making it easier to implement different forms in your application. The input takes a name, that will result in the property/attribute passed to your server, and finally it has a validation description and validation error text. The validation error text is defined on the input itself because the validation rule does not translate directly to an error message. The same validation rule might give different validation error messages in different contexts and you might need to handle multiple languages.

Lets define our form as a component first:

var Form = React.createClass({
  render: function () {
    return (
      <form>
        {this.props.children}
        <button type="submit">Submit</button>
      </form>
    );
  }
});

So our form currently wraps the children with a form element and adds a submit button at the bottom. What we want to do first is create a relationship between the form component and any input child components. We have to create this relationship because we want our form to validate when inputs change and we want inputs to validate when the form gets an error form the server. But we want it to be smart, we want it to be dynamic, because you can have any number of nested children in your form. So lets see how we can solve this.

Traversing children

What we want to do is traverse the children of the form and create a registry of inputs inside the App.Form component:

var Form = React.createClass({
  componentWillMount: function () {
    this.inputs = {}; // We create a map of traversed inputs
    this.registerInputs(this.props.children); // We register inputs from the children
  },
  registerInputs: function (children) {
    
    // A React helper for traversing children
    React.Children.forEach(children, function (child) {
    
      // We do a simple check for "name" on the child, which indicates it is an input.
      // You might consider doing a better check though
      if (child.props.name) {
      
        // We attach a method for the input to register itself to the form
        child.props.attachToForm = this.attachToForm;
        
        // We attach a method for the input to detach itself from the form
        child.props.detachFromForm = this.detachFromForm;
      }
      
      // If the child has its own children, traverse through them also...
      // in the search for inputs
      if (child.props.children) {
        this.registerInputs(child.props.children);
      }
    }.bind(this));
  },
  
  // All methods defined are bound to the component by React JS, so it is safe to use "this"
  // even though we did not bind it. We add the input component to our inputs map
  attachToForm: function (component) {
    this.inputs[component.props.name] = component;
  },
  
  // We want to remove the input component from the inputs map
  detachFromForm: function (component) {
    delete this.inputs[component.props.name];
  },
  render: function () {
    return (
      <form>
        {this.props.children}
        <button type="submit">Submit</button>
      </form>
    );
  }
});

So now all input children will get two methods from the form. One to register and one to unregister. The next thing we want to implement is an internal model in the form. The model will keep track of all the values from the inputs, so that when the form is submitted it will submit it with the values of the inputs. The name of the inputs will be the key.

Adding a model

var Form = React.createClass({
  componentWillMount: function () {
    this.model = {}; // We add a model to use when submitting the form
    this.inputs = {};
    this.registerInputs(this.props.children);
  },
  registerInputs: ...
  attachToForm: function (component) {
    this.inputs[component.props.name] = component;
    
    // We add the value from the component to our model, using the
    // name of the component as the key. This ensures that we
    // grab the initial value of the input
    this.model[component.props.name] = component.state.value;
  },
  detachFromForm: function (component) {
    delete this.inputs[component.props.name];
    
    // We of course have to delete the model property
    // if the component is removed
    delete this.model[component.props.name];
  },
  render: ...
});

Okay, I think it is a good idea to create our App.Input component now to see this first part in action. Then we will move on to communicating with the server and finish this whole thing up with validation.

The App.Input component

There is not really much to it. We create an input that will use our attachToForm and detachFromForm methods and update its value state when changing the value of the input.

var Input = React.createClass({
  
  // Create an initial state with the value passed to the input
  // or an empty value
  getInitialState: function () {
    return {
      value: this.props.value || ''
    };
  },
  componentWillMount: function () {
    this.props.attachToForm(this); // Attaching the component to the form
  },
  componentWillUnmount: function () {
    this.props.detachFromForm(this); // Detaching if unmounting
  },
  
  // Whenever the input changes we update the value state
  // of this component
  setValue: function (event) {
    this.setState({
      value: event.currentTarget.value
    });
  },
  render: function () {
    return (
      <input type="text" name={this.props.name} onChange={this.setValue} value={this.state.value}/>
    );
  }
});

So now we have an input that works with our form. Let us create the submit method.

Submitting the form

var Form = React.createClass({
  componentWillMount: ...
  registerInputs: ...
  attachToForm: ...
  detachFromForm: ...
  
  // We need a method to update the model when submitting the form.
  // We go through the inputs and update the model
  updateModel: function (component) {
    Object.keys(this.inputs).forEach(function (name) {
      this.model[name] = this.inputs[name].state.value;
    }.bind(this));
  },
  
  // We prevent the form from doing its native
  // behaviour, update the model and log out the value
  submit: function (event) {
    event.preventDefault();
    this.updateModel();
    console.log(this.model);
  },
  
  // And we add our submit method to onSubmit
  render: function () {
    return (
      <form onSubmit={this.submit}>
        {this.props.children}
        <button type="submit">Submit</button>
      </form>
    );
  }
});

And the syntax so far for building the form:

var MyApplicationForm = React.createClass({
  render: function () {
    return (
      <App.Form>
        <div className="form-group">
          <label>Email</label>
          <App.Input name="email"/>
        </div>
      </App.Form>
    );
  }
});

When I type "some@email.com" in the input and submit the form we see: { email: "some@email.com" }, in our log. That is great! Lets move on to actually submitting this data to the server.

Sending the model to the server

var Form = React.createClass({
  componentWillMount: ...
  registerInputs: ...
  attachToForm: ...
  detachFromForm: ...
  updateModel: ...
  
  // Just using some fake ajax service here to post the model to
  // the url set on the form. On sucess it wil run the onSuccess method.
  // Depending on your app you probably want to verify that the method actually exists
  submit: function (event) {
    event.preventDefault();
    this.updateModel();
    MyAjaxService.post(this.props.url, this.model)
      .then(this.props.onSuccess);
  },
  render: ...
});

Now I want to take a minute to make sure that we give a good user experience. When submitting this form it will probably take a little bit of time before we get a response. Let us make sure that the form does not allow you to click submit again. Lets create a isSubmitting state on our form.

Submitting

var Form = React.createClass({
  getInitialState: function () {
    return {
      isSubmitting: false
    };
  },
  componentWillMount: ...
  registerInputs: ...
  attachToForm: ...
  detachFromForm: ...
  updateModel: ...
  
  // We change the state of the form before submitting
  submit: function (event) {
    event.preventDefault();
    this.setState({
      isSubmitting: true
    });
    this.updateModel();
    MyAjaxService.post(this.props.url, this.model)
      .then(this.props.onSuccess);
  },
  
  // We disable the button if the form is submitting
  render: function () {
    return (
      <form onSubmit={this.submit}>
        {this.props.children}
        <button type="submit" disabled={this.state.isSubmitting}>Submit</button>
      </form>
    );    
  }
});

And now our form supports:

var MyApplicationForm = React.createClass({
  changeUrl: function () {
    location.href = '/success';
  },
  render: function () {
    return (
      <App.Form url="/emails" onSuccess={this.changeUrl}>
        <div className="form-group">
          <label>Email</label>
          <App.Input name="email"/>
        </div>
      </App.Form>
    );
  }
});

Now we are getting somewhere! Lets get going with validation.

Adding validation

So there are a few things we need to do here:

We need a valiation library
We need a validate method that both runs the validation of a specific input and validates the form itself
We need to handle errors from the server and set inputs and the form to invalid state

1. Validation library

We initially chose validator as our validation library. It has lots of default rules and we wanted to use them by defining comma separated rules on a validations property. Validator made that easy. Have a look at what we wanted:

var MyApplicationForm = React.createClass({
  render: function () {
    return (
      <App.Form>
        <div className="form-group">
          <label>Email</label>
          <App.Input name="email" validations="isEmail"/>
          <label>Number</label>
          <App.Input name="number" validations="isNumeric,isLength:4:12"/>
        </div>
      </App.Form>
    );
  }
});

What we realized though is that running a validation rule on some value is a very small percentage of the whole issue we are trying to solve, and as this code moved into the formsy-react extension, there was no reason to add a dependency to "Validator". We just implemented our own validation rule handling.

2. Implementing the validate method

As stated above we need a validate method that will handle our input validation and after that validate the actual form. We also want to use the same validator no matter what type of input it is. This means that the form needs to have this method, but at the same time let the inputs use it.

An other thing here is empty values. Should they be validated? Does "no value" actually mean "wrong value"? In this context requiring an input and giving an input is two different things. There might be an input you do not require, but if you put something in there you want to validate it. So we have to handle this with a required property. This is the syntax:

var MyApplicationForm = React.createClass({
  render: function () {
    return (
      <App.Form>
        <div className="form-group">
          <label>Email</label>
          <App.Input name="email" validations="isEmail" required/>
          <label>Number</label>
          <App.Input name="number" validations="isNumeric, isLength:4:12"/>
        </div>
      </App.Form>
    );
  }
});

Let us look at the implementation:

var Form = React.createClass({
  getInitialState: function () {
    return {
      isSubmitting: false,
      
      // We add a new state here, isValid, which will be true initially.
      // When inputs are attached they will be validated, in turn 
      // changing this value to false if any inputs are invalid
      isValid: true
    };
  }, 
  componentWillMount: ...
  
  // When the form loads we validate it
  componentDidMount: function () {
    this.validateForm();
  },
  registerInputs: function (children) {
    React.Children.forEach(children, function (child) {
    
      if (child.props.name) {
        child.props.attachToForm = this.attachToForm;
        child.props.detachFromForm = this.detachFromForm;
        
        // We also attach a validate method to the props of the input so
        // whenever the value is upated, the input will run this validate method
        child.props.validate = this.validate;
      }

      if (child.props.children) {
        this.registerInputs(child.props.children);
      }
      
    }.bind(this));
  },
  
  // The validate method grabs what it needs from the component,
  // validates the component and then validates the form
  validate: function (component) {
  
    // If no validations property, do not validate
    if (!component.props.validations) {
      return;
    }
    
    // We initially set isValid to true and then flip it if we
    // run a validator that invalidates the input
    var isValid = true;
    
    // We only validate if the input has value or if it is required
    if (component.props.value || component.props.required) {
    
      // We split on comma to iterate the list of validation rules
      component.props.validations.split(',').forEach(function (validation) {

        // By splitting on ":"" we get an array of arguments that we pass
        // to the validator. ex.: isLength:5 -> ['isLength', '5']
        var args = validation.split(':');

        // We remove the top item and are left with the method to
        // call the validator with ['isLength', '5'] -> 'isLength'
        var validateMethod = args.shift();

        // We use JSON.parse to convert the string values passed to the
        // correct type. Ex. 'isLength:1' will make '1' actually a number
        args = args.map(function (arg) { return JSON.parse(arg); });

        // We then merge two arrays, ending up with the value
        // to pass first, then options, if any. ['valueFromInput', 5]
        args = [component.state.value].concat(args);

        // So the next line of code is actually:
        // validator.isLength('valueFromInput', 5)
        if (!validator[validateMethod].apply(validator, args)) {
          isValid = false;
        }
      });
      
    }
    
    // Now we set the state of the input based on the validation
    component.setState({
      isValid: isValid,
      
      // We use the callback of setState to wait for the state
      // change being propagated, then we validate the form itself
    }, this.validateForm);

  },
  validateForm: function () {
    
    // We set allIsValid to true and flip it if we find any
    // invalid input components
    var allIsValid = true;
    
    // Now we run through the inputs registered and flip our state
    // if we find an invalid input component
    var inputs = this.inputs;
    Object.keys(inputs).forEach(function (name) {
      if (!inputs[name].state.isValid) {
        allIsValid = false;
      }
    });
    
    // And last, but not least, we set the valid state of the
    // form itself
    this.setState({
      isValid: allIsValid
    });
  },
  attachToForm: function (component) {
    this.inputs[component.props.name] = component;
    this.model[component .props.name] = component.state.value;
    
    // We have to validate the input when it is attached to put the
    // form in its correct state
    this.validate(component);

  },
  detachFromForm: ...
  updateModel: ...
  submit: ...
  render: ...
});

Lets jump over to the input component and make sure everything there is handled correctly:

var Input = React.createClass({

  getInitialState: ...
  componentWillMount: function () {
  
    // If we use the required prop we add a validation rule
    // that ensures there is a value. The input
    // should not be valid with empty value
    if (this.props.required) {
      this.props.validations = this.props.validations ? this.props.validations + ',' : '';
      this.props.validations += 'isValue';
    }
    
    this.props.attachToForm(this);
  },
  componentWillUnmount: ...
  setValue: function (event) {
    this.setState({
      value: event.currentTarget.value
      
      // When the value changes, wait for it to propagate and
      // then validate the input
    }, function () {
      this.props.validate(this);
    }.bind(this));
  },
  render: function () {
    return (
      <input type="text" name={this.props.name} onChange={this.setValue} value={this.state.value}/>
    );
  }
});

Wow, that was a lot of code! Well, this is somewhat the hidden message of this article. Validation is freakin' complex! There are so many ways to create a user experience, you need validation both from user input and from server and you have two concepts of validation, form validation and input validation. On top of that we have this total headspin of "Should an empty value be validated?". But lets finish this up and I will give you a couple of advices when it comes to building validation for your application.

3. Server error response

If the form itself is valid that does not mean the backend is happy. We have to make sure that we display error messages from the server. In this implementation we have a requirement. If the backend gives validation errors it has to return an object where the key maps to the name of the inputs and the value is the error message itself. F.ex. { email: 'Email already exists' }. Lets dive into our FORM code again and add an error handler.

var Form = React.createClass({
  getInitialState: ...
  componentWillMount: ...
  componentDidMount: ...
  registerInputs: ...
  validate: function (component) {
  
    if (!component.props.validations) {
      return;
    }
    
    var isValid = true;
    if (component.props.value || component.props.required) {
      component.props.validations.split(',').forEach(function (validation) {
        var args = validation.split(':');
        var validateMethod = args.shift();
        args = args.map(function (arg) { return JSON.parse(arg); });
        args = [component.state.value].concat(args);
        if (!validator[validateMethod].apply(validator, args)) {
          isValid = false;
        }
      }); 
    }
    
    component.setState({
      isValid: isValid,
      
      // Our new server error state on a component needs to be reset when
      // new validations occur
      serverError: null 
    }, this.validateForm);
    
  },
  validateForm: ...
  attachToForm: ...
  detachFromForm: ...
  updateModel: ...
  submit: function (event) {
    event.preventDefault();
    this.setState({
      isSubmitting: true
    });
    this.updateModel();
    MyAjaxService.post(this.props.url, this.model)
      .then(this.props.onSuccess)
      .catch(this.setErrorsOnInputs); // We catch the error from the post
  },
  setErrorsOnInputs: function (errors) {
  
     // We go through the errors
     Object.keys(errors).forEach(function (name, index) {
     
      // We grab the component by using the key from errors
      var component = this.inputs[name];

      // We change the state
      component.setState({
        isValid: false,
        serverError: errors[name] // We use a new state here to indicate a server error
      });
      
      // And after changing the state of the form,
      // we validate it
      this.setState({
        isSubmitting: false
      }, this.validateForm);
      
    }.bind(this));
  },
  render: ...
});

Almost there! The only thing remaining now is making sure that our input validates and displays validation errors correctly.

var Input = React.createClass({
  
  getInitialState: function () {
    return {
      value: this.props.value || '',
      serverErrors: null // No initial server errors
    };
  },
  componentWillMount: ...
  componentWillUnmount: ...
  setValue: ...
  
  // We have to wrap our input to display error messages
  render: function () {
    
    // We create variables that states how the input should be marked.
    // Should it be marked as valid? Should it be marked as required?
    var markAsValid = this.state.isValid;
    var markAsRequired = this.props.required && !this.state.value;
    
    var className = '';
    
    // We prioritize marking it as required over marking it
    // as not valid
    if (markAsRequired) {
      className = 'required';
    } else if (!markAsValid) {
      className = 'error';
    }
    
    // If it is valid or marked as required, we show no error.
    // If not valid we either show the server error or the validation error
    return (
      <div className={className}>
        <input type="text" name={this.props.name} onChange={this.setValue} value={this.state.value}/>
        <span>{markAsValid || markAsRequired ? null : this.state.serverError || this.state.validationError}</span>
      </div>
    );
  }
});

Sweet! We got through it! And while we sum this up, enjoy your virtual cookie:

As stated this article was written to point out the insane complexity we confront when building good user experiences in forms. The big takeaway here is that a form is an isolated implementation, just like a live search, autocomplete, calendar etc. I do not recommend implementing it as a "part of your application logic". The other takeaway here is that you will need a dynamic, but tight relationship between your form and the inputs. The reason is that user inputs will be validated on the input itself, but also needs to notify the form. And the same when the form receives an error from the server. It needs to invalidate itself and the related inputs. It is also worth mentioning that "empty value" should only be validated if you have a "required" flag on your input.

As stated above this article resulted in an extension for React JS, formsy-react, and for Angular JS, formsy-angular. This will essentially just give a form and a toolbox to build whatever inputs you want in your application, even non-traditional form inputs and you still get the validation for free.

Thanks for taking the time to read through this article and I hope it will help you handle forms and validation with React JS.