Table of Contents
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.
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
All you need as a requirement for this package is to have a project created by react.
To add react-principal to your project, simply install it using npm or yarn:
-
npm
npm install react-principal
-
yarn
yarn add react-principal
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>;
}//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();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>
);
};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>
);
}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,
$ 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
| 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. |
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
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Add tests if necessary and run tests (
yarn test) - Open a Pull Request
Hossein Mohammadi: [email protected]
Project Link: https://github.com/hosseinmd/react-principal