About React Principal

React Principal is a state-management package based on react-context which introduces several hooks to do so. Actually, react-principal is a wrapper for react context with better developer experience. High performance since provided observed connect to context. It's useful for global state management and complex component state.

React-Principal internally used React.reducer for state.

Pros

Why should you use react-principal? Because react-principal is:

• Ability to persist data using local storage and session
• Ability to create multiple providers for any component
• Pass data easily between various pages and tabs
• Applicable in both global and component-based levels
• Automatic store generation (CLI)
• TypeSafe
• High Performance
• User Friendly
• Minimum Complexity

Built With

• React

Getting Started

All you need as a requirement for this package is to have a project created by react.

Installation

To add react-principal to your project, simply install it using npm or yarn:

• npm

  npm install react-principal

• yarn

  yarn add react-principal

Usage

Before anything, you should be familiar with react reducer pattern.

import { createStore, Provider } from "react-principal";

const store = createStore({ reducer, initialState });

function Component() {
  const { foo, bar } = store.useState();
  const dispatch = store.useDispatch();

  return (
    <>
      <p>
        {foo} {bar}
      </p>
      <button
        onclick={
          () => dispatch({ type: "SET_FOO", payload: { foo: "foo" } }, callback)
          // callback will call after state set
        }
      >
        Set foo
      </button>
    </>
  );
}

// The provider can be wrapped on any desired component, where you want to generate a store.
function App() {
  <Provider store={store}>
    <Component />
  </Provider>;
}

Performance

//Define states which you want to update when they changed. If is not defined store listen to whole states change
const { foo, bar } = store.useState(["foo", "bar"]);

// Dispatch is devided from state for performance enhancement, because dispatch functions never change.
const dispatch = store.useDispatch();

persist

const store = createStore({
  reducer,
  initialState,
  // config a persister
  // window.localStorage, window.sessionStorage, AsyncStorage supported
  storage: window.localStorage,
  persistKey: "UniqKey",
  mapStateToPersist: ({ todos }) => ({
    todos, // persist just todos
  }),
});

export default () => {
  // you can save ref in global place for access to state and dispatch out of children components like `store.state`
  // Doesn't need middleWare like redux, storeRef working vary well

  useEffect(() => {
    store.setToState();
  }, []);

  return (
    <Provider store={store}>
      <App />
    </Provider>
  );
};

ProvidersList

This component is for organization of multiple providers. Simply give the 'providers' prop, an array of your providers.

function App() {
  return (
    <ProvidersList providers={[Provider1, Provider2, Provider3]}>
      {appContainer}
    </ProvidersList>
  );
}

Generator

React-principal has a command for auto generating store.

$ generate-store <destination>

Options
--type=<reducer | single | global>   Default value is set on 'global', 'single' option will create store in a single file, reducer is using with useReducer,

Example:

$ generate-store ./src/store

 Generate a sample store into src/store

$ generate-store ./src/myComponent --type=reducer

Generate a sample reducer action for using in useReducer into src/myComponent

API

| Name | Requirement | Type | Description | | ----------------- | :---------: | :----------------------------------------: | :-------------------------------------------------------------------------------: | | reducer | required | function | Pass your reducer function which is created via 'createReducer'. | | initialState | required | object | Here you can set the initial values that are going to be saved inside store. | | storage | optional | localStorage, sessionStorage, AsyncStorage | Choose from window.localStorage, window.sessionStorage, or AsyncStorage. | | persistKey | optional | string | To set a specific key to save data in the desired storage. | | mapStateToPersist | optional | function | A function which gets 'state' as an argument and saves it in the desired storage. |

Utils

Utils Readme.md.

Examples

Visit 'examples' folder for a better understanding of react-principal usage. Also, if you need to have a quick setup of this package on your project, you can check 'templates' folder.

A simple Todo list App

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Add tests if necessary and run tests (yarn test)
6. Open a Pull Request

Contact

Hossein Mohammadi: [email protected]

Project Link: https://github.com/hosseinmd/react-principal

Acknowledgements

• redux
• react-context