---
title: Announcing the Capacitor Firebase Firestore Plugin
description: Unofficial Capacitor plugin for Firebase Cloud Firestore to use the Android and iOS SDKs in your Capacitor project.
date: 
  created: 2023-10-17
  updated: 2023-10-17
authors:
  - robingenz
categories:
  - Announcements
  - Capacitor
  - SDKs
links:
  - Capacitor Firebase Cloud Firestore: sdks/capacitor/firebase/cloud-firestore.md
sponsor:
  name: AppScreens
  image: /docs/assets/images/sponsors/appscreens-logo.png
  url: https://appscreens.com/?_locale=en&utm_source=capawesome&utm_medium=referral&utm_campaign=capawesome&gclid=capawesome
---

# Announcing the Capacitor Firebase Cloud Firestore Plugin

Today we are excited to announce the release of the [Capacitor Firebase Cloud Firestore plugin](../../sdks/capacitor/firebase/cloud-firestore.md), sponsored by [AppScreens](https://appscreens.com/?_locale=en&utm_source=capawesome&utm_medium=referral&utm_campaign=capawesome&gclid=capawesome){:target="_blank"}. 
This plugin allows you to use the Android and iOS SDKs for [Firebase Cloud Firestore](https://firebase.google.com/docs/firestore){:target="_blank"} in your Capacitor project.

<!-- more -->

Until now, it was necessary to use the Firebase JavaScript SDK on Android and iOS as well to use Cloud Firestore.
However, this had some drawbacks, such as the need for additional authentication of users in the web layer and degraded performance.
The Capacitor Firebase Cloud Firestore plugin addresses these drawbacks by providing a native implementation for Android and iOS.

<figure markdown>
  ![Demo](./announcing-the-capacitor-firebase-cloud-firestore-plugin/1bb26bb3-308a-4062-aef1-7c49e983d8fe.gif)
  <figcaption>Demo</figcaption>
</figure>

Let's take a quick look at the [Capacitor Firebase Cloud Firestore API](../../sdks/capacitor/firebase/cloud-firestore.md#api) and how you can add, get and delete data from your database.

## Installation

Run the following commands to install the plugin:

```bash
npm install @capacitor-firebase/firestore
npx cap sync
```

You also need to [add Firebase to your project](https://github.com/capawesome-team/capacitor-firebase/blob/main/docs/firebase-setup.md){:target="_blank"} if you haven't already.

## Usage

If you are new to Cloud Firestore, we recommend that you first read the [Understand Cloud Firestore](https://firebase.google.com/docs/firestore){:target="_blank"} section so that you are familiar with the basics.
Let's see the plugin in action.

### Add data

There are several ways to write data to Cloud Firestore.
One way is to add a new document to a collection with an automatically generated document identifier using the [addDocument(...)](../../sdks/capacitor/firebase/cloud-firestore.md#adddocument) method:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const addDocument = async () => {
  const { reference } = await FirebaseFirestore.addDocument({
    reference: 'users',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
  });
  return reference.id;
};
```

In this case we add a new document with the data `{ first: 'Alan', last: 'Turing', born: 1912 }` to the collection `users`.

Another way is to set the content of a document within a collection by explicitly specifying a document identifier using the [setDocument(...)](../../sdks/capacitor/firebase/cloud-firestore.md#setdocument) method:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const setDocument = async () => {
  await FirebaseFirestore.setDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: { 
      first: 'Alan', 
      last: 'Turing', 
      born: 1912 
    },
    merge: true,
  });
};
```

Use `{ merge: boolean }` to specify whether the newly provided data should overwrite the content of the document or be merged with the existing document.

### Get data

To retrieve a single document from a collection, you can use the [`getDocument(...)`](../../sdks/capacitor/firebase/cloud-firestore.md#getdocument) method:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const getDocument = async () => {
  const { snapshot } = await FirebaseFirestore.getDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
  return snapshot;
};
```

You just need to pass the document reference as a string, with path components separated by a forward slash (`/`).

To retrieve multiple documents from a collection, you can use the [`getCollection(...)`](../../sdks/capacitor/firebase/cloud-firestore.md#getcollection) method:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const getCollection = async () => {
  const { snapshots } = await FirebaseFirestore.getCollection({
    reference: 'users',
    compositeFilter: {
      type: 'and',
      queryConstraints: [
        {
          type: 'where',
          fieldPath: 'born',
          opStr: '==',
          value: 1912,
        },
      ],
    },
    queryConstraints: [
      {
        type: 'orderBy',
        fieldPath: 'born',
        directionStr: 'desc',
      },
      {
        type: 'limit',
        limit: 10,
      },
    ],
  });
  return snapshots;
};
```

This method allows you to apply filters and sorting to the query.
It is recommended that you specify the `type` property first, so that TypeScript will list the remaining properties for you.

### Delete data

To delete a document from a collection, you can use the [`deleteDocument(...)`](../../sdks/capacitor/firebase/cloud-firestore.md#deletedocument) method:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const deleteDocument = async () => {
  await FirebaseFirestore.deleteDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
  });
};
```

Again you just need to pass the document reference as a string, with path components separated by a forward slash (`/`).

### Get real-time updates

If you want to get real-time updates when documents change, you can use the [`addDocumentSnapshotListener(...)`](../../sdks/capacitor/firebase/cloud-firestore.md#adddocumentsnapshotlistener) and [`addCollectionSnapshotListener(...)`](../../sdks/capacitor/firebase/cloud-firestore.md#addcollectionsnapshotlistener) methods:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';


const addDocumentSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addDocumentSnapshotListener(
    {
      reference: 'users/Aorq09lkt1ynbR7xhTUx',
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionSnapshotListener(
    {
      reference: 'users',
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};
```

The callback function will be called every time the document or collection changes.
To remove the listener, you have to call the [`removeSnapshotListener(...)`](../../sdks/capacitor/firebase/cloud-firestore.md#removesnapshotlistener) or [`removeAllListeners()`](../../sdks/capacitor/firebase/cloud-firestore.md#removealllisteners) methods:

```typescript
import { FirebaseFirestore } from '@capacitor-firebase/firestore';

const removeSnapshotListener = async (callbackId: string) => {
  await FirebaseFirestore.removeSnapshotListener({
    callbackId,
  });
};

const removeAllListeners = async () => {
  await FirebaseFirestore.removeAllListeners();
};
```

## Limitations

Currently, there are still a few limitations that you need to be aware of:

1. **Data types**: The supported data types are those that can be represented in JSON such as numbers, strings, booleans, arrays, and objects. Something that is not currently supported is, for example, the JavaScript `Date` object. However, you can just pass the `Date` as a `string` by using the `toISOString()` method:
  ```js
  // Create a string representation of the current date based on ISO 8601
  const dateString = new Date().toISOString();
  // Create a new date object from the string
  const date = new Date(dateString);
  ```
1. **Field values**: Firestore supports various field values such as `FieldValue.delete()`, `FieldValue.increment()` or `FieldValue.serverTimestamp()`. However, these will not be supported until the next release (see [capacitor-firebase/issues/443](https://github.com/capawesome-team/capacitor-firebase/issues/443){:target="_blank"}).

## Closing Thoughts

Be sure to check out our [API Reference](../../sdks/capacitor/firebase/cloud-firestore.md#api) to see what else you can do with this plugin. 
Also feel free to check out our base sponsor [AppScreens](https://appscreens.com/?_locale=en&utm_source=capawesome&utm_medium=referral&utm_campaign=capawesome&gclid=capawesome){:target="_blank"} - a dedicated screenshot mockup generator for app developers.

## Related Posts

- [Capacitor Firestore: Real-Time Data & Offline Sync](./capacitor-firebase-cloud-firestore-guide.md)
- [What's New in Capacitor Firebase 8.3.0](./capacitor-firebase-8-3-0-release.md)
- [Capacitor Push Notifications: The Complete Guide](./capacitor-push-notifications-guide.md)
- [How to Wrap an Angular App with Capacitor and Firebase](./how-to-wrap-an-angular-app-with-capacitor-and-firebase.md)