Capacitor Firebase Cloud Firestore Plugin

Unofficial Capacitor plugin for Firebase Cloud Firestore.[^1]

Use Cases

The Cloud Firestore plugin is typically used to store and sync app data in the cloud, for example:

• Real-time updates: Keep your UI up to date by listening to document and collection changes with snapshot listeners.
• User-generated content: Create, read, update, and delete documents for user profiles, posts, or other app data.
• Complex queries: Filter and sort collections with composite filters and query constraints such as where, orderBy, and limit.
• Offline support: Enable offline persistence and control network access to work with locally cached data.
• Atomic writes: Perform multiple write operations as a single atomic batch with writeBatch(...).

Compatibility

Guides

• Announcing the Capacitor Firebase Cloud Firestore Plugin
• Capacitor Firestore: Real-Time Data & Offline Sync: Real-time listeners, offline persistence, and atomic writes with this plugin.
• How to Wrap an Angular App with Capacitor and Firebase: Uses this plugin alongside Cloud Storage to store and sync user data.
• How to Use Firebase in a Capacitor App: How the database combines with Authentication, Storage, and the rest of the family in a real app.

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capacitor-firebase/firestore` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capacitor-firebase/firestore
npx cap sync

Add Firebase to your project if you haven't already (Android / iOS / Web).

Android

Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

• $firebaseFirestoreVersion version of com.google.firebase:firebase-firestore (default: 26.0.2)

This can be useful if you encounter dependency conflicts with other plugins in your project.

iOS

Swift Package Manager

Add the following to your capacitor.config.json (or capacitor.config.ts) to avoid a SwiftPM package identity collision:

{
  "experimental": {
    "ios": {
      "spm": {
        "packageOptions": {
          "@capacitor-firebase/firestore": {
            "symlink": true
          }
        }
      }
    }
  }
}

Attention: SPM packageOptions support requires Capacitor CLI 8.4.0+.

Configuration

These configuration values are available:

Examples

In capacitor.config.json:

{
  "plugins": {
    "FirebaseFirestore": {
      "databaseId": undefined
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capacitor-firebase/firestore" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    FirebaseFirestore: {
      databaseId: undefined,
    },
  },
};

export default config;

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Starter templates

The following starter templates are available:

• Ionstarter Angular Firebase

Usage

The following examples show how to create, read, update, and delete documents, update documents with field values, perform batched writes, query collections, control network access, use the Firebase Emulator, and listen for and remove real-time updates.

Create a document

Add a new document to a collection with an auto-generated ID, or write a document at a known reference with setDocument(...). Set merge to true to merge the data with an existing document:

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

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

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

Read a document

Read a single document by its reference:

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

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

Update or delete a document

Update fields of an existing document or delete it entirely:

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

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

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

Update a document with field values

Use FieldValue helpers to increment numbers, set server timestamps, modify arrays, or delete fields:

import { FieldValue, FirebaseFirestore } from '@capacitor-firebase/firestore';

const updateDocumentWithFieldValue = async () => {
  await FirebaseFirestore.updateDocument({
    reference: 'users/Aorq09lkt1ynbR7xhTUx',
    data: {
      born: FieldValue.increment(1),
      updatedAt: FieldValue.serverTimestamp(),
      nicknames: FieldValue.arrayUnion('Prof'),
      tags: FieldValue.arrayRemove('draft'),
      deprecatedField: FieldValue.delete(),
    },
  });
};

Perform a batched write

Execute multiple set, update, and delete operations as a single atomic batch:

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

const writeBatch = async () => {
  await FirebaseFirestore.writeBatch({
    operations: [
      {
        type: 'set',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
        options: { merge: true },
      },
      {
        type: 'update',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
        data: { 
          first: 'Alan', 
          last: 'Turing', 
          born: 1912 
        },
      },
      {
        type: 'delete',
        reference: 'users/Aorq09lkt1ynbR7xhTUx',
      },
    ],
  });
};

Query a collection

Read multiple documents from a collection or a collection group. You can filter the results with a composite filter and apply query constraints such as orderBy and limit:

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;
};

const getCollectionGroup = async () => {
  const { snapshots } = await FirebaseFirestore.getCollectionGroup({
    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;
};

Control network access

Disable and re-enable the use of the network, for example to force the plugin to work with locally cached data:

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

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

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

Use the Firebase Emulator

Connect the plugin to a local Firebase Emulator instance during development:

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

const useEmulator = async () => {
  await FirebaseFirestore.useEmulator({
    host: '10.0.2.2',
    port: 9001,
  });
};

Listen for real-time updates

Attach snapshot listeners to a document, a collection, or a collection group to get notified whenever the data changes:

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',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

const addCollectionGroupSnapshotListener = async () => {
  const callbackId = await FirebaseFirestore.addCollectionGroupSnapshotListener(
    {
      reference: 'users',
      compositeFilter: {
        type: 'and',
        queryConstraints: [
          {
            type: 'where',
            fieldPath: 'born',
            opStr: '==',
            value: 1912,
          },
        ],
      },
      queryConstraints: [
        {
          type: 'orderBy',
          fieldPath: 'born',
          directionStr: 'desc',
        },
        {
          type: 'limit',
          limit: 10,
        },
      ],
    },
    (event, error) => {
      if (error) {
        console.error(error);
      } else {
        console.log(event);
      }
    }
  );
  return callbackId;
};

Remove listeners

Remove a single snapshot listener by its callback ID or remove all listeners at once:

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

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

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

API

• addDocument(...)
• addCollectionGroupSnapshotListener(...)
• addCollectionSnapshotListener(...)
• addDocumentSnapshotListener(...)
• clearPersistence()
• deleteDocument(...)
• disableNetwork()
• disablePersistence()
• enablePersistence(...)
• enableNetwork()
• getCollection(...)
• getCollectionGroup(...)
• getCountFromServer(...)
• getDocument(...)
• removeAllListeners()
• removeSnapshotListener(...)
• setDocument(...)
• updateDocument(...)
• useEmulator(...)
• writeBatch(...)
• Interfaces
• Type Aliases

addDocument(...)

addDocument(options: AddDocumentOptions) => Promise<AddDocumentResult>

Adds a new document to a collection with the given data.

Returns: Promise<AddDocumentResult>

Since: 5.2.0

addCollectionGroupSnapshotListener(...)

addCollectionGroupSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionGroupSnapshotListenerOptions, callback: AddCollectionGroupSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for collection group snapshot events.

Returns: Promise<string>

Since: 6.1.0

addCollectionSnapshotListener(...)

addCollectionSnapshotListener<T extends DocumentData = DocumentData>(options: AddCollectionSnapshotListenerOptions, callback: AddCollectionSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for collection snapshot events.

Returns: Promise<string>

Since: 5.2.0

addDocumentSnapshotListener(...)

addDocumentSnapshotListener<T extends DocumentData = DocumentData>(options: AddDocumentSnapshotListenerOptions, callback: AddDocumentSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for document snapshot events.

Returns: Promise<string>

Since: 5.2.0

clearPersistence()

clearPersistence() => Promise<void>

Clears the persistent storage. This includes pending writes and cached documents.

Attention: Must be called after the app is shutdown or when the app is first initialized.

Since: 5.2.0

deleteDocument(...)

deleteDocument(options: DeleteDocumentOptions) => Promise<void>

Deletes the document referred to by the specified reference.

Since: 5.2.0

disableNetwork()

disableNetwork() => Promise<void>

Disables use of the network.

Since: 5.2.0

disablePersistence()

disablePersistence() => Promise<void>

Disables offline persistence.

Attention: Must be called before any other Firestore method.

Since: 8.2.0

enablePersistence(...)

enablePersistence(options?: EnablePersistenceOptions | undefined) => Promise<void>

Enables offline persistence.

Attention: Must be called before any other Firestore method.

Since: 8.2.0

enableNetwork()

enableNetwork() => Promise<void>

Re-enables use of the network.

Since: 5.2.0

getCollection(...)

getCollection<T extends DocumentData = DocumentData>(options: GetCollectionOptions) => Promise<GetCollectionResult<T>>

Reads the collection referenced by the specified reference.

Returns: Promise<GetCollectionResult<T>>

Since: 5.2.0

getCollectionGroup(...)

getCollectionGroup<T extends DocumentData = DocumentData>(options: GetCollectionGroupOptions) => Promise<GetCollectionGroupResult<T>>

Reads the collection group referenced by the specified reference.

Returns: Promise<GetCollectionGroupResult<T>>

getCountFromServer(...)

getCountFromServer(options: GetCountFromServerOptions) => Promise<GetCountFromServerResult>

Fetches the number of documents in a collection.

Returns: Promise<GetCountFromServerResult>

Since: 6.4.0

getDocument(...)

getDocument<T extends DocumentData = DocumentData>(options: GetDocumentOptions) => Promise<GetDocumentResult<T>>

Reads the document referred to by the specified reference.

Returns: Promise<GetDocumentResult<T>>

Since: 5.2.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 5.2.0

removeSnapshotListener(...)

removeSnapshotListener(options: RemoveSnapshotListenerOptions) => Promise<void>

Remove a listener for document or collection snapshot events.

Since: 5.2.0

setDocument(...)

setDocument(options: SetDocumentOptions) => Promise<void>

Writes to the document referred to by the specified reference. If the document does not yet exist, it will be created.

Since: 5.2.0

updateDocument(...)

updateDocument(options: UpdateDocumentOptions) => Promise<void>

Updates fields in the document referred to by the specified reference.

Since: 5.2.0

useEmulator(...)

useEmulator(options: UseEmulatorOptions) => Promise<void>

Instrument your app to talk to the Firestore emulator.

Since: 6.1.0

writeBatch(...)

writeBatch(options: WriteBatchOptions) => Promise<void>

Execute multiple write operations as a single batch.

Since: 6.1.0

Interfaces

AddDocumentResult

AddDocumentOptions

DocumentData

AddCollectionGroupSnapshotListenerOptions

QueryCompositeFilterConstraint

QueryFieldFilterConstraint

QueryOrderByConstraint

QueryLimitConstraint

QueryStartAtConstraint

QueryEndAtConstraint

GetCollectionGroupResult

DocumentSnapshot

SnapshotMetadata

AddCollectionSnapshotListenerOptions

GetCollectionResult

AddDocumentSnapshotListenerOptions

GetDocumentResult

DeleteDocumentOptions

EnablePersistenceOptions

GetCollectionOptions

GetCollectionGroupOptions

GetCountFromServerResult

GetCountFromServerOptions

GetDocumentOptions

RemoveSnapshotListenerOptions

SetDocumentOptions

UpdateDocumentOptions

UseEmulatorOptions

WriteBatchOptions

WriteBatchOperation

SetOptions

Type Aliases

QueryFilterConstraint

QueryFieldFilterConstraint | QueryCompositeFilterConstraint

QueryOperator

'<' | '<=' | '==' | '>=' | '>' | '!=' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in'

QueryNonFilterConstraint

QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint

OrderByDirection

'desc' | 'asc'

AddCollectionGroupSnapshotListenerCallback

(event: AddCollectionGroupSnapshotListenerCallbackEvent<T> | null, error: any): void

AddCollectionGroupSnapshotListenerCallbackEvent

GetCollectionGroupResult<T>

CallbackId

string

AddCollectionSnapshotListenerCallback

(event: AddCollectionSnapshotListenerCallbackEvent<T> | null, error: any): void

AddCollectionSnapshotListenerCallbackEvent

GetCollectionResult<T>

AddDocumentSnapshotListenerCallback

(event: AddDocumentSnapshotListenerCallbackEvent<T> | null, error: any): void

AddDocumentSnapshotListenerCallbackEvent

GetDocumentResult<T>

FAQ

How do I get notified about data changes in real time?

Attach a snapshot listener with addDocumentSnapshotListener(...), addCollectionSnapshotListener(...), or addCollectionGroupSnapshotListener(...). The callback is invoked whenever the observed data changes. Each listener returns a callback ID that you can later pass to removeSnapshotListener(...), or you can remove all listeners at once with removeAllListeners(). See Listen for real-time updates for an example.

What is the difference between getCollection and getCollectionGroup?

The getCollection(...) method reads the documents of a single collection at the given reference. The getCollectionGroup(...) method reads the documents of a collection group, which consists of all collections with the same ID. Both methods support composite filters and query constraints.

Does the plugin work offline?

Yes, you can enable offline persistence with the enablePersistence(...) method, which must be called before any other Firestore method. You can also disable and re-enable the use of the network with disableNetwork() and enableNetwork(). The persistent storage, including pending writes and cached documents, can be cleared with clearPersistence(), which must be called after the app is shut down or when it is first initialized.

Can I use a Firestore database other than the default one?

Yes, you can set the databaseId configuration option in your Capacitor configuration to select the Firestore database to use (see Configuration). This option is only available on Android and iOS.

How do I test my app against a local Firestore instance?

Use the useEmulator(...) method to connect the plugin to a local Firebase Emulator instance by providing its host and port. This allows you to develop and test without touching your production data.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• Firebase Authentication: Unofficial Capacitor plugin for Firebase Authentication.
• Firebase Cloud Functions: Unofficial Capacitor plugin for Firebase Cloud Functions.
• Firebase Cloud Storage: Unofficial Capacitor plugin for Firebase Cloud Storage.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.