fuego

🔥 Firebase Firestore hooks & components for React and React Native.

⚡️ Provides out-of-the-box optimization to prevent memory leaks from multiple listeners/subscriptions.

Install

npm i --save @nandorojo/fuego firebase

Requires react 16.8.3 or higher to support hooks.

useFuego

React hook that turns any firestore query into a stateful component.

See useFuego docs for custom options.

Query users

Don't worry about parsing through firestore's querySnapshot. Fuego handles that for you.

import { useFuego } from '@nandorojo/fuego'

const Users = () => {
  const { data, loading } = useFuego({ path: 'users' })

  if (loading) return <Loading />

  return data.map(user => <User name={user.name} id={user.id} />)
}

Real-time chat in ten lines of code

Fuego automatically handles removing the listeners when a component unmounts.

const Chat = ({ roomId }) => {
  const { data, loading } = useFuego({
    path: `chatrooms/${roomId}/messages`,
    // subscribe to live to updates
    listen: true
  })

  if (loading) return <Loading />

  return data.map(message => <Message text={message.text} id={message.id} />)
}

Query popular memes

const Memes = () => {
  const { data, loading } = useFuego({
    path: 'memes',
    limit: 20,
    where: ['popularity', '>=', '90'],
    orderBy: 'popularity'
  })

  if (loading) return <Loading />

  return data.map(user => <Meme url={meme.url} id={meme.id} />)
}

Easily write data to your backend

// NOTE this is using useFuegoContext, not useFuego
import { useFuegoContext } from '@nandorojo/fuego'

const ChatRoom = (props) => {
  // access the firestore db object
  const { db } = useFuegoContext()
  
  const sendMessage = (text) => {
   // write to the firestore db
  	db.collection(`channels/${props.id}/messages`).add({ text })
  }

 // return your render code here...
}

Setup

1. Wrap your App.js component with the <FuegoProvider /> component. Pass a Fuego instance as a prop.
2. Place the <FuegoGate /> component directly within the provider component to make sure your app has up-to-date auth.

See firebase's website for steps on getting your firebaseConfig.

** Example**

import React from 'react'
import { FuegoProvider, Fuego, FuegoGate } from '@nandorojo/fuego'
import YourAppHere from './path/to/app'

// replace with your custom firebaseConfig
const firebaseConfig = {
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appID: 'app-id'
}

const fuego = new Fuego(firebaseConfig)

export default () => {
  return (
    <FuegoProvider fuego={fuego}>
      <FuegoGate signInAnonymously displayName="AnonymousTestName">
        <YourAppHere />
      <FuegoGate>
    </FuegoProvider>
  )
}

Docs

useFuego

React hook to query Firestore. Allows both for one-time get requests or snapshot listeners.

Arguments

useFuego takes 2 arguments: query and options.

const { data, loading } = useFuego(query, options)

data
loading
error
db
ref
unsubscribe

Returns

<FuegoGate />

Component that lets your app always be properly authenticated with firebase. Its children won't render until the app has successfully authenticated.

Important: This component must be wrapped within the FuegoProvider to work. It's highly recommended you make it the direct child (as seen in the example above), though it isn't techincally necessary.

FuegoGate props

| Prop | Type | Description | example | |---------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| | signInAnonymously | boolean | (Optional) If true, users will automtically be signed in anonymously, unless the AuthComponent prop is specified. This is useful for testing with anonymous users. | | | beforeAuthUpdate | (user: firebase.User or null) => void | (Optional) Callback function that will be called when the auth updates, right before the component updates. It takes one argument: a user if it exists, and null otherwise. This is useful if you want to store the user in redux or some other state manager. | | | displayName | string | (Optional) A display name given to the user if the signInAnonymously prop is set to true. | | | photoURL | string | (Optional) A photo url given to the user if the signInAnonymously prop is set to true. | | | LoadingComponent | ReactNode | null | (Optional) A react component that renders while the auth is initially loading. Defaults to a screen with a loading indicator; you can also set it to null to disable it. | | | AuthComponent | ReactNode | (Required if you don't set signInAnonymously to true. A react component to render when loading has completed and the user is not currently signed in. This is where you insert your own auth flow component. It receives this firebase instance's auth as a prop, so you can use this.props.auth().signInWithToken in the component or other firebase auth methods using that prop. Overrides signInAnonymously if prop is set. | |

// ...following the <FuegoProvider /> example

export default () => {
  return (
    <FuegoProvider fuego={fuego}>
      <FuegoGate> // <-- this part is added
        <App />
      </FuegoGate>
    </FuegoProvider>
  )
}