# fireact

> Hooks, middleware and helpers for using Firebase with React

Latest version **0.1.5** (published 2019-11-12) · ISC license · 0 weekly downloads

## Install

```sh
npm install fireact
pnpm add fireact
yarn add fireact
bun add fireact
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.5 |
| Published | 2019-11-12 |
| First published | 2019-07-10 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 9 |
| Unpacked size | 232.9 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1 |
| Maintainers | richardcrng |

## Links

- npm: https://www.npmjs.com/package/fireact
- Repository: https://github.com/richardcrng/fireact
- Homepage: https://github.com/richardcrng/fireact#readme
- Issues: https://github.com/richardcrng/fireact/issues
- npm.io page: https://npm.io/package/fireact

## Dependencies (9)

- [ramda](https://npm.io/package/ramda.md) ^0.26.1
- [react](https://npm.io/package/react.md) ^16.11.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [firebase](https://npm.io/package/firebase.md) ^7.2.3
- [react-dom](https://npm.io/package/react-dom.md) ^16.11.0
- [@types/jest](https://npm.io/package/@types/jest.md) ^24.0.21
- [@types/ramda](https://npm.io/package/@types/ramda.md) ^0.26.18
- [@types/lodash](https://npm.io/package/@types/lodash.md) ^4.14.136
- [@babel/polyfill](https://npm.io/package/@babel/polyfill.md) ^7.4.4

## Recent versions

- 0.1.5 (latest) — 2019-11-12
- 0.1.4 — 2019-11-10
- 0.1.3 — 2019-11-06
- 0.1.2 — 2019-11-06
- 0.1.1 — 2019-07-30
- 0.1.0 — 2019-07-29
- 0.0.7 — 2019-07-29
- 0.0.6 — 2019-07-10
- 0.0.5 — 2019-07-10
- 0.0.4 — 2019-07-10
- 0.0.3 — 2019-07-10
- 0.0.2 — 2019-07-10
- 0.0.1 — 2019-07-10

## README

# Fireact

[![Build Status](https://travis-ci.com/richardcrng/fireact.svg?branch=master)](https://travis-ci.com/richardcrng/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`](#usefirebasedatabasestatepath-options--), 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
```bash
npm install --s fireact
```

## Main API
```js
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`](#usefirebase)
* [`useFirebaseCurrentUser`](#usefirebasecurrentuser)
* [`useFirebaseDatabaseState`](#usefirebasedatabasestatepath-options--)

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

### `useFirebase()`
#### Returns
The `firebase` object initialised by Fireact.

#### Example
```js
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
```js
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`](##usefirebasedatabasevaluepath-options--) and [`useFirebaseDatabaseWriters`](#usefirebasedatabasewriterspath).

#### Example
```js
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
```js
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`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#order-bychild) |
| `orderByKey` | boolean | If true, orders the data by key | [`firebase.database.Reference.orderByKey`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#order-bykey) |
| `orderByPriority` | boolean | If true, orders the data by priority | [`firebase.database.Reference.orderByPriority`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#order-bypriority) |
| `orderByValue` | boolean | If true, orders the data by value | [`firebase.database.Reference.orderByValue`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#order-byvalue) |
| `limitToFirst` | number | Retrieves only the first `limitToFirst` number of children | [`firebase.database.Reference.limitToFirst`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#limit-tofirst) |
| `limitToLast` | number | Retrieves only the last `limitToLast` number of children | [`firebase.database.Reference.limitToLast`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#limit-tolast) |
| `startAt` | number, string or boolean |  | [`firebase.database.Reference.startAt`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#start-at) |
| `endAt` | number, string or boolean |  | [`firebase.database.Reference.endAt`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#end-at) |
| `equalTo` | number, string or boolean |  | [`firebase.database.Reference.equalTo`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#equal-to) |

### `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`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#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`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#transaction) |
| `update` | Takes an object and updates the RTD by assigning the object's key-value pairs at `path` | [`firebase.database.Reference.update`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#update) |
| `push` | Takes an value, [auto-generates](https://firebase.googleblog.com/2015/02/the-2120-ways-to-ensure-unique_68.html) a [push key](https://firebase.google.com/docs/database/web/lists-of-data#append_to_a_list_of_data) for it, and updates the RTD at said key from path with the passed in value | [`firebase.database.Reference.push`](https://firebase.google.com/docs/reference/js/firebase.database.Reference.html#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
```js
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.
}
```

---
_Source: https://npm.io/package/fireact · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._