Skip to content

hosseinmd/react-principal

Repository files navigation

NPM

install size dependencies

Table of Contents
  1. About React Principal
  2. Getting Started
  3. Usage
  4. API
  5. Utils
  6. Examples
  7. Contributing
  8. Contact
  9. Acknowledgements

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

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