/redux-elm

The Elm Architecture in JavaScript http://salsita.github.io/redux-elm/

Primary LanguageJavaScript

NPM version Dependencies devDependency Status Build status Downloads Join the chat at https://gitter.im/salsita/redux-elm

The Elm Architecture in JavaScript for building really scalable applications.

redux-elm is framework specifically tailored for solving difficult problems that people have to face in modern front-end application development, it is heavily based on Composition.

Goal of this project is to solve hard problems by defining patterns, not implementation. Library is very lightweight and you should be able to fully understand the codebase. Main building block is redux which serves as predictable state container and because redux-elm is built on top of that, you will be able to benefit from all of its tooling:

  • DevTools
  • Time Travel
  • Immutable application snapshots
  • Easy unit testing

Because redux-elm is about Patterns, we have really thorough documentation which guides you to utilize all the ideas that redux-elm provides.

See why the Elm Architecture matters.

How does it look?

redux-elm is about Components and every Component must define two pieces Updater and View where Updater is very similar to Redux reducer and View is simple React Component, of course you can use your own View library.

Counter Updater

import { Updater } from 'redux-elm';

const initialModel = 0;

export default new Updater(initialModel)
  .case('Increment', model => model + 1)
  .case('Decrement', model => model - 1)
  .toReducer();

Counter View

import React from 'react';
import { view } from 'redux-elm';

export default view(({ model, dispatch }) => (
  <div>
    <button onClick={() => dispatch({ type: 'Decrement' })}>-</button>
    <div>{model}</div>
    <button onClick={() => dispatch({ type: 'Increment' })}>+</button>
  </div>
));

Installation & Usage

You can install redux-elm via npm.

npm install redux-elm --save

We didn't want to keep all the boilerplate in redux-elm repo therefore we've prepared simple redux-elm-skeleton repositiory which will serve as easiest way to start using redux-elm.

git clone git@github.com:salsita/redux-elm-skeleton.git
cd redux-elm-skeleton
npm install
npm start
open http://localhost:3000

You will see Hello World so that you can immediately open your favorite Text Editor and start writing your own application. Skeleton repo integrates redux-devtools Chrome extension, so we strongly recommend installing the extension.

Documentation

Goal of documentation is explaining basic principle of redux-elm and this is Composition, it's divided into few chapters to gradually increase amount of complexity.

  1. Getting Started Tutorial
  2. GifViewer Tutorial
  3. Composition

First two chapters describes basic principles, while Composition part is the most important part explaining how redux-elm helps you building really scalable application. There's also Chapter which explains how to properly Unit test your application.

Examples

You will find original Elm Architecture examples written in JavaScript using redux-elm:

  1. Counter
  2. Counters Pair
  3. Dynamic List of Counters
  4. Random GIF Viewer
  5. Random GIF Viewers Pair
  6. Dynamic List of Random GIF Viewers

Static Typing

Definitely one of the most important features of Elm programming language is its type system. Elm is statically typed language and fully supports type inference, unfortunately this is not same for JavaScript, however you can still use flowtype because redux-elm provides type definitions for everything that's publicly exposed. We strongly encourage you to do so, because Flow is a great help for spotting subtle bugs before they actually appear. Using Flow in your redux-elm project is seemless and does not require any additional effort except installing flow as your project's dependency.

static-typing

Flow checks:

  • correct model shape
  • Matchers
  • and many more...

All the examples implemented throughout tutorials in documentation have been ported to Flow version too and you can find them in examples-flow branch of redux-elm-skeleton repo.

For further information see documentation

Discussion

Join the discussion on gitter