.verb.md

🔥 🐣 {%= name %} {%= badge("fury") %} {%= badge("travis") %}

{%= description %}

{%= badge("npm") %}

Firedux (fiery·ducks) wraps the Firebase JavaScript API to dispatch Redux actions that optimisically & immediately read/write to an in-memory subset of your data from Firebase, then asynchronously pull & push data in the background.

Also supports some authentication methods and actions.

Works well with React.

Support firedux and fiery ducks like Magmar!

{%/*

Table of contents

*/%}

Install

{%= include("install-npm", { save: true }) %}

You'll need to configure redux-thunk on your Redux store.

Use

See my TodoMVC example, the tests, and below:

import Firedux from 'firedux'
import Firebase from 'firebase'
import { createStore, applyMiddleware, combineReducers } from 'redux'
import thunk from 'redux-thunk'

/**
 * For Firebase 2.x, e.g.:
 */
var ref = new Firebase('https://redux-firebase.firebaseio.com/')

/**
 * Or for Firebase 3.x, e.g.:
 */
var app = Firebase.initializeApp({
  apiKey: '<your-api-key>',
  authDomain: '<your-auth-domain>',
  databaseURL: 'https://redux-firebase.firebaseio.com/',
  storageBucket: '<your-storage-bucket>'
})
var ref = app.database().ref()

/**
 * Then create your Firedux instance, passing it your database reference as `ref`.
 */
const firedux = new Firedux({
  ref,

  // Optional:
  omit: ['$localState'] // Properties to reserve for local use and not sync with Firebase.
})

const reducer = combineReducers({
  firedux: firedux.reducer()
  // Your other reducers...
})

// Create store with middleware, including thunk.
const store = applyMiddleware(
  thunk
  // Your other middleware...
)(createStore)(reducer)

// Set dispatch function from store on your Firedux instance.
firedux.dispatch = store.dispatch


// Later, you can subscribe to state.
store.subscribe(() => {
  const state = store.getState()
  const { data, authData } = state.firedux
  console.log('Test data from Firebase:', data.test)

  // Lazy loading
  // e.g. once authorized, get user data:
  if (authData && authData.auth && authData.auth.uid) {
    firedux.watch(`users/${authData.auth.uid}`)
  }
})

// Watch a path:
firedux.watch('users/joe')
.then(({snapshot}) => {})
// state.firedux.data.users.joe
// Note: this promise will only resolve on the first value,
//  but it'll keep syncing on all value updates.

// Get:
firedux.get('posts/123')
.then(({snapshot}) => {})
// state.firedux.data.posts['123']

// Set:
firedux.set('test', true)
.then(({value}) => {})
// state.firedux.data.test == true

// Update (merging set):
firedux.update('users/joe', { job: 'developer' })
.then(({value}) => {})
// state.firedux.data.users.joe == { name: 'Joe', job: 'developer' }

// Push (to a collection):
firedux.push('users', { name: 'Jane' }, (id) => {
  // The ID is generated locally immediately,
  // so you can get it before the push with this callback.
  // id == '-K95Cjx-caw2uSNsFJiI'
})
.then((id) => {})
// state.firedux.data.users['-K95Cjx-caw2uSNsFJiI'] == { name: 'Jane' }

// Remove:
firedux.remove('users/joe')
.then(() => {})
// state.firedux.data.users['joe'] == undefined


// Auth
// WARNING: Auth methods may only support Firebase 2.x for now.

// Init
// Call this when your app starts, to get existing session, and listen for auth changes.
firedux.init()
// See Login state below.

// Login
firedux.login({
  email: '[email protected]',
  password: '123'
})
// state.firedux.authData == { auth: { uid: '123' } }
//  etc. `authData` per https://www.firebase.com/docs/web/api/firebase/authwithcustomtoken.html
// or state.firedux.authError == Error

// Logout
firedux.logout()
// state.firedux.authData == null

// To handle some unsupported features, you can get access to the underlying Firebase instance via:
firedux.ref
// e.g. turn off a watch:
firedux.ref.child('users/joe').off('value')
// or login with OAuth:
firedux.ref.authWithOAuthPopup("twitter", (error, authData) => {
  store.dispatch({type: 'FIREBASE_LOGIN', error, authData})
})

Analytics

This component includes tracking via Google Analytics. The purpose is to better understand how and where it's used, as a guide for development.

To opt-out of this tracking, before loading the script on your page, use the global options in JavaScript, with noTrack set to true, as follows:

window.FIREDUX_OPTIONS = {
  noTrack: true
};

Running tests

{%= include("tests") %}

Contributing

{%= include("contributing") %} {%= include("contributing-extra") %}

Author

{%= include("author") %}

License

{%= copyright({start: 2015, linkify: true}) %} {%= license({linkify: true}) %}

---

{%= include("footer") %}