React Chrome Redux

A set of utilities for building Redux applications in Google Chrome extensions. Although React is mentioned in the package name, this package's only requirement is Redux. Feel free to use this with AngularJS and other libraries.

Installation

This package is available on npm:

npm install react-chrome-redux

Overview

react-chrome-redux allows you to build your Chrome extension like a Redux-powered webapp. The background page holds the Redux store, while Popovers and Content-Scripts act as UI Components, passing actions and state updates between themselves and the background store. At the end of the day, you have a single source of truth (your Redux store) that describes the entire state of your extension.

All UI Components follow the same basic flow:

1. UI Component dispatches action to a Proxy Store.
2. Proxy Store passes action to background script.
3. Redux Store on the background script updates its state and sends it back to UI Component.
4. UI Component is updated with updated state.

Basic Usage (full docs here)

As described in the introduction, there are two pieces to a basic implementation of this package.

1. Add the Proxy Store to a UI Component, such as a popup

// popover.js

import React from 'react';
import {render} from 'react-dom';
import {Provider} from 'react-redux';
import {Store} from 'react-chrome-redux';

import App from './components/app/App';

const store = new Store({
  portName: 'MY_APP' // communication port name
});

// The store implements the same interface as Redux's store
// so you can use tools like `react-redux` no problem!
render(
  <Provider store={store}>
    <App/>
  </Provider>
  , document.getElementById('app'));

2. Wrap your Redux store in the background page with wrapStore()

// background.js

import {wrapStore} from 'react-chrome-redux';

const store; // a normal Redux store

wrapStore(store, {portName: 'MY_APP'}); // make sure portName matches

That's it! The dispatches called from UI component will find their way to the background page no problem. The new state from your background page will make sure to find its way back to the UI components.

3. Optional: Implement actions whose logic only happens in the background script (we call them aliases)

Sometimes you'll want to make sure the logic of your action creators happen in the background script. In this case, you will want to create an alias so that the alias is proxied from the UI component and the action creator logic executes in the background script.

// background.js

import { applyMiddleware, createStore } from 'redux';
import { alias, wrapStore } from 'react-chrome-redux';

const aliases = {
  // this key is the name of the action to proxy, the value is the action
  // creator that gets executed when the proxied action is received in the
  // background
  'user-clicked-alias': () => {
    // this call can only be made in the background script
    chrome.notifications.create(...);

  };
};

const store = createStore(rootReducer,
  applyMiddleware(
    alias(aliases)
  )
);

// content.js

import { Component } from 'react';

const store = ...; // a proxy store

class ContentApp extends Component {
  render() {
    return (
      <input type="button" onClick={ this.dispatchClickedAlias.bind(this) } />
    );
  }

  dispatchClickedAlias() {
    store.dispatch({ type: 'user-clicked-alias' });
  }
}

Docs

• Introduction
• Getting Started
• Advanced Usage
• API
  • Store
  • wrapStore
  • alias

Who's using this?

Using react-chrome-redux in your project? We'd love to hear about it! Just open an issue and let us know.