@procore-canary/redux-modules

redux-modules

redux-modules is a refinement on the Redux module concept with developer experience in mind. It provides:

• A concise, intuitive way to define actions and state transformations
• Action creator middleware for transforming actions before they're dispatched
• A decorator that handles mapping state and actions to components
• A modified Redux Provider that dynamically registers new reducers as connected components mount

Getting Started

Install

npm install redux-modules --save

Usage Example

Here's an example of a simple todo app. First create a module that allows todos to be created and destroyed.

src/modules/todos.js

import { createModule } from 'redux-modules';
import { propCheck } from 'redux-modules-middleware';
import { fromJS, List } from 'immutable';

import { shape, string, number } from 'prop-types';

export default createModule({
  name: 'todos',
  initialState: List(),
  selector: state => ({ todos: state.get('todos') }),
  transformations: {
    create: {
      middleware: [
        middleware.propCheck(
          shape({ description: string.isRequired })
        ),
      ],
      reducer: (state, { payload }) =>
        state.update('collection', todos => todos.push(fromJS(payload))),
    },
    destroy: {
      middleware: [
        middleware.propCheck(number.isRequired),
      ],
      reducer: (state, { payload }) =>
        state.update('collection', todos => todos.delete(payload)),
    },
  },
});

Once the module is complete, the reducer has to be added to the store.

src/App.jsx

const store = createStore(todoModule.reducer, {});

export default const App = props => (
  <Provider store={store}>
    <Todos {...props}/>
  </Provider>
)

Alternatively, use ModuleProvider to allow reducers to be automatically added to the store at runtime.

import { ModuleProvider } from 'redux-modules';
const store = createStore(state => state, {});

export default const App = props => (
  <ModuleProvider store={store}>
    <Todos {...props}/>
  </ModuleProvider>
)

The last step is to connect the module to the view. This works like a normal Redux connect with the added bonus of auto dispatching and namespacing actions.

src/views/Todos.jsx

import { connectModule } from 'redux-modules';
import { Component, PropTypes } from 'react';
import { array, func, shape } from 'prop-types';

@connectModule(todoModule)
export default class Todos extends Component {
  static propTypes = {
    todos: array,
    actions: shape({
      create: func,
      destroy: func,
    }),
  };

That's it! Check the documentation for comparisons with idiomatic Redux, in depth examples, and advanced usage.

Documentation

• Motivation
• Basic Concepts
• Recipes
• API Reference
• Tooling

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!