README.md

Homebase React

The React state management library for write-heavy applications

Supported languages, frameworks and DBs:

• JS + React + Datascript (jump)
• CLJS + Reagent + Datascript (jump)
• Datahike support coming soon

What and Why

As data and our need to annotate and organize it grows, so does our need for supporting state in write-heavy applications.

To solve this problem, modern write-heavy applications such as Superhuman, Roam Research, and Facebook Messenger built their own embedded data layers to enable these more sophisticated user experiences.

Homebase-react enables developers to access the same embedded datalog database as Roam Research through React hooks. You no longer have to build out a team or learn specialized tools like Clojure in order to build a delightful write-heavy application.

Testimonials

Homebase is executing on the vision of data usage, portability, and management we had when building Firebase. We never got there. I'm excited!

—James Tamplin, Founder/CEO of Firebase

Datalog is the future of end-user programming, personal productivity software, p2p software, etc.

—Chet Corcos, Founding Engineer of Notion

Javascript + React

Start by installing homebase-react.

# NPM
npm install homebase-react --save

# Yarn
yarn add homebase-react

Optionally install the datalog-console chrome extension to inspect the homebase-react DB in your browser.

⭐️ 📖 Read the JS docs ⚛️ ⭐️

import { useCallback } from 'react'
import { HomebaseProvider, useEntity, useTransact } from 'homebase-react'

const RootComponent = () => (
  // Create a DB and set some starting data
  <HomebaseProvider config={{ initialData: [{ counter: { id: 1, count: 0 }}] }}>
    <App/>
  </HomebaseProvider>
)

const App = () => {
  // Get entity id = 1
  const [counter] = useEntity(1)
  const [transact] = useTransact()

  return (
    <button onClick={() => {
      // Increment and save the count
      transact([{ counter: { 
        id: 1, count: counter.get('count') + 1 
      }}])
    }>
      {/* Render the count */}
      Increment {counter.get('count')}
    </button>
  )
}

Live demo

ClojureScript + Reagent

Start by adding homebase-react.

Optionally add datalog-console and its corresponding chrome extension to inspect the DB in your browser.

⭐️ 📖 Read the CLJS docs ƛ ⭐️

(ns homebase.dev.example.reagent.counter
  (:require
   [datascript.core :as d]
   [homebase.reagent :as hbr]
   [datalog-console.integrations.datascript :as datalog-console]))

(def db-conn (d/create-conn {}))
(d/transact! db-conn [[:db/add 1 :count 0]]) ; Transact some starting data.
(hbr/connect! db-conn) ; Connect homebase.reagent to the database.
(datalog-console/enable! {:conn db-conn}) ; Also connect the datalog-console extension for better debugging.

(defn counter []
  (let [[entity] (hbr/entity db-conn 1)] ; Get a homebase.reagent/Entity. Note the use of db-conn and not @db-conn, this makes it reactive.
    (fn []
      [:div
       "Count: " (:count @entity) ; Deref the entity just like a reagent/atom.
       [:div
        [:button {:on-click #(d/transact! db-conn [[:db/add 1 :count (inc (:count @entity))]])} ; Use d/transact! just like normal.
         "Increment"]]])))

Live demo

Roadmap

1. Improve developer tools: custom chrome formatters, DB admin console extension
2. Rewrite React ↔ Homebase cache
   1. Support async DB access (for Datahike)
   2. Reactive query planning (better perf on pages with lots of live reads)
3. Swap Datascript out for Datahike
   1. Immutability
   2. History / Change Tracking
4. Persist to IndexedDB
5. Local-first conflict resolution for offline caching and sync between multiple devices

Limitations

Homebase React is currently not a good choice for read-heavy applications (e.g. Twitter, ecommerce). We plan to support these query patterns with our platform eventually.

Alternatives

There isn't much in the way of React friendly datalog DB based state management for Javascript, but there's at least one alternative if you're a Clojure dev.

• If you prefer d/pull over d/entity take a look at Posh. It supports less of the d/q API, but provides more tools for tuning performance.

Development

yarn install
yarn dev

Open http://localhost:3000

Test

yarn install
yarn test

Contributing

Welcome and thank you! Writing docs, patches and features are all incredibly helpful and appreciated.

We only ask that you provide test coverage for code changes, and conform to our commit guidelines.

Authors

• Chris Smothers (@csmothers) – Homebase
• JB Rubinovitz (@rubinovitz) – Homebase