\n \n\n\n\n\n# About React Principal\n\nReact Principal is a state-management package based on react-context which introduces several hooks to do so.\nActually, react-principal is a wrapper for react context with better developer experience.\nHigh performance since provided observed connect to context.\nIt's useful for global state management and complex component state.\n\nReact-Principal internally used React.reducer for state.\n\n### Pros\n\nWhy should you use react-principal?\nBecause react-principal is:\n\n- Ability to persist data using local storage and session\n- Ability to create multiple providers for any component\n- Pass data easily between various pages and tabs\n- Applicable in both global and component-based levels\n- Automatic store generation (CLI)\n- TypeSafe\n- High Performance\n- User Friendly\n- Minimum Complexity\n\n### Built With\n\n- [React](https://react.com)\n\n\n\n## Getting Started\n\nAll you need as a requirement for this package is to have a project created by react.\n\n### Installation\n\nTo add react-principal to your project, simply install it using npm or yarn:\n\n- npm\n\n ```sh\n npm install react-principal\n ```\n\n- yarn\n ```sh\n yarn add react-principal\n ```\n\n## Usage\n\nBefore anything, you should be familiar with react reducer pattern.\n\n```js\nimport { createStore, Provider } from \"react-principal\";\n\nconst store = createStore({ reducer, initialState });\n\nfunction Component() {\n const { foo, bar } = store.useState();\n const dispatch = store.useDispatch();\n\n return (\n <>\n
\n {foo} {bar}\n
\n dispatch({ type: \"SET_FOO\", payload: { foo: \"foo\" } }, callback)\n // callback will call after state set\n }\n >\n Set foo\n \n \n );\n}\n\n// The provider can be wrapped on any desired component, where you want to generate a store.\nfunction App() {\n \n \n ;\n}\n```\n\n### Performance\n\n```js\n//Define states which you want to update when they changed. If is not defined store listen to whole states change\nconst { foo, bar } = store.useState([\"foo\", \"bar\"]);\n\n// Dispatch is devided from state for performance enhancement, because dispatch functions never change.\nconst dispatch = store.useDispatch();\n```\n\n### persist\n\n```js\nconst store = createStore({\n reducer,\n initialState,\n // config a persister\n // window.localStorage, window.sessionStorage, AsyncStorage supported\n storage: window.localStorage,\n persistKey: \"UniqKey\",\n mapStateToPersist: ({ todos }) => ({\n todos, // persist just todos\n }),\n});\n\nexport default () => {\n // you can save ref in global place for access to state and dispatch out of children components like `store.state`\n // Doesn't need middleWare like redux, storeRef working vary well\n\n useEffect(() => {\n store.setToState();\n }, []);\n\n return (\n \n \n \n );\n};\n```\n\n### ProvidersList\n\nThis component is for organization of multiple providers. Simply give the 'providers' prop, an array of your providers.\n\n```js\nfunction App() {\n return (\n \n {appContainer}\n \n );\n}\n```\n\n### Generator\n\nReact-principal has a command for auto generating store.\n\n`$ generate-store `\n\n Options\n --type= Default value is set on 'global', 'single' option will create store in a single file, reducer is using with useReducer,\n\n##### Example:\n\n`$ generate-store ./src/store`\n\n Generate a sample store into src/store\n\n`$ generate-store ./src/myComponent --type=reducer`\n\n Generate a sample reducer action for using in useReducer into src/myComponent\n\n## API\n\n| Name | Requirement | Type | Description |\n| ----------------- | :---------: | :----------------------------------------: | :-------------------------------------------------------------------------------: |\n| reducer | required | function | Pass your reducer function which is created via 'createReducer'. |\n| initialState | required | object | Here you can set the initial values that are going to be saved inside store. |\n| storage | optional | localStorage, sessionStorage, AsyncStorage | Choose from window.localStorage, window.sessionStorage, or AsyncStorage. |\n| persistKey | optional | string | To set a specific key to save data in the desired storage. |\n| mapStateToPersist | optional | function | A function which gets 'state' as an argument and saves it in the desired storage. |\n\n## Utils\n\n[Utils Readme.md](UtilsReadme.md).\n\n## Examples\n\nVisit 'examples' folder for a better understanding of react-principal usage.\nAlso, if you need to have a quick setup of this package on your project, you can check 'templates' folder.\n\nA simple [Todo list App](https://github.com/hosseinmd/react-principal/blob/master/examples/web/src/app.js)\n\n\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Add tests if necessary and run tests (`yarn test`)\n6. Open a Pull Request\n\n\n\n## Contact\n\nHossein Mohammadi: hosseinm.developer@gmail.com\n\nProject Link: [https://github.com/hosseinmd/react-principal](https://github.com/hosseinmd/react-principal)\n\n\n\n## Acknowledgements\n\n- [redux](https://redux.js.org/)\n- [react-context](https://reactjs.org/docs/context.html)\n","readmeFilename":"readme.md"}