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
• Docs
• Contributing

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';
      import 'firebase/performance';
      //...
      

   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 firebaseConfig={firebaseConfig} initPerformance>
          <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

   We need to do this because useFirestoreDoc throws a Promise while it is waiting for a response from Firestore. Suspense will catch the Promise and render fallback until the Promise is resolved.

   //...
   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

A React Context Provider that allows the useFirebaseApp hook to pick up the firebase object.

Sample usage

const firebaseConfig = {
  /* web app config from Firebase console */
};

<FirebaseAppProvider firebaseConfig={firebaseConfig} initPerformance>
  <App />
</FirebaseAppProvider>;

Props

Prop	Type	Description
config	Object	the web app config object usually passed to initializeApp
initPerformance	bool	Whether or not to initialize Firebase Performance Monitoring

Hooks

useFirebaseApp

When called from a component nested inside a FirebaseAppProvider, useFirebaseApp returns the root Firebase object.

IMPORTANT: By default, useFirebaseApp returns a firebase object without any products attached to it (e.g. you can't call firebase.firestore(). To do that, you need to import 'firebase/firestore' or any other Firebase feature as needed)

Returns

firebase

useUser

Get the user that is currently signed in.

Throws a Promise by default

Parameters

Parameter	Type	Description
auth ?	Auth	[optional] auth object. If not provided, useUser will use useFirebaseApp to find the Auth object.
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

User

useFirestoreDoc

Listen to a Firestore Document.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	DocumentReference	A reference to the document you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

DocumentSnapshot

useFirestoreCollection

Listen to a Firestore Collection.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	CollectionReference	A reference to the collection you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

QuerySnapshot

useDatabaseObject

Listen to a Realtime Database Object.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Reference	A reference to the object you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

QueryChange

useDatabaseList

Listen to a Realtime Database list.

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Reference	A reference to the list you want to listen to
options ?	ReactFireOptions	Options. This hook will not throw a Promise if you provide startWithValue.

Returns

QueryChange[]

useStorageTask

Listen to a Storage UploadTask

Throws a Promise by default

Parameters

Parameter	Type	Description
task	UploadTask
ref	Reference
options ?	ReactFireOptions

Returns

UploadTaskSnapshot

useStorageDownloadURL

Subscribe to a storage blob's download URL

Throws a Promise by default

Parameters

Parameter	Type	Description
ref	Reference
options ?	ReactFireOptions

Returns

string

Components

AuthCheck

Renders children if a user is signed in and meets the required claims. Renders fallback otherwise.

Props

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

SuspenseWithPerf

Starts a Firebase Performance Monitoring trace and ends it when suspense stops suspending.

Props

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

ReactFireOptions

Property	Type
startWithValue	any

Contributing

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