This module requires that the @react-native-firebase/app module is already setup and installed. To install the "app" module, view the Getting Started documentation.

# Install & setup the app module
yarn add @react-native-firebase/app

# Install the firestore module
yarn add @react-native-firebase/firestore

# If you're developing your app using iOS, run this command
cd ios/ && pod install

If you're using an older version of React Native without autolinking support, or wish to integrate into an existing project, you can follow the manual installation steps for iOS and Android.

If you have started to receive a app:mergeDexDebug error after adding Cloud Firestore, please read the Enabling Multidex documentation for more information on how to resolve this error.

Platform notes: IndexedDB persistence and memoryLocalCache / persistentLocalCache are web only. Native persistence is controlled by the iOS/Android Firestore SDK. initializeFirestore is async on React Native.

Firestore is a flexible, scalable NoSQL cloud database to store and sync data. It keeps your data in sync across client apps through realtime listeners and offers offline support so you can build responsive apps that work regardless of network latency or Internet connectivity.

Cloud Firestore stores data within "documents", which are contained within "collections", and documents can also contain collections. For example, we could store a list of our users documents within a "Users" collection. The collection function allows us to reference a collection within our code:

import { collection, getFirestore } from '@react-native-firebase/firestore';

const db = getFirestore();
const usersCollection = collection(db, 'Users');

The collection function returns a CollectionReference class, which provides properties and methods to query and fetch the data from Cloud Firestore. We can also directly reference a single document on the collection by calling the doc function:

import { collection, doc, getFirestore } from '@react-native-firebase/firestore';

const db = getFirestore();

// Get user document with an ID of ABC
const userDocument = doc(collection(db, 'Users'), 'ABC');

The doc function returns a DocumentReference.

A document can contain different types of data, including scalar values (strings, booleans, numbers), arrays (lists) and objects (maps) along with specific Cloud Firestore data such as Timestamps, GeoPoints, Bytes and more.

Cloud Firestore provides the ability to read the value of a collection or document. This can be read one-time, or provide realtime updates when the data within a query changes.

To read a collection or document once, call getDocs on a CollectionReference or getDoc on a DocumentReference:

import { collection, doc, getDoc, getDocs, getFirestore } from '@react-native-firebase/firestore';

const db = getFirestore();
const users = await getDocs(collection(db, 'Users'));
const user = await getDoc(doc(collection(db, 'Users'), 'ABC'));

To setup an active listener to react to any changes to the query, call onSnapshot with an event handler callback. For example, to watch the entire "Users" collection for when any documents are changed (removed, added, modified):

import { collection, getFirestore, onSnapshot } from '@react-native-firebase/firestore';

const db = getFirestore();

function onResult(QuerySnapshot) {
  console.log('Got Users collection result.');
}

function onError(error) {
  console.error(error);
}

onSnapshot(collection(db, 'Users'), onResult, onError);

onSnapshot also returns a function, allowing you to unsubscribe from events. This can be used within any useEffect hooks to automatically unsubscribe when the hook needs to unsubscribe itself:

import React, { useEffect } from 'react';
import { collection, doc, getFirestore, onSnapshot } from '@react-native-firebase/firestore';

const db = getFirestore();

function User({ userId }) {
  useEffect(() => {
    const subscriber = onSnapshot(doc(collection(db, 'Users'), userId), documentSnapshot => {
      console.log('User data: ', documentSnapshot.data());
    });

    // Stop listening for updates when no longer required
    return () => subscriber();
  }, [userId]);
}

Realtime changes via onSnapshot can be applied to both collections and documents.

Once a query has returned a result, Firestore returns either a QuerySnapshot (for collection queries) or a DocumentSnapshot (for document queries). These snapshots provide the ability to view the data, view query metadata (such as whether the data was from local cache), whether the document exists or not and more.

A QuerySnapshot returned from a collection query allows you to inspect the collection, such as how many documents exist within it, access to the documents within the collection, any changes since the last query and more.

To access the documents within a QuerySnapshot, call the forEach method:

import { collection, getDocs, getFirestore } from '@react-native-firebase/firestore';

const db = getFirestore();

getDocs(collection(db, 'Users')).then(querySnapshot => {
  console.log('Total users: ', querySnapshot.size);

  querySnapshot.forEach(documentSnapshot => {
    console.log('User ID: ', documentSnapshot.id, documentSnapshot.data());
  });
});

Each child document of a QuerySnapshot is a QueryDocumentSnapshot, which allows you to access specific information about a document (see below).

A DocumentSnapshot is returned from a query to a specific document, or as part of the documents returned via a QuerySnapshot. The snapshot provides the ability to view a documents data, metadata and whether a document actually exists.

