https://github.com/perry-mitchell/redux-browser-extension-sync
Sync Redux state between browser extension components
https://github.com/perry-mitchell/redux-browser-extension-sync
browser-extension redux redux-middleware state-synchronization
Last synced: about 1 year ago
JSON representation
Sync Redux state between browser extension components
- Host: GitHub
- URL: https://github.com/perry-mitchell/redux-browser-extension-sync
- Owner: perry-mitchell
- License: mit
- Created: 2018-09-03T15:45:44.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-06-11T09:54:22.000Z (about 2 years ago)
- Last Synced: 2025-05-12T13:13:18.583Z (about 1 year ago)
- Topics: browser-extension, redux, redux-middleware, state-synchronization
- Language: JavaScript
- Size: 169 KB
- Stars: 6
- Watchers: 3
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-redux - **redux-browser-extension-sync** - Redux state synchronization between browser extension components (background/popup etc.). Works in Chrome, Firefox and Opera.
- fucking-awesome-redux - **redux-browser-extension-sync** - Redux state synchronization between browser extension components (background/popup etc.). Works in Chrome, Firefox and Opera.
README
# Redux Browser-Extension Sync
> Sync Redux state between browser extension components
[](https://travis-ci.org/perry-mitchell/redux-browser-extension-sync) [](https://www.npmjs.com/package/redux-browser-extension-sync)
## Installation
Install by simply executing the following:
```shell
npm install redux-browser-extension-sync --save-dev
```
## About
This library provides a simple toolkit to perform state-sync between different parts of the browser:
* Background
* Extension pages
* Popup
It is not designed to work with content scripts or other areas that do not have access to `chrome.runtime.sendMessage`. This library is supported in the following browsers:
* Chrome
* Firefox
* Opera
* Edge ¹
¹ Edge support is dependent on API bridges being in place - follow the [Chrome to Edge porting instructions](https://docs.microsoft.com/en-us/microsoft-edge/extensions/guides/porting-chrome-extensions#api-bridges).
## Usage
To sync state between your stores in different parts of your application/extension, you should first initialise the **background** store with the required middleware:
```javascript
import { applyMiddleware, createStore } from "redux";
import { createSyncMiddleware, syncStore } from "redux-browser-extension-sync/background";
import rootReducer from "../reducers/index.js";
const syncMiddleware = createSyncMiddleware();
const store = syncStore(createStore(
rootReducer,
applyMiddleware(syncMiddleware)
));
```
The synchronisation is performed by connecting to the store in 2 phases:
* `createSyncMiddleware` - Middleware that watches for dispatched actions on the store, and transmits these to other tabs
* `syncStore` - Store enhancement to dispatch received actions on the store
When the background script initialises, the store and its sync enhancements will be ready and waiting for tabs or popups to connect.
To initialise the stores of popups or tabs, the same process followed, with 1 addition: a sync reducer. This reducer wraps the extension's root reducer, allowing it to set state:
```javascript
import { combineReducers } from "redux";
import { createSyncReducer } from "redux-browser-extension-sync";
import notes from "./notes.js";
import searchResults from "./searchResults.js";
const appReducer = combineReducers({
notes,
searchResults
});
export default createSyncReducer(appReducer);
```
Once this reducer is set-up, similar store connections as with the background store can be made:
```javascript
import { applyMiddleware, createStore } from "redux";
import { createSyncMiddleware, syncStore } from "redux-browser-extension-sync";
import rootReducer from "../reducers/index.js";
const syncMiddleware = createSyncMiddleware();
const store = syncStore(createStore(
rootReducer,
applyMiddleware(syncMiddleware)
));
```
That's all that's required to connect the Redux stores and their state. This library uses Chrome messaging APIs to send the state between extension components (API methods are compatible across supported browsers).
**Disclaimer**: It is not recommended to store sensitive information in any store synchronised using this library.
### Extension requirements
The extension must have a background script for this library to work. The background script, with its Redux store, is the central message bank for all state synchronisations.
It is advisable that you keep the same reducers in _each store_ (tabs, background etc.), otherwise Redux will show warnings about it not finding expected reducer keys. While this is not a show-stopper, it _is_ ugly.
### Manifest requirements
Certain manifest permissions may need to be set before this library can be used. The **tabs** permission, for one, needs to be obtained before communication within this library can take place.
### State requirements
You should be using a clean, **primitive** state structure that supports JSON-style serialisation. The state will regularly be sent between browser tabs and the background script in serialised form.
## Motivation
The [browser extension for Buttercup](https://github.com/buttercup/buttercup-browser-extension) is a complex application used for password and secrets management - it makes use of multiple Redux stores across its components, which prompted me to write a sync library to assist with this process. I intend to use it elsewhere as I like the ability to bring my full state tree with me across each extension I build.