From 2e0dbbb6bbc50f7af51c40f860b039a7ba787716 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Ma=C5=82kowski?= Date: Thu, 26 Nov 2020 12:48:01 +0100 Subject: [PATCH] chore: add README & LICENSE (#281) * chore: add README & LICENSE As per title, adding initial README file & LICENSE. It will need some work for sure, I've left the missing links as TODO * chore: more badges * chore: apply suggestions from code review Co-authored-by: Burkhard Reffeling * Update LICENSE.md Co-authored-by: Burkhard Reffeling --- LICENSE.md | 21 ++++++++++++ README.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 LICENSE.md create mode 100644 README.md diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..389bcc34 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2016 Burkhard Reffeling + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 00000000..2bfc5ff3 --- /dev/null +++ b/README.md @@ -0,0 +1,93 @@ +🚧 THIS IS **ALPHA** version of the library - the API still might change 🚧 + +# electron-redux + +Electron-Redux is an Redux Store Enhancer that helps you loosely synchronize the redux stores in multiple electron processes. + +When working with Electron, using Redux poses couple of problems, since main and renderer processes are isolated and IPC is a single way of communication between them. This library, enables you to register all your Redux stores in the main & renderer process, and enable cross-process action dispatching & _loose_ store synchronization. + +![GitHub Workflow Status](https://img.shields.io/github/workflow/status/klarna/electron-redux/Release) +![npm (tag)](https://img.shields.io/npm/v/electron-redux/alpha) +![npm](https://img.shields.io/npm/dm/electron-redux) +![npm bundle size (version)](https://img.shields.io/bundlephobia/minzip/electron-redux/alpha) +[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) +[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) + +## Installation + +```sh +# with yarn +yarn add electron-redux@alpha + +# with npm +npm install electron-redux@alpha +``` + +For more details, please see [the Installation docs page](#todo). + +## Documentation + +electron-redux docs are located at **electron-redux.js.org**. You can find there: + +- [Getting started](#todo) +- [Recipes](#todo) +- [API Reference](#todo) + +## Quick start + +electron-redux comes as a [Redux StoreEnhancer](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer). To initialize your stores, you just need to decorate them in the `main` and `renderer` processes of electron with their respective enhancers: + +```ts +// main.ts +import { mainStateSyncEnhancer } from 'electron-redux' + +const store = createStore(reducer, mainStateSyncEnhancer()) +``` + +```ts +// renderer.ts +import { rendererStateSyncEnhancer } from 'electron-redux' + +const store = createStore(reducer, rendererStateSyncEnhancer()) +``` + +That's it! + +You are now ready to fire actions from any of your processes, and depending on the [scope](#scoped-actions) the main store will broadcast them across your application. + +Please check out the [docs](#todo) for more recipes and examples! + +## Actions + +Actions fired **MUST be [FSA](https://github.com/acdlite/flux-standard-action#example)-compliant**, i.e. have a `type` and `payload` property. Any actions not passing this test will be ignored and simply passed through to the next middleware. + +> Nota bene, `redux-thunk` is not FSA-compliant out of the box, but can still produce compatible actions once the async action fires. + +Furthermore, actions (and that includes payloads) **MUST be serializable**. + +> You can extend default JSON serialization used, by [providing your own serialization/deserialization functions](#todo). + +### Scoped actions + +By default, all actions are broadcast to all registered stores. However, some state should only live in the renderer (e.g. `isPanelOpen`). electron-redux introduces the concept of action scopes. + +To stop an action from propagating from renderer to main store, simply set the scope to local by decorating your action with `stopForwarding` function. Read more about it in the [docs](#todo) + +### Blacklisted actions + +By default, some of the actions are blacklisted from broadcasting / propagating, those include actions starting with `@@` and `redux-form`. The list of ignored actions can be modified with [options](#todo). + +## Changelog + +This project adheres to [Semantic Versioning](http://semver.org/). +Every release, along with the migration instructions, is documented on the GitHub [Releases](https://github.com/klarna/electron-redux/releases) page. + +## Contributing + +Contributions via [issues](https://github.com/klarna/electron-redux/issues/new) or [pull requests](https://github.com/klarna/electron-redux/compare) are hugely welcome! Remember to read our [contributing guidelines](.github/CONTRIBUTING.md) to get started! + +By contributing to electron-redux, you agree to abide by [the code of conduct](.github/CODE_OF_CONDUCT.md). + +## License + +[MIT](LICENSE.md)