To view a documents data, call the data method on the snapshot:

import { collection, doc, getDoc, getFirestore } from '@react-native-firebase/firestore';

const db = getFirestore();

getDoc(doc(collection(db, 'Users'), 'ABC')).then(documentSnapshot => {
  console.log('User exists: ', documentSnapshot.exists);

  if (documentSnapshot.exists) {
    console.log('User data: ', documentSnapshot.data());
  }
});

A snapshot also provides a helper function to easily access deeply nested data within a document. Call the get method with a dot-notated path:

import { collection, doc, getDoc, getFirestore } from '@react-native-firebase/firestore';

const db = getFirestore();

function getUserZipCode(documentSnapshot) {
  return documentSnapshot.get('info.address.zipcode');
}

getDoc(doc(collection(db, 'Users'), 'ABC'))
  .then(documentSnapshot => getUserZipCode(documentSnapshot))
  .then(zipCode => {
    console.log('Users zip code is: ', zipCode);
  });

Cloud Firestore offers advanced capabilities for querying collections.

To filter documents within a collection, pass where constraints to query. Filtering supports equality checks and "in" queries. For example, to filter users where their age is greater or equal than 18 years old:

import { collection, getDocs, getFirestore, query, where } from '@react-native-firebase/firestore';

const db = getFirestore();

getDocs(query(collection(db, 'Users'), where('age', '>=', 18))).then(querySnapshot => {
  /* ... */
});

Cloud Firestore also supports array membership queries. For example, to filter users who speak both English (en) or French (fr), use the in filter:

getDocs(query(collection(db, 'Users'), where('languages', 'in', ['en', 'fr']))).then(
  querySnapshot => {
    /* ... */
  },
);

To learn more about all of the querying capabilities Cloud Firestore has to offer, view the Firebase documentation.

You can combine multiple filters using and() and or() composite constraints. For example:

import {
  and,
  collection,
  getDocs,
  getFirestore,
  or,
  query,
  where,
} from '@react-native-firebase/firestore';

const db = getFirestore();

const snapshot = await getDocs(
  query(
    collection(db, 'Users'),
    where('user', '==', 'Tim'),
    where('email', '==', 'tim@example.com'),
  ),
);

You can use the and() function to make logical AND queries:

const snapshot = await getDocs(
  query(
    collection(db, 'Users'),
    and(where('user', '==', 'Tim'), where('email', '==', 'tim@example.com')),
  ),
);

You can use the or() function to make logical OR queries:

const snapshot = await getDocs(
  query(
    collection(db, 'Users'),
    or(
      and(where('user', '==', 'Tim'), where('email', '==', 'tim@example.com')),
      and(where('user', '==', 'Dave'), where('email', '==', 'dave@example.com')),
    ),
  ),
);

For an understanding of what queries are possible, please consult the query limitation documentation on the official Firebase Firestore documentation.

To limit the number of documents returned from a query, use the limit constraint:

import {
  collection,
  getDocs,
  getFirestore,
  limit,
  query,
  where,
} from '@react-native-firebase/firestore';

const db = getFirestore();

getDocs(query(collection(db, 'Users'), where('age', '>=', 18), limit(20))).then(querySnapshot => {
  /* ... */
});

The above example both filters the users by age and limits the documents returned to 20.

To order the documents by a specific value, use the orderBy constraint:

import {
  collection,
  getDocs,
  getFirestore,
  orderBy,
  query,
} from '@react-native-firebase/firestore';

const db = getFirestore();

getDocs(query(collection(db, 'Users'), orderBy('age', 'desc'))).then(querySnapshot => {
  /* ... */
});

The above example orders all user in the snapshot by age in descending order.

To start and/or end the query at a specific point within the collection, you can pass either a value to startAt, endAt, startAfter or endBefore. You must specify an order to use pointers, for example:

import {
  collection,
  endAt,
  getDocs,
  getFirestore,
  orderBy,
  query,
  startAt,
} from '@react-native-firebase/firestore';

const db = getFirestore();

getDocs(query(collection(db, 'Users'), orderBy('age', 'desc'), startAt(18), endAt(30))).then(
  querySnapshot => {
    /* ... */
  },
);

The above query orders the users by age in descending order, but only returns users whose age is between 18 and 30.

You can further specify a DocumentSnapshot instead of a specific value. For example:

import {
  collection,
  doc,
  getDoc,
  getDocs,
  getFirestore,
  orderBy,
  query,
  startAt,
} from '@react-native-firebase/firestore';

const db = getFirestore();
const userDocumentSnapshot = await getDoc(doc(collection(db, 'Users'), 'DEF'));

