Skip to content

dustinmyers/react-conflux

Repository files navigation

Conflux library logo

Conflux is a modularized state management system utilizing the Context API and React Hooks for the React ecosystem. It provides predictable and optionally-nested state containers for applications in an elegant, streamlined, and developer-friendly manner.

Table of Contents

Why Use Conflux?

Context and Hooks are relatively cutting-edge at the moment, but the concept of global state management is most likely familiar to even the newest of developers. Most existing systems currently revolve around a single global store. While this pattern does come with huge benefits, modern applications are so large and complex that these stores can sometimes give you "the forest with the tree" when one only needs partial slices of state.

While most people use Context in React to pass a single global state up-and-down the entire application, it also has the ability to be surgically scoped to a specific component tree within an application's component architecture. As most large chunks of state are sometimes only needed inside of their assigned section of the application, modularity, maintainability, and performance can all be improved by segmenting state to specific limbs of the component tree.

Conflux upgrades state management by combining the best facets of Redux, Context, and React Hooks. Developers can define state to a specific component, state tree, or the entire application. In fact, all three of these are possible at the same time through the use of multiple StateProviders. It then becomes a trivial matter to destructure out state for use in your application's components.

Origins

Dustin Myers and Nathan Thomas wrote the Conflux patterns contained in this repository while searching for a better alternative to current state management libraries and frameworks. Too many of the current options are either boilerplate-heavy or unnecessarily complicated. The goal was to produce modularity in component tree branches' state in a really easy manner. This was achieved by using the Context API and React Hooks, providing modular state with minimal code patterns.

Learn Conflux

A Brief Overview

You create as many instances of StateProvider as you would like for modularized state management, and the beauty of Conflux is that you can nest them in any manner you choose.

/**
 * While intimidating at first, the process of implementing Conflux is actually really straightforward.
 * In order to use Conflux in our application, we must first import StateProvider and the useStateValue hook.
 */

import { StateProvider, useStateValue } from 'react-conflux';

/**
 * The next step to using Conflux in our application is placing the StateProvider component in our
 * application.
 *
 * The following example demonstrates how you might go about wrapping the State Provider around
 * a part of your component tree.
 */

export const App = () => {
  return (
    <StateProvider reducer={reducer} stateContext={exampleContext}>
      <ChildrenComponents />
    </StateProvider>
  );
};

/**
 * The two parameters required by the StateProvider component are a reducer function and a
 * stateContext object.
 *
 * Reducers are pure functions that must take in some state and an action while returning state.
 *
 * Note that the first parameter of the reducer function, state, has a default value of initialState,
 * the beginning state of our reducer. The second parameter, the action, is an object sent into
 * our reducer from our dispatch function which we will see in just a minute.
 *
 * Here is an example of a reducer and its corresponding switch statement; in this
 * example, we're taking in a new to-do item and setting it to state.
 */

const toDoReducer = (state = initialState, action) => {
  switch (action.type) {
    case 'ADD_TODO':
      return {
        ...state,
        toDoItems: [...state.toDoItems, action.payload]
      };
    default:
      return state;
  }
};

/**
 * The initialState object contains the starting state necessary for the given StateProvider it's
 * being passed into.
 *
 * An example of this for demonstration purposes is below.
 */

const initialState = {
  inputText: '',
  listArray: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
  nameObject: { firstName: 'Marty', lastName: 'McFly' },
  toDoItems: [
    { id: 1, name: 'Meddle with the future' },
    { id: 2, name: 'Check out the past' }
  ]
};

/**
 * The stateContext object is created in your application by importing createContext from React and
 * defining your state like the example below. This context object is passed into the StateProvider
 * (and, later, your useStateValue hook).
 */

const exampleContext = createContext();

/**
 * Every action object must have a type and payload; the type allows us to navigate the cases
 * in our reducer switch statements, and the payload is the state which we will update in our
 * reducer.
 *
 * Here's an example of what an action object looks like.
 */

const action = {
  type: 'ADD_TODO',
  payload: { id: 3, name: 'Marty, we have to go back!' }
};

/**
 * The last step to using Conflux is to rig it up in your components within the component tree
 * housed in the relevant StateProvider.
 *
 * You can destructure out your state and dispatch by passing the context object created above into
 * the useStateValue hook which is imported from Conflux You can then further destructure out your
 * individual state values to assign throughout your component.
 *
 * Additionally, the dispatch function can be invoked with an action object inside of it to send
 * state to our reducer (and ultimately to be placed into our StateProvider's state).
 */

const [state, dispatch] = useStateValue(ExampleContext);

const { inputText } = state;

dispatch({
  type: 'ADD_TODO',
  payload: { id: 3, name: 'Marty, we have to go back!' }
});

Example Applications

We try, whenever possible, to give you a corresponding CodeSandbox for every sample so that you can play with the code online.

Installation

To install the most recent stable version:

npm install react-conflux

or

yarn add react-conflux

At this time, no other dependencies are required for Conflux outside of running it within a React environment.

Contributing and Getting Involved

If you spot a bug or would like to request a feature, we welcome and are grateful for any contributions from the community. Please review the process for contributing to this project by reading the contribution guidelines.

Logo

Please read the logo guidelines on use and copyright as well as find official PNG files on GitHub.

Authors

License

MIT

Acknowledgements

  • Redux - A phenomenal application of state management that paved the way for some of the patterns used in this library

About

No description, website, or topics provided.

Resources

License

MIT, Unknown licenses found

Licenses found

MIT
LICENSE.md
Unknown
LICENSE-logo.md

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published