Firekit
This project was bootstrapped with nwb
Firekit helps syncing the Firebase RealtimeDatabase or the new Firestore database with the redux state.
Features
Firekit allows you to watch firebase data and sync it to your redux store with a minimum of code to write. It uses a Provider to server the firebaseApp to all Components that need it.
Some features that are unique to this firebase toolkit are:
-
persistant watchers - the watchers are persistant and are not linked to components. You deside when to watch a value in your firebase database and when to unwatch (turn off listeners) it.
-
your create firebaseApp - you initialise the firebaseApp how you want and add it as prop to the firekit
FirebaseProviderand all your components have access to the firebaseApp -
easy persistance - firekit saves in your store only simple json data so that persistance is no nightmare any more!
-
normalised redux store - the firekit reducers are structured with normalisation in mind
-
native firebase - you can use firebases native sdk for the web. Firekit is just listening on changes. Every change on the data you can make as it is described in the official firebase documentation
-
realtime forms - firekit has a special Warapper for
redux-formswitch allows to sync them with the realtime database very simple and plus it is automaticaly synced on field changes in real time if they ocure while your are in the Form
Features like populating values in the database are omited with purpose. The Firebase Cloud Functions are the place where you should populate data that must be saved in multiple places.
Install
For using only the redux features
npm i -S firekit
In a react project where you want to have also the Provider
npm i -S firekit firekit-provider
Configuration
We will use code snipets from the demo project to explan how to configure firekit. There are two main steps for the configuration:
- prepare the
FirebaseProvider - add the firekit reducers to your redux reducer
To initialize the FirebaseReducer we need to initialize our firebase app as it is described in the official firebase documentation.
When we have the firebaseApp we just add it as paramater to our Provider.
import React from 'react';
import ReactDOM from 'react-dom';
import { Provider } from 'react-redux';
import { FirebaseProvider } from 'firekit-provider'; // Import the FirebaseProvider from firekit
import configureStore from './store';
import { Root } from './containers/Root';
import { addLocalizationData } from './locales';
import injectTapEventPlugin from 'react-tap-event-plugin';
import registerServiceWorker from './registerServiceWorker';
import firebase from 'firebase';
const store = configureStore();
addLocalizationData();
//Get the configs of your firerbase project
const firebaseConf={
apiKey: "AIzaSyBQAmNJ2DbRyw8PqdmNWlePYtMP0hUcjpY",
authDomain: "react-most-wanted-3b1b2.firebaseapp.com",
databaseURL: "https://react-most-wanted-3b1b2.firebaseio.com",
projectId: "react-most-wanted-3b1b2",
storageBucket: "react-most-wanted-3b1b2.appspot.com",
messagingSenderId: "258373383650"
}
//Initialise your firebase app
const firebaseApp = firebase.initializeApp(firebaseConf);
//The part above can be done in a seperate file so it can be acessed from everiwhere in your application
//It is moved here in this snipped for simplicity purpose
//Now in your root part of your application add the FirebaseProvider as you have done with the redux Provoder
//Take care that the FirebaseProvider comes after the redux Provider to have access to the redux store
ReactDOM.render(
<Provider store={store}>
<FirebaseProvider firebaseApp={firebaseApp}>
<Root />
</FirebaseProvider>
</Provider>
, document.getElementById('root')
);
registerServiceWorker();
Take care that adding the FirebaseProvider happens in a root part of your application and after the redux Provider.
Taht would be the first part. In the second one we just add the firekit reducers to our redux reduxer.
import { responsiveStateReducer } from 'redux-responsive';
import { combineReducers } from 'redux';
import { responsiveDrawer } from 'material-ui-responsive-drawer';
import { reducer as formReducer } from 'redux-form'
import auth from './auth/reducer';
import dialogs from './dialogs/reducer';
import messaging from './messaging/reducer';
import locale from './locale/reducer';
import theme from './theme/reducer';
import firekitReducers from 'firekit'; //Import the firekitReducers
console.log(firekitReducers);
const reducers = combineReducers({
browser: responsiveStateReducer,
responsiveDrawer,
form: formReducer,
auth,
dialogs,
messaging,
locale,
theme,
...firekitReducers //Spread the firekit reducers
})
export default reducers;
To add all firekit reducers to your redux store just spread the firekitReducers object into your comineReducers object.
WARNING: if you are using persistance take care that the reducer initialization is not persisted! He saves the watchers. If he would be persisted the watcher would not initialize again after a page reload. If you are using redux-persist just add him to the black list.
persistStore(store, {blacklist:['auth', 'form', 'connection', 'initialization'] }, ()=>{}); //Add initialization to persistance blacklist if you use persistance
INFO: the reducers are not customasable. In future we could add customatisation for this so they could have any name you want.
Usage
Let us now do something with our firekit :smile:
To use firekit in a component we need to tell the component to get all firekit props from the context.
We use for that a simple call withFirebase. It is very similar to the react-router call withRouter. The usage is exactly the same.
Let us take a look on a simple component.
import React, { Component } from 'react';
import {injectIntl, intlShape} from 'react-intl';
import { Activity } from '../../containers/Activity';
import { withFirebase } from 'firekit-provider';
class MyComponent extends Component {
componentDidMount(){
const { watchList }= this.props;
watchList('companies'); //Here we started watching a list
}
render() {
const { intl }= this.props;
return (
<Activity
title={intl.formatMessage({id: 'my_component'})}>
</Activity>
);
}
}
MyComponent.propTypes = {
intl: intlShape.isRequired,
};
export default injectIntl(withFirebase(MyComponent)); //Here using 'withFirebase()' we added all we need to our component
As you can see calling withFirebase(Component) adds to our Component all props we need to work with firekit. watchList is one of more API calls we can make. More about every one is writen below in the API section.
Now that we know how to add the firekit props to our Compont lets take a look what we can do with it.
Accessing firebaseApp
The FirebaseProvider provides the firebaseApp trought the rect context and withFirebase allows us to get it easely as Component property. We can then do with the firebaseApp whatever we want: create, update, delete data in the realtime databae, work with the auth or with the storage. You have all your freedom with firebase cause firebaseApp is the same one you initialised and put into the FirebaseProvider.
import React, { Component } from 'react';
import {injectIntl, intlShape} from 'react-intl';
import { Activity } from '../../containers/Activity';
import { withFirebase } from 'firekit-provider';
class MyComponent extends Component {
componentDidMount(){
const { firebaseApp }= this.props;
firebaseApp.database().ref('some_value').update(55); //Here we just changed a value in our database
}
render() {
const { intl }= this.props;
return (
<Activity
title={intl.formatMessage({id: 'my_component'})}>
</Activity>
);
}
}
MyComponent.propTypes = {
intl: intlShape.isRequired,
};
export default injectIntl(withFirebase(MyComponent)); //Here using 'withFirebase()' we added all we need to our component
Connection
Firebase has integrated a listener to observe the connection state to your firebase app.
import React, { Component } from 'react';
import { connect } from 'react-redux';
import { withFirebase } from 'firekit-provider';
class MyComponent extends Component {
componentDidMount(){
const { initConnection }= this.props;
initConnection(); //Here we started watching the connection state
}
componentWillUnmount() {
const { unsubscribeConnection, }= this.props;
unsubscribeConnection(); // Here we unsunscribe the listening to the connection state
}
render() {
const { isConnected }= this.props;
return (
<div>Connection state:{isConnected}</div>
);
}
}
const mapStateToProps = (state) => {
const { connection} = state;
return {
isConnected: connection?connection.isConnected:false, // Here we get the connection state from the redux store
};
};
export default connect(
mapStateToProps
)(withFirebase(MyComponent));
Lists and Queries
We can easely observe lists in the realtime database using the watchList and unwatchList API calls. The same calls are used to observe Firebase queries. watchList and unwatchList can recieve as parameter a string to a database path or a Firebase reference to that path. If you have a simple reference to a path using just the string of the path is the right choice. But if you have a Firebase query reference you can send that reference with all its query calls as parameter.
IMPORTAND:: the list will be a Array contained of objects witch have the props key and val where the key is the child key in the list and val the value of the child. This is similar to the snapshot you get from a Firebase list on event.
import React, { Component } from 'react';
import { connect } from 'react-redux';
import { withFirebase } from 'firekit-provider';
import _ from 'lodash';
class MyComponent extends Component {
componentDidMount(){
const { watchList, firebaseApp }= this.props;
watchList('users'); //Here we started watching the users list
//Here we watch a simple firebase query
let tasksRef= firebaseApp.database().ref('tasks').limitToFirst(10);
watchList(tasksRef);
//Here we watch a list and save the data on a specific location in our redux store
watchList('public_tasks', 'tasks');
}
componentWillUnmount() {
const { unwatchList, }= this.props;
unwatchList('users'); // We can unwatch the list on unmounting the Component
unwatchList('tasks'); // To unwatch a query qe can use just the ref path string
unwatchList('public_tasks'); // To unwatch a watcher that is stored in a specific location we call the unwatchList with the path
}
rednerList = () => {
const {users} =this.props;
if(users===undefined){
return <div></div>
}
return _.map(users, (user, i) => {
return <div key={i}>
{user.val.displayName}
</div>
});
}
render() {
const { isConnected }= this.props;
return (
<div>
{this.rednerList()}
</div>
);
}
}
const mapStateToProps = (state) => {
const { lists } = state;
return {
users: lists.users,
tasks: lists.tasks, //the data from 'public_tasks' path
};
};
export default connect(
mapStateToProps
)(withFirebase(MyComponent));
Here we unwatched the list on componentWillUnmount. We could also leave this away and the list will change in realtime in the background and it will not load all data on revisiting the Component again.
If you are using persistand watcher you would have to unwatch them in some point of your application or on application exit.
Because of that there are special calls that allow us to unwatch all persistand watcher in a single call. That could be calles in the root component of your application like this:
//... other code of your root Component
componentWillUnmount() {
const { unsubscribeConnection, unwatchAllLists, unwatchAllPaths }= this.props;
unsubscribeConnection();
unwatchAllLists();
unwatchAllPaths();
}
//... other code of your root Component
INFO: You can call the watchList and watchPath as often you want. The library caches initialized lists and paths to the initialization state so it knows if you are trying to initialize a list or path that is already initialized and is already observed and in that case the library just doesn't do anything. So if you call watchList('users') in multiple places in your application you don't have to care about if it is already initialized or not and can be shure that if it is you just have your data in the redux store ready to use.
As you noticed we here unwatch not only the lists but also the connection and the paths watcher.
Paths
The paths watcher exactly like the lists watcher with watchPath and unwatchPath.
//...
componentDidMount(){
const { watchPath }= this.props;
watchPath('users_count'); //Here we started watching the path
}
componentWillUnmount() {
const { unwatchPath, destroyPath }= this.props;
unwatchPath('users'); // We can unwatch the path on unmounting the Component
destroyPath('users'); // We can destory the path. This will remove the path data from redux.
//INFO: calling destroy will automaticaly unwatch the path or list
}
//...
Here we also unwatch the path on componentWillUnmount but we could also leave the watcher persistand and unwatch it on application closing. This is useful if you need to load user data or user permissions from the database and you want that the permission changes take effect in realtime to the user.
Docs
firekit can use the new Firebase firestore feature and enables you to watch changes on documents and collections.
The docs watcher exactly like the paths watcher with watchDoc and unwatchDoc.
//...
componentDidMount(){
const { watchDoc }= this.props;
watchDoc('samples/sandwichData');
}
componentWillUnmount() {
const { unwatchDoc, destroyDoc }= this.props;
unwatchDoc('samples/sandwichData');
destroyDoc('samples/sandwichData');
}
//...
IMPORTAND:: The RealtimDatabase of Firebase enabled us to have global unsubsrciption to the watchers. This is no longer possible with the firestore so even it seems possible to work with persistent watchers it's unofrtunately NOT! You have to take care to unwatch every listener when leaving a component or the instance where the watcher was initialised.
Collections
The collections watcher exactly like the docs watcher with watchCol and unwatchCol.
//...
componentDidMount(){
const { watchCol }= this.props;
watchCol('posts');
}
componentWillUnmount() {
const { unwatchCol, destroyCol }= this.props;
unwatchCol('posts');
}
//...
IMPORTAND:: Here we have the same restrictions as they are with docs on the global unwatch feature.
FireForm
FirForm is a special component created for usage with redux-form. It takes a path and an uid paramater to know where to get its data. The name propertie is the name of the redux-form Form name. All other properties are optional and wil be described in further documentation. It is importand to know that FireForm can only be used in Components that have the withFirebase called to access the firebaseApp.
Inside the FireForm we put as child our Form with the fields we want and the macig hapens :smile:
All fields will be filled with the data from the path and uid and if no uid is provided the form will be a Form that creates a new entry in your path.
And comes the cool thing. If you are in the Form working on fields and someone else changes some data. Every field that you haven't changed will be in realtime updated! Isn't that cool :smile:
//...
<FireForm
firebaseApp={firebaseApp}
name={'companie'}
path={`${path}`}
onSubmitSuccess={(values)=>{history.push('/companies');}}
onDelete={(values)=>{history.push('/companies');}}
handleCreateValues={this.handleCreateValues}
uid={match.params.uid}>
<Form /> // Here is your simple form
</FireForm>
//...
Messaging
Firebase offers a simple API for managing push notification messages. Firekit provides a simple API call initMessaging that manages all messaging events for you and syncs them to your redux store. The API call can recieve a function paramater you can use to hanlde new messages. That parameter is optional. Firekit stores the messaging token, permission and new messages to your store automaticaly. In future there will be added APIs to clear single and all messages.
//...
componentDidMount(){
const { initMessaging }= this.props;
initMessaging((payload)=>{console.log(payload)}); //Here we initialise the Firbease messaging and log new messages to the console
}
//...
TO DO
- [X] compine all reducer to one import
- [X] integrate firebase messaging
- [X] integrate firebase auth watcher
- [X] integrate firebase queries watcher
- [X] implement alias names (custom destination locations) for path and list watchers
- [X] seperate firekit-provider and fireform in seperate projects
- [X] integrate
firestoredocuments watcher - [X] integrate
firestorecollections watcher - [X] integrate
firestorequeries watcher - [X] integrate selectors for lists
- [X] integrate error hanling
- [X] integrate loading indicators in redux state