getDocs(query(collection(db, 'Users'), orderBy('age', 'desc'), startAt(userDocumentSnapshot))).then(
  querySnapshot => {
    /* ... */
  },
);

The above query orders the users by age in descending order, however only returns documents whose order starts at the user with an ID of DEF.

Cloud Firestore does not support the following types of queries:

• Queries with range filters on different fields, as described in the previous section.

The Firebase documentation provides great examples on best practices on how to structure your data. We highly recommend reading the guide before building out your database.

For a more in-depth look at what is possible when writing data to Firestore please refer to this documentation

To add a new document to a collection, use addDoc with a CollectionReference:

import { addDoc, collection, getFirestore } from '@react-native-firebase/firestore';

const db = getFirestore();

addDoc(collection(db, 'Users'), {
  name: 'Ada Lovelace',
  age: 30,
}).then(() => {
  console.log('User added!');
});

addDoc adds the new document to your collection with a random unique ID. If you'd like to specify your own ID, call setDoc with a DocumentReference instead:

import { collection, doc, getFirestore, setDoc } from '@react-native-firebase/firestore';

const db = getFirestore();

setDoc(doc(collection(db, 'Users'), 'ABC'), {
  name: 'Ada Lovelace',
  age: 30,
}).then(() => {
  console.log('User added!');
});

The setDoc example above replaces any existing data on a given DocumentReference. if you'd like to update a document instead, use updateDoc:

import { collection, doc, getFirestore, updateDoc } from '@react-native-firebase/firestore';

const db = getFirestore();

updateDoc(doc(collection(db, 'Users'), 'ABC'), {
  age: 31,
}).then(() => {
  console.log('User updated!');
});

The method also provides support for updating deeply nested values via dot-notation:

import { collection, doc, getFirestore, updateDoc } from '@react-native-firebase/firestore';

const db = getFirestore();

updateDoc(doc(collection(db, 'Users'), 'ABC'), {
  'info.address.zipcode': 94040,
}).then(() => {
  console.log('User updated!');
});

Cloud Firestore supports storing and manipulating values on your database, such as Timestamps, GeoPoints, Bytes and array management.

To store GeoPoint values, provide the latitude and longitude to a new instance of the class:

import { doc, GeoPoint, getFirestore, updateDoc } from '@react-native-firebase/firestore';

const db = getFirestore();

updateDoc(doc(db, 'users', 'ABC'), {
  'info.address.location': new GeoPoint(53.483959, -2.244644),
});

To store raw Bytes (for example of a Base64 image string), provide the string to the static fromBase64String method on the class:

import { Bytes, doc, getFirestore, updateDoc } from '@react-native-firebase/firestore';

const db = getFirestore();

updateDoc(doc(db, 'users', 'ABC'), {
  'info.avatar': Bytes.fromBase64String('data:image/png;base64,iVBOR...'),
});

When storing timestamps, it is recommended you use serverTimestamp(). When written to the database, the Firebase servers will write a new timestamp based on their time, rather than the clients. This helps resolve any data consistency issues with different client timezones:

import { doc, getFirestore, serverTimestamp, updateDoc } from '@react-native-firebase/firestore';

const db = getFirestore();

updateDoc(doc(db, 'users', 'ABC'), {
  createdAt: serverTimestamp(),
});

Cloud Firestore also allows for storing arrays. To help manage the values with an array (adding or removing), the API exposes arrayUnion and arrayRemove helpers.

To add a new value to an array (if value does not exist, will not add duplicate values):

import { arrayUnion, doc, getFirestore, updateDoc } from '@react-native-firebase/firestore';

const db = getFirestore();

updateDoc(doc(db, 'users', 'ABC'), {
  fcmTokens: arrayUnion('ABCDE123456'),
});

To remove a value from the array (if the value exists):

import { arrayRemove, doc, getFirestore, updateDoc } from '@react-native-firebase/firestore';

const db = getFirestore();

updateDoc(doc(db, 'users', 'ABC'), {
  fcmTokens: arrayRemove('ABCDE123456'),
});

You can delete documents within Cloud Firestore using the deleteDoc method with a DocumentReference:

import { deleteDoc, doc, getFirestore } from '@react-native-firebase/firestore';

const userDocRef = doc(getFirestore(), 'users/ExampleUser');
deleteDoc(userDocRef).then(() => {
  console.log('User deleted!');
});

At this time, you cannot delete an entire collection without use of a Firebase Admin SDK.

If a document contains any sub-collections, these will not be deleted from database. You must delete any sub-collections yourself.

If you need to remove a specific property with a document, rather than the document itself, you can use deleteField:

