README.md

@localfirst/state is an automatically replicated Redux store that gives your app offline capabilities and secure peer-to-peer synchronization superpowers.

🚧 Work in progress

Why

Distributed, offline-first technologies are promising for a lot of reasons, but they're unfamiliar to most web application developers. This library provides offline storage and peer-to-peer synchronization capabilities, and exposes them via a familiar Redux store that can be used in a vanilla JS, React, or Electron application.

🡒 Read more

What

This library provides two services:

• Data replication & synchronization, using the Automerge library
• Persistence to a local or remote data store. You can use the provided adapters for IndexedDb or MongoDb, or provide your own.

🡒 Read more

How

Example apps

Two demo React applications are included:

todo An implementation of TodoMVC To run: yarn dev:todo:start

grid A simple table editor To run: yarn dev:grid:start

Getting started

yarn add @localfirst/state

import { StoreManager } from '@localfirst/state'
import { Provider } from 'react-redux'

const storeManager = new StoreManager({
  // Pass your reducers
  proxyReducer,

  // Pass an initial state, just like you would for Redux
  initialState: {
    todoList: [],
    todoMap: {},
    filter: ALL,
  },
})

export const Index = () => {
  // Obtain a Redux store
  const store = storeManager.createStore(discoveryKey)
  return (
    // Pass the store to your app
    <Provider store={store}>
      <App />
    </Provider>
  )
}

🡒 More on how to use @localfirst/state in your app

Limitations

This library requires that the entire repository be present on each peer's machine. That means that it is limited to datasets that can fit comfortably within the disk space on a single computer. In 2019, that means something on the order of 1-10 GB.

Further reading

• CRDTs and the Quest for Distributed Consistency, a great talk by Martin Kleppman, the author of Automerge.
• Local-first software: You own your data, in spite of the cloud, a manifesto published by Ink & Switch, the industrial research lab created by Heroku alumni that is behind Automerge.
• A web application with no web server?

Alternatives

All of these projects are working in similar problem space, in JavaScript. All work in Node.js and the browser unless otherwise noted.

• Hypermerge is the semi-official networking and persistence stack for Automerge, based on the DAT project's Hypercore and created by the team at Ink and Switch. It's used in sample Automerge applications like Capstone and Farm. Node.js only.
• PouchDb Syncs with Apache CouchDb.
• Realm Database Acquired by MongoDB in 2019. Node.js only.
• HyperDB From the DAT Project. Showcased in a cool sample app by @jimpick: Dat Shopping List.
• GunDB Distributed graph database.