ivantsov/redux-webext

Redux for WebExtensions

redux-webext

This package allows you to use Redux for managing the state of your WebExtension.

Installation

npm install redux-webext --save

Introduction

Usually WebExtension consists of two basic parts:

• background page, where you store the data and process it somehow
• UI pages (e.g. popup or content scripts), where you show the data from background page

As you can see, to provide data between background and UI pages you have to use messages. Or... actually, you don't have to, because of redux-webext:

In a nutshell, redux-webext takes care of communication between background and UI pages using Redux. But there are 2 key things that you should understand:

• In background page there is Redux store that contains the entire state of your WebExtension. All logic (actions, reducers etc) is placed in background page as well.
• UI pages have access to the state via their own Redux stores, but there are no real actions or reducers. I said real because UI pages might have functions associated with actions in background page. You can think about it like a proxy that allows you to call background actions from UI pages.

The words above don't make a lot of sense without code, right? So, there's tutorial with example where you can find how to use redux-webext and how it works.

Examples

• https://github.com/ivantsov/redux-webext/tree/master/examples - simple example with tutorial
• https://github.com/ivantsov/yandex-mail-notifier-chrome - real extension that uses redux-webext
• https://github.com/armateam/extension - a real and simple extension that uses redux-webext

API

createBackgroundStore(options) - creates Redux store for background page.

Options

• store - instance of Redux store.
• actions (optional) - object which keys are types of actions in UI page and values are actions in background page.
• onDisconnect (optional) - function that will be called on destroying UI store (e.g. right after closing a popup).

Returns the provided store.

Example

const store = createStore(reducer); // real Redux store

const backgroundStore = createBackgroundStore({
    store,
    actions: {
        // "INCREMENT_UI_COUNTER" is a string that will be used as a type of action in UI page
        // "incrementUICounter" is an action is background page
        INCREMENT_UI_COUNTER: incrementUICounter,
        DECREMENT_UI_COUNTER: decrementUICounter
    }
});

createUIStore() - creates Redux store for UI pages.

Returns promise which will be resolved after receiving the current state of background store. And an object with identical to Redux store structure will be passed as resolved result.

Example

async function initApp() {
    const store = await createUIStore();

    ReactDOM.render(
        <Provider store={store}>
            <App/>
        </Provider>,
        document.getElementById('app')
    );
}

initApp();