import {
  collection,
  deleteField,
  doc,
  getFirestore,
  updateDoc,
} from '@react-native-firebase/firestore';

const db = getFirestore();

updateDoc(doc(collection(db, 'Users'), 'ABC'), {
  fcmTokens: deleteField(),
});

Transactions are a way to always ensure a write occurs with the latest information available on the server. Transactions never partially apply writes & all writes execute at the end of a successful transaction.

Transactions are useful when you want to update a field's value based on its current value, or the value of some other field. If you simply want to write multiple documents without using the document's current state, a batch write would be more appropriate.

When using transactions, note that:

• Read operations must come before write operations.
• A function calling a transaction (transaction function) might run more than once if a concurrent edit affects a document that the transaction reads.
• Transaction functions should not directly modify application state (return a value from the updateFunction).
• Transactions will fail when the client is offline.

Imagine a scenario whereby an app has the ability to "Like" user posts. Whenever a user presses the "Like" button, a "likes" value (number of likes) on a "Posts" collection document increments. Without transactions, we'd first need to read the existing value and then increment that value in two separate operations.

On a high traffic application, the value on the server could already have changed by the time the operation sets a new value, causing the actual number to not be consistent.

Transactions remove this issue by atomically updating the value on the server. If the value changes whilst the transaction is executing, it will retry. This always ensures the value on the server is used rather than the client value.

To execute a new transaction, call runTransaction:

import { doc, getFirestore, runTransaction } from '@react-native-firebase/firestore';

const db = getFirestore();

function onPostLike(postId) {
  // Create a reference to the post
  const postReference = doc(db, 'posts', postId);

  return runTransaction(db, async transaction => {
    // Get post data first
    const postSnapshot = await transaction.get(postReference);

    if (!postSnapshot.exists) {
      throw 'Post does not exist!';
    }

    transaction.update(postReference, {
      likes: postSnapshot.data().likes + 1,
    });
  });
}

onPostLike('ABC')
  .then(() => console.log('Post likes incremented via a transaction'))
  .catch(error => console.error(error));

If you do not need to read any documents in your operation set, you can execute multiple write operations as a single batch that contains any combination of setDoc, updateDoc, or deleteDoc operations. A batch of writes completes atomically and can write to multiple documents.

First, create a new batch instance via writeBatch, perform operations on the batch and finally commit it once ready. The example below shows how to delete all documents in a collection in a single operation:

import { collection, getDocs, getFirestore, writeBatch } from '@react-native-firebase/firestore';

const db = getFirestore();

async function massDeleteUsers() {
  // Get all users
  const usersQuerySnapshot = await getDocs(collection(db, 'Users'));

  // Create a new batch instance
  const batch = writeBatch(db);

  usersQuerySnapshot.forEach(documentSnapshot => {
    batch.delete(documentSnapshot.ref);
  });

  return batch.commit();
}

massDeleteUsers().then(() => console.log('All users deleted in a single batch operation.'));

It is important that you understand how to write rules in your Firebase console to ensure that your data is secure. Please follow the Firebase Firestore documentation on security.

Firestore provides out of the box support for offline capabilities. When reading and writing data, Firestore uses a local database which synchronizes automatically with the server. Firestore functionality continues when users are offline, and automatically handles data migration to the server when they regain connectivity.

This functionality is enabled by default, however it can be disabled if you need it to be disabled (e.g. on apps containing sensitive information). initializeFirestore must be called before any Firestore interaction is performed, otherwise it will only take effect on the next app launch:

import { getApp } from '@react-native-firebase/app';
import { initializeFirestore } from '@react-native-firebase/firestore';

async function bootstrap() {
  await initializeFirestore(getApp(), {
    persistence: false, // disable offline persistence
  });
}

Cloud Firestore data bundles are static data files built by you from Cloud Firestore document and query snapshots, and published by you on a CDN, hosting service or other solution. Once a bundle is loaded, a client app can query documents from the local cache or the backend.

To load and query data bundles, use loadBundle and namedQuery:

import {
  getDocsFromCache,
  getFirestore,
  loadBundle,
  namedQuery,
} from '@react-native-firebase/firestore';

const db = getFirestore();

// load the bundle contents
const response = await fetch('https://api.example.com/bundles/latest-stories');
const bundle = await response.text();
await loadBundle(db, bundle);

// query the results from the cache
// note: use getDocsFromCache to query the local cache only
const storiesQuery = await namedQuery(db, 'latest-stories-query');
if (storiesQuery) {
  const snapshot = await getDocsFromCache(storiesQuery);
}

You can build data bundles with the Admin SDK. For more information about building and serving data bundles, see Firebase Firestore main documentation on Data bundles as well as their "Bundle Solutions" page