README

React Dendrimer

React dendrimer is a higher order component which allows for encapsulation of react-redux apps as controlled components within a larger react application.

Installation:

npm install --save react-dendrimer

Why Do I Need This?

There's a good chance you don't! Composition in redux is intended to happen at the reducer level, however there are some cases where you may need to isolate "sub-apps" as individual components in a larger application (see https://redux.js.org/recipes/isolating-subapps).

A problem arises when you need to communicate between "sub-apps", as they are each their own source of truth! The best solution would be to join all "sub-apps" that need to communicate with eachother under a single store through reducer composition, however this isn't always a realistic possibility.

React dendrimer provides a simple solution for working with and communicating between redux "sub-apps" without sacrificing one-way data flow, by allowing you to wrap entire redux apps as controlled components -- just like you would a form input!

Example usage

Let's create a controlled redux app component (dendrimer) from a redux application with a simple state tree:

import { Component } from 'react';
import Dendrimer from 'react-dendrimer';
import { SubAppRootComponent, reducer, myCustomMiddleware } from './subApp';

export default class SubAppDendrimer extends Component {
    constructor(props) {
        super(props);

        this.state = {
            subAppState: {
                foo: true,
                bar: true
            }
        };
    }

    render() {
        return (
            <Dendrimer
                onChange={this.handleSubAppChange}
                reducer={reducer}
                state={this.state.subAppState}
            >
                <SubAppRootComponent />
            </Dendrimer>
        );
    }

    handleSubAppChange(subAppAction, newSubAppState) {
        this.setState({
            subAppState: newSubAppState
        });
    }
}

Each time an action dispatched within the "sub-app" would cause its state to change, the action and new state is instead provided to our callback handleSubAppChange. From here we can register the new state into our component state, and let it flow back into the "sub-app" through the state prop on Dendrimer.

Notably, the state tree of the "sub-app" store is not updated until the state flows back in through the state prop on Dendrimer, so the "sub-app" is in effect "controlled" by this outer component.

If our "sub-app" is dependent on some middleware (or store enhancer), we can add it to the Dendrimer by modifying the above example:

    render() {
        return (
            <Dendrimer
                enhancer={applyMiddleware(myCustomMiddleware)}
                onChange={this.handleSubAppChange}
                reducer={reducer}
                state={this.state.subAppState}
            >
                <SubAppRootComponent />
            </Dendrimer>
        );
    }

This way we can preserve the full functionality of the "sub-app" while ensuring it's state is controlled by the main app.

Note: The "sub-app" is still responsible for its own side-effects! Logging, ajax requests, etc performed by the "sub-app" will not be prevented by the dendrimer.

Contributions

Anyone is welcome to contribute to this package. My only "rule" is that your contribution must either pass the existing unit tests, or include additional unit tests to cover new functionality.

Here are some commands that may be helpful for development:

npm test: Runs the unit tests
npm run build: Builds the library

License

MIT

Usage no npm install needed!