react-rebase

What is this?

Re-base is a great Firebase library that makes it easy to use Firebase with react components by binding the Firebase data with the component's state. react-rebase is a wrapper of re-base that provides an ability to bind the data to props instead!

Note that this library totally depends on Re-base library to do everything! Some level of knowledge of re-base API is needed, at least checkout post and bindToState function.

Also, it's incredibly IMMATURE and somewhat a work in progress that I barely touch anymore. Use it at your own risk!

Why react-rebase?

Since Re-base binds Firebase data to state, we are basically forced to have a stateful component connect to it. However, this is an era of stateless functional component. To have an otherwise-stateless component become stateful just to connect with Firebase could leave some bad taste in the mouths of stateless functional component lovers like me. Obviously one could separate the firebase-connected component to a container component solely for providing Firebase data and callback functions to update state (which interns update those data). However, this approach doesn't scale very well since there will be a need to pass those data and callback functions around a lot. It's a similar problem you will likely face if you try to use redux without react-redux library.

All things considered, since there is no such convenient library that would simply bind Firebase reference to props, I created react-rebase to do just that. react-rebase will abstract the state binding to a higher order component and provide the data to props directly.

Installation

To install, simply do npm install --save react-rebase or yarn add react-rebase

Usage

rebaseConnect(mapRefDataToProps, mapBaseActionsToProps)(Component);

where mapRefDataToProps is a function that takes in props and returns a props object made from the ref data that is bound to the HoC state, and mapBaseActionsToProps is a function that takes in Re-base object and props then returns a props object made from mapBaseActionsToProps. The details on how these parameters look like are below.

Note: The API is heavily inspired by react-redux.

Example

Let's say we are working on a counter component, probably something like this:

// Counter.jsx
const Counter = ({ count, updateCount }) => (
  <div>
    Current value: {count}
    <button onClick={() => updateCount(count+1)}>Add</button>
  </div>  
);

Now we want to connect it to Firebase for real-time capabilities. First we will need to instantiate the Re-base and pass it to the top level RebaseProvider. Like this:

// App.jsx
import Rebase from "re-base";
import { RebaseProvider } from "react-rebase";
import Counter from './Counter.jsx'

const base = Rebase.createClass({
  ...
});

const App = () => (
  <RebaseProvider instance={base}>
    <Counter /> 
  </RebaseProvider>
)

Now that we provided RebaseProvider with the re-base instance, let's make some change to our Counter.jsx so it can connect to Firebase. For this example we will assume that the data lives at '/count' endpoint

// Counter.jsx
import { rebaseConnect } from 'react-rebase';

const Counter = ({ count, updateCount }) => (
  <div>
    Current value: {count}
    <button onClick={() => updateCount(count+1)}>Add</button>
  </div>  
);

const COUNT_PATH = '/count';

export default rebaseConnect(
  (props) => ({
    count: { path: COUNT_PATH }, // this becomes a `count` prop
  }),
  (base) => ({
    updateCount: (newValue) => base.post(COUNT_PATH, newValue), // this becomes an `updateCount` prop
  })
)(Counter);

And that's it! Now our counter will be connected to Firebase.

Documentation (WIP)

rebaseConnect(mapRefDataToProps, mapBaseActionsToProps)

Connect the component with the props constructed from Firebase data and re-base actions. The user needs to provide two functions:

1. mapRefDataToProps(props) This function should return an object where the key is the prop name and the value is an object containing Firebase path and options specified there.

Example:

const mapRefDataToProps = (props) => ({ 
  items: { 
    path: 'path/to/items', 
    options: { asArray: true },  // optional
  }
});

2. mapBaseActionsToProps(base, [props]) This function should return an object where the key is the prop name and the value is a function that potentially mutates the data on firebase.

Example:

const mapBaseActionsToProps = (base, props) => ({ 
  addItems: (id, newItem) => base.post(`path/to/items/${id}`, newItem)
});