quickstart.md

Getting Started with ReactFire

⚛ + 🔥 = 🌯

This quickstart shows you how to connect your React web app to Cloud Firestore, listen for its data, and display the data in real time. We'll also configure Firebase Performance Monitoring so you can get some performance stats.

Let's build a web app that displays, in real time, the tastiness of a burrito. Yum!

To see the completed app, check out this StackBlitz workspace.

1. Create a document in Cloud Firestore

If your project doesn't have a Cloud Firestore database instance yet, check out these instructions to create a new instance. Please initialize it in locked mode.

1. Go to the Database tab in the Firebase console.

2. Add a document.

   1. In the Data tab of the console, click Add Collection

   2. Name the collection tryreactfire

   3. Add a document with ID burrito and boolean field yummy: true

   

3. Add security rules to allow access to your burrito document.

   1. In the Rules tab of the console, add the following security rules:

   rules_version = '2';
   service cloud.firestore {
      match /databases/{database}/documents {
        match /tryreactfire/burrito {
          allow read, write: if true;
        }
      }
    }
   

   2. Publish the rules.

2. Create a React App

Prerequisite: make sure you have Node.js installed.

In a terminal, create a fresh React app in a directory of your choice.

npx create-react-app myapp
cd myapp

3. Install ReactFire and the Firebase SDK

Ignore npm warnings.

npm install --save firebase reactfire

4. Register your app with Firebase

1. In the center of the Firebase console's project overview page, click the Web icon to launch the setup workflow.

   If you've already added an app to your Firebase project, click Add app to display the platform options.

2. Enter your app's nickname.

   Note: Firebase Hosting is not required for you to use Firebase products with your web app.

3. Register the app.

4. Copy the Firebase config object. This will be used in Step 5.

5. Continue to Console

5. Add Firebase to index.js

Open the src directory and add code to index.js as described below.

1. Import from the Firebase SDK

   //...
   import { doc, getFirestore } from 'firebase/firestore';
   //...

2. Import from ReactFire

   //...
   import { FirebaseAppProvider, FirestoreProvider, useFirestoreDocData, useFirestore, useFirebaseApp } from 'reactfire';
   //...

3. Add the Firebase config object

   Add the firebaseConfig constant and paste the config object from Step 4.

   //...
   const firebaseConfig = {
     /* Paste your config object from Firebase console here
      */
   };
   //...

4. Wrap your app in a FirebaseAppProvider

   Modify the component passed to the render function.

   //...
   ReactDOM.render(
     <FirebaseAppProvider firebaseConfig={firebaseConfig}>
       <App />
     </FirebaseAppProvider>,
     document.getElementById('root')
   );
   //...

6. Add the Burrito function component to App.js

Open the src directory and add code to App.js as described below.

1. Import from ReactFire

   //...
   import 'firebase/firestore';
   import { useFirestoreDocData, useFirestore } from 'reactfire';
   //...

2. Add a function component

   //...
   function BurritoTaste() {
     // easily access the Firestore library
     const burritoRef = doc(useFirestore(), 'tryreactfire', 'burrito');
   
     // subscribe to a document for realtime updates. just one line!
     const { status, data } = useFirestoreDocData(burritoRef);
   
     // easily check the loading status
     if (status === 'loading') {
       return <p>Fetching burrito flavor...</p>;
     }
   
     return <p>The burrito is {data.yummy ? 'good' : 'bad'}!</p>;
   }
   //...

3. Render your new Burrito component

   Replace the App function with the following:

   //...
   function App() {
     const firestoreInstance = getFirestore(useFirebaseApp());
     return (
       <FirestoreProvider sdk={firestoreInstance}>
         <h1>🌯</h1>
         <BurritoTaste />
       </FirestoreProvider>
     );
   }
   //...

7. Run your app!

1. Run your app.

   yarn start
   
   # or
   
    npm run start

2. Edit the value of yummy in the Database tab in the Firebase console and watch it update in real time in your app! 🔥🔥🔥

Next Steps

The example app in this repository shows a number of ReactFire use cases. The Firestore file demonstrates how to work with lists of data in its AnimalsList component. The Auth file demonstrates how to show a sign in form in its SignInForm component, and shows how to access user details in its UserDetails component. The full example app code can be found here.