@capacitor-firebase/firestore

Unofficial Capacitor plugin for Firebase Cloud Firestore.¹

Guides

• Announcing the Capacitor Firebase Cloud Firestore Plugin

Newsletter

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

Compatibility

Plugin Version	Capacitor Version	Status
8.x.x	>=8.x.x	Active support
7.x.x	7.x.x	Deprecated
6.x.x	6.x.x	Deprecated

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.

Configuration

These configuration values are available:

Prop	Type	Description	Since
databaseId	string	The database ID of the Firestore database to use. Only available for Android and iOS.	8.2.0

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

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

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

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',
  });
};

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',
      },
    ],
  });
};

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

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

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

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

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

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.

Param	Type
options	AddDocumentOptions

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.

Param	Type
options	AddCollectionGroupSnapshotListenerOptions
callback	AddCollectionGroupSnapshotListenerCallback<T>

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.

Param	Type
options	AddCollectionSnapshotListenerOptions
callback	AddCollectionSnapshotListenerCallback<T>

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.

Param	Type
options	AddDocumentSnapshotListenerOptions
callback	AddDocumentSnapshotListenerCallback<T>

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.

Param	Type
options	DeleteDocumentOptions

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.

Param	Type
options	EnablePersistenceOptions

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.

Param	Type
options	GetCollectionOptions

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.

Param	Type
options	GetCollectionGroupOptions

Returns: Promise<GetCollectionGroupResult<T>>

---

getCountFromServer(...)

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

Fetches the number of documents in a collection.

Param	Type
options	GetCountFromServerOptions

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.

Param	Type
options	GetDocumentOptions

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.

Param	Type
options	RemoveSnapshotListenerOptions

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.

Param	Type
options	SetDocumentOptions

Since: 5.2.0

---

updateDocument(...)

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

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

Param	Type
options	UpdateDocumentOptions

Since: 5.2.0

---

useEmulator(...)

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

Instrument your app to talk to the Firestore emulator.

Param	Type
options	UseEmulatorOptions

Since: 6.1.0

---

writeBatch(...)

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

Execute multiple write operations as a single batch.

Param	Type
options	WriteBatchOptions

Since: 6.1.0

---

Interfaces

AddDocumentResult

Prop	Type	Description	Since
reference	DocumentReference	The reference of the newly added document.	5.2.0

DocumentReference

Prop	Type	Description	Since
id	string	The document's identifier within its collection.	5.2.0
path	string	The path of the document.	5.2.0

AddDocumentOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.2.0
data	DocumentData	An object containing the data for the new document.	5.2.0

DocumentData

AddCollectionGroupSnapshotListenerOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	6.1.0
compositeFilter	QueryCompositeFilterConstraint	The filter to apply.	6.1.0
queryConstraints	QueryNonFilterConstraint[]	Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields.	6.1.0

QueryCompositeFilterConstraint

Prop	Type	Description	Since
type	'and' | 'or'	The type of the constraint.	5.2.0
queryConstraints	QueryFilterConstraint[]	The filters to apply.	5.2.0

QueryFieldFilterConstraint

Prop	Type	Description	Since
type	'where'	The type of the constraint.	5.2.0
fieldPath	string	The path to compare.	5.2.0
opStr	QueryOperator	The operation string to apply.	5.2.0
value	any	The value for comparison.	5.2.0

QueryOrderByConstraint

Prop	Type	Description	Since
type	'orderBy'	The type of the constraint.	5.2.0
fieldPath	string	The path to compare.	5.2.0
directionStr	OrderByDirection	The direction to sort by.	5.2.0

QueryLimitConstraint

Prop	Type	Description	Since
type	'limit' | 'limitToLast'	The type of the constraint.	5.2.0
limit	number	The maximum number of items to return.	5.2.0

QueryStartAtConstraint

Prop	Type	Description	Since
type	'startAt' | 'startAfter'	The type of the constraint.	5.2.0
reference	string	The reference to start at or after as a string, with path components separated by a forward slash (/). Attention: This requires an additional document read.	5.2.0

