redux-replica

• redux-replica
  • Definitions
    • Electron
    • Chrome
  • Motivation
    • The solution
  • Install
  • Usage Example
  • Actions
    • Local actions (renderer process)
    • Aliased actions (main process)
    • Blacklisted actions
  • Contributions
  • Contributors

Definitions

Electron

In Electron, the process that runs package.json's main script is called the main process. The script that runs in the main process can display a GUI by creating web pages. An Electron app always has one main process, but never more.

Since Electron uses Chromium for displaying web pages, Chromium's multi-process architecture is also used. Each web page in Electron runs in its own process, which is called the renderer process. Electron Docs.

Chrome Extension

The background script is the extension's event handler; it contains listeners for browser events that are important to the extension. Extension UI pages, such as a popup, can contain ordinary HTML pages with JavaScript logic. Extensions that read or write to web pages utilize a content script. The content script contains JavaScript that executes in the contexts of a page that has been loaded into the browser. Content scripts read and modify the DOM of web pages the browser visits. Developer Chrome

Motivation

Using redux with electron poses a couple of problems. Processes (main and renderer) are completely isolated, and the only mode of communication is IPC.

• Where do you keep the state?
• How do you keep the state in sync across processes?

The solution

redux-replica offers an easy to use solution. The redux store on the master process becomes the single source of truth, and stores in the slave processes become mere proxies. You MUST use equal reducers for all processes.

Electron:

• Master: Main Process
• Slave: Each Renderer Process

Chrome Extension:

• Master: Background Script
• Slave: Popup and each Content Script

Install

$ npm install --save redux-replica

or

$ yarn add redux-replica

Usage Example

redux-replica comes as redux middleware that is really easy to apply:

// in the master store
import { forwardToRenderer, triggerAlias, replayActionMain } from 'redux-replica'

const todoApp = combineReducers(reducers)

const store = createStore(
  todoApp,
  initialState, // optional
  applyMiddleware(
    triggerAlias, // optional, see below
    ...otherMiddleware,
    forwardToRenderer, // IMPORTANT! This goes last
  ),
)

replayActionMain(store)

// in the slave store
import { forwardToMain, replayActionRenderer, getInitialStateRenderer } from 'redux-replica'

const todoApp = combineReducers(reducers)

getInitialStateRenderer().then((initialState) => {
  const store = createStore(
    todoApp,
    initialState,
    applyMiddleware(
      forwardToMain, // IMPORTANT! This goes first
      ...otherMiddleware,
    ),
  )

  replayActionRenderer(store)
})

And that's it! You are now ready to fire actions without having to worry about synchronising your state between processes.

Actions

Actions fired MUST be FSA-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.

NB: 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 (de-)serialisable, i.e. either POJOs (simple objects - that excludes native JavaScript or DOM objects like FileList, Map, etc.), arrays, or primitives. For workarounds, check out aliased actions

Local actions (renderer process)

By default, all actions are being broadcast from the main store to the renderer processes. However, some state should only live in the renderer (e.g. isPanelOpen). redux-replica introduces the concept of action scopes.

To stop an action from propagating from renderer to main store, simply set the scope to local:

function myLocalActionCreator() {
  return {
    type: 'MY_ACTION',
    payload: 123,
    meta: {
      scope: 'local',
    },
  }
}

Aliased actions (main process)

Most actions will originate from the renderer side, but not all should be executed there as well. A great example is fetching of data from an external source, e.g. using promise middleware, which should only ever be executed once (i.e. in the main process). This can be achieved using the triggerAlias middleware mentioned above.

Using the createAliasedAction helper, you can quite easily create actions that are are only being executed in the main process, and the result of which is being broadcast to the renderer processes.

import { createAliasedAction } from 'redux-replica'

export const importGithubProjects = createAliasedAction(
  'IMPORT_GITHUB_PROJECTS', // unique identifier
  (accessToken, repoFullName) => ({
    type: 'IMPORT_GITHUB_PROJECTS',
    payload: importProjects(accessToken, repoFullName),
  }),
)

Blacklisted actions

By default actions of certain type (e.g. starting with '@@') are not propagated to the main thread. You can change this behaviour by using forwardToMainWithParams function.

// in the renderer store
import { forwardToMainWithParams, replayActionRenderer, getInitialStateRenderer } from 'redux-replica'

const todoApp = combineReducers(reducers)
const initialState = getInitialStateRenderer()

const store = createStore(
  todoApp,
  initialState,
  applyMiddleware(
    forwardToMainWithParams(), // IMPORTANT! This goes first
    ...otherMiddleware,
  ),
)

replayActionRenderer(store)

You can specify patterns for actions that should not be propagated to the main thread.

forwardToMainWithParams({
  blacklist: [/^@@/, /^redux-form/],
})

Contributions

Contributions via issues or pull requests are hugely welcome!

Feel free to let me know whether you're successfully using redux-replica in your project and I'm happy to add them here as well!