alt

Check out the API Reference for full in-depth docs. For a high-level walk-through on flux, take a look at the Getting Started guide. What follows below applies only to the master branch of alt and not the latest distribution. Any questions? ask in the gitter room.

Why you should be using Alt

• It is pure flux. Stores have no setters, the flow is unidirectional.
• Isomorphic and works with react-native.
• Actively maintained and being used in production.
• Extremely flexible and unopinionated in how you use flux. Create traditional singletons or use dependency injection.
• It is terse. No boilerplate.

What does it look like?

Alt

import Alt from 'alt';
export default new Alt();

Actions

import alt from './alt';

class TodoActions {
  updateTodo(id, text) {
    return { id, text }
  }
}

export default alt.createActions(TodoActions);

Store

import alt from './alt';
import TodoActions from './TodoActions'

class TodoStore {
  constructor() {
    this.bindListeners({
      updateTodo: TodoActions.updateTodo
    });

    this.state = {
      todos: []
    };
  }

  updateTodo(todo) {
    this.setState({ todos: this.state.todos.concat(todo) });
  }
}

export default alt.createStore(TodoStore, 'TodoStore');

View

Using the connectToStores util from alt-utils package (npm install alt-utils)

// ES2015 (ES6)
import connectToStores from 'alt-utils/lib/connectToStores';
import { Component } from 'react';
import TodoStore from './TodoStore';

class TodoView extends Component {
  static getStores() {
    return [TodoStore];
  }

  static getPropsFromStores() {
    return TodoStore.getState();
  }

  render() {
    return (
      <ul>
        {this.props.todos.map((todo) => {
          return (
            <li key={todo.id}>{todo.text}</li>
          );
        })}
      </ul>
    );
  }
}
export default connectToStores(TodoView);

or

//ES2016 (ES7) using @connectToStores Decorator
import connectToStores from 'alt-utils/lib/connectToStores';
import { Component } from 'react';
import TodoStore from './TodoStore';

@connectToStores
class TodoView extends Component {
  static getStores() {
    return [TodoStore];
  }

  static getPropsFromStores() {
    return TodoStore.getState();
  }

  ...
}

In the Wild

Examples

• Airbnb Airpal
• Alt Notify
• Chrome Devtool
• Example Tests
• Github Example
• Isomorphic Alt
• Jumar's Tindahan
• Maple.js Webcomponents
• React Native Example
• React Router Example
• React Router Loopback
• React Webpack Rails Example
• React Webpack Altjs Example
• React Weather
• Shopping Cart
• Todo
• Typeahead
• Isomorphic React Examples
• Typescript Project
• Why did Social Tables choose Alt?

Boilerplates

• Isomorphic Flux Boilerplate
• React + Webpack + Node
• Web-React
• Generator-React-Webpack-Alt
• Isomorphic Alt Generator

Pure Flux + More

• Unidirectional data flow
• Stores have no setters
• Inversion of control
• Single central dispatcher
• All Stores receive the dispatch

Read about the Principles of Flux.

One really cool aspect of alt is that you can save snapshots of the entire application's state at any given point in time. This has many different use cases like:

• Time traveling through the state of your application. For fun and profit.
• Being able to debug from a broken state. Have your team send you the exact state the app was in when it crashed.
• Isomorphism. You save a snapshot that you send from the server to the client and then bootstrap back on the client.
• Rolling back to previous stable states.

There are also many utils available which interface well with alt:

• ActionListener lets you listen to individual actions without having to create a store.
• AltContainer a higher-order container component that is your swiss army knife for React.
• AltIso addon that uses iso to render your application on both server and client.
• atomic enables your stores for atomic transactions.
• connectToStores a higher-order function that wraps your React components for store listening.
• decorators a collection of useful ES7 decorators for working with alt.
• DispatchRecorder lets you record all your dispatches and replay them back at a later time.
• FinalStore is a Store that you can listen to that only emits when all your other stores have received all their data.
• ImmutableUtil makes working with immutable-js easy.
• TimeTravel enhances your stores so they are able to travel through different states in time.

Topical Guide

First we install alt through npm. Although alt is also available through bower.

npm install alt

The following topical guide covers on using alt as a singleton in a traditional flux way.

We'll be referring back to this code a lot by using the alt reference declared.

const Alt = require('alt');
const alt = new Alt();

ES6

Alt is written in, and encourages ES6. It is completely optional but it is pleasant to write.