QueryEndAtConstraint

Prop	Type	Description	Since
type	'endAt' | 'endBefore'	The type of the constraint.	5.2.0
reference	string	The reference as to end at or before as a string, with path components separated by a forward slash (/). Attention: This requires an additional document read.	5.2.0

GetCollectionGroupResult

Prop	Type	Description	Since
snapshots	DocumentSnapshot<T>[]	The documents in the collection.	5.2.0

DocumentSnapshot

Prop	Type	Description	Since
id	string	The document's identifier within its collection.	5.2.0
path	string	The path of the document.	5.2.0
data	T | null	An object containing the data for the document. Returns null if the document doesn't exist.	5.2.0
metadata	SnapshotMetadata	Metadata about the snapshot, concerning its source and if it has local modifications.	6.2.0

SnapshotMetadata

Prop	Type	Description	Since
fromCache	boolean	True if the snapshot was created from cached data.	6.2.0
hasPendingWrites	boolean	True if the snapshot was created from pending write data.	6.2.0

AddCollectionSnapshotListenerOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.2.0
compositeFilter	QueryCompositeFilterConstraint	The filter to apply.	5.2.0
queryConstraints	QueryNonFilterConstraint[]	Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields.	5.2.0

GetCollectionResult

Prop	Type	Description	Since
snapshots	DocumentSnapshot<T>[]	The documents in the collection.	5.2.0

AddDocumentSnapshotListenerOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.2.0

GetDocumentResult

Prop	Type	Description	Since
snapshot	DocumentSnapshot<T>	The current document contents.	5.2.0

DeleteDocumentOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.2.0

EnablePersistenceOptions

Prop	Type	Description	Default	Since
cacheSizeBytes	number	The cache size in bytes.	104857600 (100 MB)	8.2.0
synchronizeTabs	boolean	Whether to synchronize persistence across multiple tabs. Only available for Web.	false	8.2.0

GetCollectionOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.2.0
compositeFilter	QueryCompositeFilterConstraint	The filter to apply.	5.2.0
queryConstraints	QueryNonFilterConstraint[]	Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields.	5.2.0

GetCollectionGroupOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.2.0
compositeFilter	QueryCompositeFilterConstraint	The filter to apply.	5.2.0
queryConstraints	QueryNonFilterConstraint[]	Narrow or order the set of documents to retrieve, but do not explicitly filter for document fields.	5.2.0

GetCountFromServerResult

Prop	Type	Description	Since
count	number	The number of documents in the collection.	6.4.0

GetCountFromServerOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	6.4.0

GetDocumentOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.2.0

RemoveSnapshotListenerOptions

Prop	Type	Since
callbackId	CallbackId	5.2.0

SetDocumentOptions

Prop	Type	Description	Default	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).		5.2.0
data	DocumentData	An object containing the data for the new document.		5.2.0
merge	boolean	Whether to merge the provided data with an existing document.	false	5.2.0

UpdateDocumentOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.2.0
data	DocumentData	An object containing the data for the new document.	5.2.0

UseEmulatorOptions

Prop	Type	Description	Default	Since
host	string	The emulator host without any port or scheme. Note when using a Android Emulator device: 10.0.2.2 is the special IP address to connect to the 'localhost' of the host computer.		6.1.0
port	number	The emulator port.	8080	6.1.0

WriteBatchOptions

Prop	Type	Description	Since
operations	WriteBatchOperation[]	The operations to execute in the batch.	6.1.0

WriteBatchOperation

Prop	Type	Description	Since
type	'set' | 'update' | 'delete'	The type of operation.	6.1.0
reference	string	The reference as a string, with path components separated by a forward slash (/).	6.1.0
data	DocumentData	An object containing the data for the new document.	6.1.0
options	SetOptions	An object to configure the set behavior.	7.3.0

SetOptions

Prop	Type	Description	Default	Since
merge	boolean	Whether a merge should be performed or the document should be overwritten.	false	7.3.0

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>

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