Reactfire

npm install reactfire

Hooks, Context Providers, and Components that make it easy to interact with Firebase.

By default, every reactfire hook throws a Promise until it has connected to Firebase, allowing you to use Suspense to render a fallback component. If you don't want reactfire to throw a promise, pass an initial value to a reactfire hook. It will emit the initial value right away instead of throwing a promise.

Quickstart

Listen for realtime changes in a Firestore document with Reactfire. We'll use create-react-app to quickly get a Reactfire demo up and running.

1. Create a fresh React app.

   create-react-app myapp
   

2. Install reactfire and the Firebase SDK

   npm i firebase reactfire
   

3. Create a world-readable document in Firestore.

   For example, a collection called tryreactfire with document burrito with field yummy: true.

   To keep this as simple as possible, modify your security rules to make that document world-readable.

4. Modify src/index.js

   1. Import firebase and reactfire

      //...
      import { FirebaseAppProvider } from 'reactfire';
      import * as firebase from 'firebase/app';
      //...
      

   2. Wrap your app in a FirebaseAppProvider and provide the config object from the Firebase console

      //...
      const firebaseConfig = {
        /* add your config object from Firebase console */
      };
      ReactDOM.render(
        <FirebaseAppProvider config={firebaseConfig}>
          <App />
        </FirebaseAppProvider>,
        document.getElementById('root')
      );
      //...
      

5. Modify src/App.js

   1. Import firebase/firestore as well as the useFirestoreDoc and useFirebaseApp hooks

      //...
      import 'firebase/firestore';
      import { UseFirestoreDoc } from 'reactfire';
      //...
      

   2. Add a function component

      //...
      function Burrito() {
        // create a ref
        const firebaseApp = useFirebaseApp();
        const burritoRef = firebaseApp
          .firestore()
          .collection('tryreactfire')
          .doc('burrito');
      
        // get the doc. just one line!
        const burritoDoc = useFirestoreDoc(burritoRef);
      
        // get the value from the doc
        const isYummy = burritoDoc.data().yummy;
      
        return <p>The burrito is {isYummy ? 'good' : 'bad'}</p>;
      }
      //...
      

   3. Render your component inside of a Suspense tag

   //...
   function App() {
     return (
       <div className="App">
         <header className="App-header">{/* ... */}</header>
         <Suspense fallback={'loading burrito status...'}>
           <Burrito />
         </Suspense>
       </div>
     );
   }
   //...
   

6. Run your app!

   npm run start
   

7. Edit the value of yummy in the Firebase console, and watch it update in real time in your app! 🔥🔥🔥

Docs

ToC

• Providers
  • FirebaseAppProvider
• Hooks
  • useFirebaseApp
  • Authentication
    • useUser
  • Database
    • Cloud Firestore
      • useFirestoreDoc
      • useFirestoreCollection
    • Realtime Database
      • useDatabaseObject
      • useDatabaseList
  • Cloud Storage
    • useStorageTask
    • useStorageDownloadURL
• Components
  • Performance Monitoring
    • SuspenseWithPerf
  • Authentication
    • AuthCheck

Providers

FirebaseAppProvider

Hooks

useFirebaseApp

useUser

useFirestoreDoc

useFirestoreCollection

useDatabaseObject

useDatabaseList

useStorageTask

useStorageDownloadURL

Components

SuspenseWithPerf

AuthCheck

AuthCheckProps

Property	Type
auth	Auth
children	React.Component
fallback	React.Component
requiredClaims	Object

SuspensePerfProps

Property	Type
children	React.Component
fallback	React.Component
firePerf	any
traceId	string

ReactFireOptions

Property	Type
startWithValue	any

Components

AuthCheck

Props

interface AuthCheckProps

Returns

React.FunctionComponent

SuspenseWithPerf

Props

interface SuspensePerfProps

Returns

React.FunctionComponent

Hooks

useDatabaseList

Subscribe to a Realtime Database list

Parameters

Parameter	Type
ref	Reference or Query
options ?	ReactFireOptions

Returns

QueryChange[]

useDatabaseObject

Subscribe to a Realtime Database object

Parameters

Parameter	Type
ref	Reference
options ?	ReactFireOptions

Returns

QueryChange

useFirestoreCollection

Subscribe to a Firestore collection

Parameters

Parameter	Type
ref	CollectionReference
options ?	ReactFireOptions

Returns

QuerySnapshot

useFirestoreDoc

Suscribe to Firestore Document changes

Parameters

Parameter	Type
ref	DocumentReference
options ?	ReactFireOptions

Returns

DocumentSnapshot

useStorageDownloadURL

Subscribe to a storage ref's download URL

Parameters

Parameter	Type
ref	Reference
options ?	ReactFireOptions

Returns

string

useStorageTask

Subscribe to the progress of a storage task

Parameters

Parameter	Type
task	UploadTask
ref	Reference
options ?	ReactFireOptions

Returns

UploadTaskSnapshot

useUser

Subscribe to Firebase auth state changes, including token refresh

Parameters

Parameter	Type
auth	Auth
options ?	ReactFireOptions

Returns

User

useObservable

Parameters

Parameter	Type
observable$	Observable
observableId	string
startWithValue ?	any

Returns

any

For development

1. yarn install
2. cd into the reactfire/reactfire directory. run yarn run watch.
3. In a new terminal, cd into the reactfire/sample-simple directory. run yarn start.
4. Head over to https://localhost:3000 to see the running sample

Testing

1. cd into the reactfire/reactfire directory
2. run yarn test