{"id":15700443,"url":"https://github.com/perry-mitchell/redux-browser-extension-sync","last_synced_at":"2025-05-12T13:13:33.251Z","repository":{"id":51259716,"uuid":"147225004","full_name":"perry-mitchell/redux-browser-extension-sync","owner":"perry-mitchell","description":"Sync Redux state between browser extension components","archived":false,"fork":false,"pushed_at":"2024-06-11T09:54:22.000Z","size":173,"stargazers_count":6,"open_issues_count":4,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-12T13:13:18.583Z","etag":null,"topics":["browser-extension","redux","redux-middleware","state-synchronization"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/perry-mitchell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-09-03T15:45:44.000Z","updated_at":"2023-04-08T10:15:22.000Z","dependencies_parsed_at":"2025-04-23T06:40:50.289Z","dependency_job_id":null,"html_url":"https://github.com/perry-mitchell/redux-browser-extension-sync","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fredux-browser-extension-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fredux-browser-extension-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fredux-browser-extension-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perry-mitchell%2Fredux-browser-extension-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perry-mitchell","download_url":"https://codeload.github.com/perry-mitchell/redux-browser-extension-sync/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745195,"owners_count":21957319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser-extension","redux","redux-middleware","state-synchronization"],"created_at":"2024-10-03T19:48:44.088Z","updated_at":"2025-05-12T13:13:33.199Z","avatar_url":"https://github.com/perry-mitchell.png","language":"JavaScript","funding_links":[],"categories":["Marks"],"sub_categories":["[React - A JavaScript library for building user interfaces](http://facebook.github.io/react)"],"readme":"# Redux Browser-Extension Sync\n\u003e Sync Redux state between browser extension components\n\n[![Build Status](https://travis-ci.org/perry-mitchell/redux-browser-extension-sync.svg?branch=master)](https://travis-ci.org/perry-mitchell/redux-browser-extension-sync) [![npm version](https://badge.fury.io/js/redux-browser-extension-sync.svg)](https://www.npmjs.com/package/redux-browser-extension-sync)\n\n## Installation\nInstall by simply executing the following:\n\n```shell\nnpm install redux-browser-extension-sync --save-dev\n```\n\n## About\nThis library provides a simple toolkit to perform state-sync between different parts of the browser:\n\n * Background\n * Extension pages\n * Popup\n\nIt 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:\n\n * Chrome\n * Firefox\n * Opera\n * Edge ¹\n \n ¹ 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).\n\n## Usage\nTo sync state between your stores in different parts of your application/extension, you should first initialise the **background** store with the required middleware:\n\n```javascript\nimport { applyMiddleware, createStore } from \"redux\";\nimport { createSyncMiddleware, syncStore } from \"redux-browser-extension-sync/background\";\nimport rootReducer from \"../reducers/index.js\";\n\nconst syncMiddleware = createSyncMiddleware();\n\nconst store = syncStore(createStore(\n    rootReducer,\n    applyMiddleware(syncMiddleware)\n));\n```\n\nThe synchronisation is performed by connecting to the store in 2 phases:\n\n * `createSyncMiddleware` - Middleware that watches for dispatched actions on the store, and transmits these to other tabs\n * `syncStore` - Store enhancement to dispatch received actions on the store\n\nWhen the background script initialises, the store and its sync enhancements will be ready and waiting for tabs or popups to connect.\n\nTo 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:\n\n```javascript\nimport { combineReducers } from \"redux\";\nimport { createSyncReducer } from \"redux-browser-extension-sync\";\nimport notes from \"./notes.js\";\nimport searchResults from \"./searchResults.js\";\n\nconst appReducer = combineReducers({\n    notes,\n    searchResults\n});\n\nexport default createSyncReducer(appReducer);\n```\n\nOnce this reducer is set-up, similar store connections as with the background store can be made:\n\n```javascript\nimport { applyMiddleware, createStore } from \"redux\";\nimport { createSyncMiddleware, syncStore } from \"redux-browser-extension-sync\";\nimport rootReducer from \"../reducers/index.js\";\n\nconst syncMiddleware = createSyncMiddleware();\n\nconst store = syncStore(createStore(\n    rootReducer,\n    applyMiddleware(syncMiddleware)\n));\n```\n\nThat'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).\n\n**Disclaimer**: It is not recommended to store sensitive information in any store synchronised using this library.\n\n### Extension requirements\nThe 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.\n\nIt 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.\n\n### Manifest requirements\nCertain 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.\n\n### State requirements\nYou 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.\n\n## Motivation\nThe [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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fredux-browser-extension-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperry-mitchell%2Fredux-browser-extension-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperry-mitchell%2Fredux-browser-extension-sync/lists"}