Fireact

Explainer

Fireact is a library of React hooks that provide easy access to Firebase products inside your React app.

Example use case

With hooks like useFirebaseDatabaseState, there's an easy API for:

• subscribing a component to data in your Firebase Real-Time Database;
• triggering updates to your data in your Firebase Real-Time Database.

Installation

npm install --s fireact

Main API

import Fireact from 'fireact'

// Retrieve your own options values by adding a web app on
// https://console.firebase.google.com
const config = {
  apiKey: "AIza....",                             // Auth / General Use
  authDomain: "YOUR_APP.firebaseapp.com",         // Auth with popup/redirect
  databaseURL: "https://YOUR_APP.firebaseio.com", // Realtime Database
  storageBucket: "YOUR_APP.appspot.com",          // Storage
  messagingSenderId: "123456789"                  // Cloud Messaging
}

const products = [
  'auth',
  'database'
  // ...include any other Firebase products you want to use
]

const {
  firebase,     // firebase object with API as documented: https://firebase.google.com/docs/reference/js/
  Provider,     // Parent Provider that allows Fireact hooks to be used in components nested within
  middleware    // Redux middleware that makes the firebase object available as a property of all actions
} = Fireact(config, products)

Any components that are wrapped in Provider, or have a parent/ancestor wrapped in Provider, gain access to the library's hooks.

Most notable of these are:

• useFirebase
• useFirebaseCurrentUser
• useFirebaseDatabaseState

Hooks

Hooks can be used inside any component that has Provider wrapped around it.

useFirebase()

Returns

The firebase object initialised by Fireact.

Example

import React from 'react'
import { useFirebase } from 'fireact'

function Component() {
  const firebase = useFirebase()

  // exposes the JS Firebase API
  // docs at https://firebase.google.com/docs/reference/js/
}

useFirebaseCurrentUser()

Returns

The current user from Firebase Authentication, if there is one.

Example

import React from 'react'
import { useFirebaseCurrentUser } from 'fireact'

function Component() {
  const user = useFirebaseCurrentUser()

  // exposes the firebase.User object for the current Firebase user
  // docs at https://firebase.google.com/docs/reference/js/firebase.User.html
}

useFirebaseDatabaseState(path, [options = {}])

Parameters

• path (string): path to a value in the Firebase Real-Time Database
• options (object, optional): a configuration object for sorting and filtering

Returns

An array with two elements:

1. The current value of the Firebase Real-Time Database at path; and
2. An object of functions which can be used to write to Firebase Real-Time Database at path.

These are the two return values, respectively, from useFirebaseDatabaseValue and useFirebaseDatabaseWriters.

Example

import React from 'react'
import { useFirebaseDatabaseState } from 'fireact'

function Component() {
  const [value, { set, transaction, update, push, pushWithKey }] = useFirebaseDatabaseState('arbitrary/path/to/entry')

  // your logic here
}

useFirebaseDatabaseValue(path, [options = {}])

Parameters

• path (string): path to a value in the Firebase Real-Time Database
• options (object, optional): a configuration object for sorting and filtering

Returns

The current value of the Firebase Real-Time Database at path.

Example

import React from 'react'
import { useFirebaseDatabaseValue } from 'fireact'

function Component() {
  const value = useFirebaseDatabaseValue('arbitrary/path/to/entry')

  // exposes the JS value from the Firebase RTD database location of path
}

options object: sorting and filtering

| Key | Value (type) | Description | Firebase Docs | | --- | --- | --- | --- | | orderByChild | string | Uses the given value as a child key to order the data | firebase.database.Reference.orderByChild | | orderByKey | boolean | If true, orders the data by key | firebase.database.Reference.orderByKey | | orderByPriority | boolean | If true, orders the data by priority | firebase.database.Reference.orderByPriority | | orderByValue | boolean | If true, orders the data by value | firebase.database.Reference.orderByValue | | limitToFirst | number | Retrieves only the first limitToFirst number of children | firebase.database.Reference.limitToFirst | | limitToLast | number | Retrieves only the last limitToLast number of children | firebase.database.Reference.limitToLast | | startAt | number, string or boolean | | firebase.database.Reference.startAt | | endAt | number, string or boolean | | firebase.database.Reference.endAt | | equalTo | number, string or boolean | | firebase.database.Reference.equalTo |

useFirebaseDatabaseWriters(path)

Parameters

• path (string): path to a value in the Firebase Real-Time Database

Returns

An object of functions which can be used to write to Firebase Real-Time Database at path:

| Function | Description | Firebase Docs | | --- | --- | --- | | set | Takes a value and updates the RTD to the given value at path | firebase.database.Reference.set | | transaction | Takes a callback and updates the RTD with the return value from the callback when it is passed the RTD's current value at path | firebase.database.Reference.transaction | | update | Takes an object and updates the RTD by assigning the object's key-value pairs at path | firebase.database.Reference.update | | push | Takes an value, auto-generates a push key for it, and updates the RTD at said key from path with the passed in value | firebase.database.Reference.push | | pushWithKey | Takes a callback, (autoGeneratedPushKey) => value, which updates the RTD at the auto-generated push key from path (as above, with the vanilla push) to the return value of the callback | N/A |

Example

import React from 'react'
import { useFirebaseDatabaseWriters } from 'fireact'

function Component() {
  const {
    set,
    transaction,
    update,
    push,
    pushWithKey
  } = useFirebaseDatabaseWriters('arbitrary/path/to/entry')

  // functions can be executed inside a useEffect hook, component callback, etc.
}