You can use the es6 transpiler that comes with react courtesy of jstransform or you can use one of the other popular ES6 transpilers: babel or traceur.

You won't need an es6-shim but you can use one for further goodies in your javascripts.

Alt does depend on ES5 features, the good news is so does React. You can use es5-shim to support those pesky old browsers.

Typescript Definitions and Support

The typescript definitions for alt are located in the typings directory. This should be included in your project under typings/alt or whatever folder you use to manage your definitions files. You can import the dependencies react and es6-promises, easily with TSD. From here you can reference your typings as per usual with a reference tag <reference path="<path>.d.ts" />. Check the alt-typescript-tutorial for more information and project examples.

Using Typescript 1.5 you can import with the legacy syntax:

import Alt = require("alt");
import chromeDebug = require("alt/utils/chromeDebug");
import AltContainer = require("alt/AltContainer");

Creating Actions

Actions are the way you update state. They're kind of a big deal.

alt.createActions :: Class -> Actions

class LocationActions {
  updateLocation(city) {
    return city;
  }
}

const locationActions = alt.createActions(LocationActions);

You return the data from your action that you wish to dispatch. If you want to run async in your actions then you simply return a function where the first argument is the dispatch:

class LocationActions {
  updateLocationThatDoesItAsync(city) {
    return (dispatch) => {
      setTimeout(() => dispatch(city));
    };
  }
}

alt.createActions then returns an Object containing all the methods defined. You can then call your actions directly.

locationActions.updateLocation('Paris');

Writing out actions that pass data through directly can get quite tedious so there's a shorthand for writing these what are essentially identity functions

class LocationActions {
  constructor() {
    // for single action
    this.generateActions('updateLocation');

    // as well as for many actions
    this.generateActions('updateCity', 'updateCountry');
  }
}

const locationActions = alt.createActions(LocationActions);

locationActions.updateLocation('Las Vegas')

locationActions.updateCity('Las Vegas')
locationActions.updateCountry('US')

Remember, dispatch only takes one argument. Therefore, if you need to pass multiple arguments into a store you can use an Object.

class LocationActions {
  updateLocation(x, y) {
    return { x, y };
  }
}

const locationActions = alt.createActions(LocationActions);

locationActions.updateLocation('Miami', 'Florida');

A shorthand function created in the constructor will pass through the multiple parameters as an Array

class LocationActions {
  constructor() {
    this.generateActions('updateLocation'); // ['South Lake Tahoe, 'California']
  }
}

const locationActions = alt.createActions(LocationActions);

locationActions.updateLocation('South Lake Tahoe', 'California');

There's even a shorthand for the shorthand if all you're doing is generating a list of actions

const locationActions = alt.generateActions('updateLocation', 'updateCity', 'updateCountry');

Stores

Stores are where you keep a part of your application's state.

You can either define your stores as a class/constructor-prototype or as an Object.

alt.createStore :: Class, string -> Store

class LocationStore {
  constructor() {
    this.bindAction(locationActions.updateLocation, this.onUpdateLocation);

    this.state = {
      city: 'Denver',
      country: 'US'
    };
  }

  onUpdateLocation(obj) {
    const { city, country } = obj
    this.setState({ city, country });
  }
}

const locationStore = alt.createStore(LocationStore);

You can also use a regular old JavaScript Object to create your stores. This is more about aesthetic preference.

const locationStore = alt.createStore({
  displayName: 'LocationStore',

  bindListeners: {
    onUpdateLocation: locationActions.updateLocation
  },

  state: {
    city: 'Denver',
    country: 'US'
  },

  onUpdateLocation(obj) {
    const { city, country } = obj
    this.setState({ city, country });
  }
});

If you're creating a store using a class/constructor then you also have the option of assigning your state values to your instance directly and then you're able to update them in place.

function LocationStore() {
  this.city = 'San Francisco';
  this.country = 'US';
}

LocationStore.prototype.onUpdateLocation = function (obj) {
  this.city = obj.city;
  this.country = obj.country;
};

Store instances returned by alt.createStore can be listened to for updates by calling listen.

listen is meant to be used by your View components in order to await changes made to each store. It returns a function you can use to un-listen to your store.

locationStore.listen((data) => {
  console.log(data)
});

Alternatively, you can use the unlisten method. It takes in the same function you used for listen and unregisters it.

Another important method is getState, which returns a copy of the current store's state.

locationStore.getState().city === 'Denver'

Important Note

All defined methods in your Store class will not be available on the store instance. They are accessible within the class but not on the returned O