Skip to content
No description, website, or topics provided.
JavaScript
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist Remove additional conflux logging after initialization of state Jun 23, 2019
examples
logo Update image pathing to be URLs May 22, 2019
src Remove additional conflux logging after initialization of state Jun 23, 2019
test Implement initial grouped state object to mask @conflux repeated logging Jun 23, 2019
.babelrc Remove modules: false May 22, 2019
.eslintignore
.eslintrc.js Update ESLint with import/babel plugins and fix default exports May 21, 2019
.gitignore
.prettierrc.json Update with prettier settings May 15, 2019
CHANGELOG.md Include Rollup ReactDOM import and rollup-plugin-node-resolve May 15, 2019
CODE_OF_CONDUCT.md Upgrade README with examples and add code of conduct with contributio… May 18, 2019
CONTRIBUTING.md Fix contributing markdown file error May 23, 2019
LICENSE-logo.md Add LICENSE-logo.md and update README May 23, 2019
LICENSE.md Add LICENSE-logo.md and update README May 23, 2019
README.md Update and tweak README.md to flow better Jun 4, 2019
index.js
jest.config.js
package-lock.json Implement singleton useInitialState hook on app/Conflux load May 29, 2019
package.json
rollup.config.js

README.md

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
You can’t perform that action at this time.