@capacitor-firebase/firestore

Unofficial Capacitor plugin for Firebase Cloud Firestore.¹

Guides

• Announcing the Capacitor Firebase Cloud Firestore Plugin

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

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

No configuration required for this plugin.

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(...)
• setDocument(...)
• getDocument(...)
• updateDocument(...)
• deleteDocument(...)
• writeBatch(...)
• getCollection(...)
• getCollectionGroup(...)
• getCountFromServer(...)
• clearPersistence()
• enableNetwork()
• disableNetwork()
• useEmulator(...)
• addDocumentSnapshotListener(...)
• addCollectionSnapshotListener(...)
• addCollectionGroupSnapshotListener(...)
• removeSnapshotListener(...)
• removeAllListeners()
• 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

---

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

---

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

---

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

---

deleteDocument(...)

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

Deletes the document referred to by the specified reference.

Param	Type
options	DeleteDocumentOptions

Since: 5.2.0

---

writeBatch(...)

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

Execute multiple write operations as a single batch.

Param	Type
options	WriteBatchOptions

Since: 6.1.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

---

clearPersistence()

clearPersistence() => Promise<void>

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

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

Since: 5.2.0

---

enableNetwork()

enableNetwork() => Promise<void>

Re-enables use of the network.

Since: 5.2.0

---

disableNetwork()

disableNetwork() => Promise<void>

Disables use of the network.

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

---

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

---

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

---

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

---

removeSnapshotListener(...)

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

Remove a listener for document or collection snapshot events.

Param	Type
options	RemoveSnapshotListenerOptions

Since: 5.2.0

---

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 5.2.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

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

GetDocumentResult

Prop	Type	Description	Since
snapshot	DocumentSnapshot<T>	The current document contents.	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

GetDocumentOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	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

DeleteDocumentOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.2.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

GetCollectionResult

Prop	Type	Description	Since
snapshots	DocumentSnapshot<T>[]	The documents in the collection.	5.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

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

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

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

AddDocumentSnapshotListenerOptions

Prop	Type	Description	Since
reference	string	The reference as a string, with path components separated by a forward slash (/).	5.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

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

RemoveSnapshotListenerOptions

Prop	Type	Since
callbackId	CallbackId	5.2.0

Type Aliases

QueryFilterConstraint

QueryFieldFilterConstraint | QueryCompositeFilterConstraint

QueryOperator

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

QueryNonFilterConstraint

QueryOrderByConstraint | QueryLimitConstraint | QueryStartAtConstraint | QueryEndAtConstraint

OrderByDirection

'desc' | 'asc'

AddDocumentSnapshotListenerCallback

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

AddDocumentSnapshotListenerCallbackEvent

GetDocumentResult<T>

CallbackId

string

AddCollectionSnapshotListenerCallback

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

AddCollectionSnapshotListenerCallbackEvent

GetCollectionResult<T>

AddCollectionGroupSnapshotListenerCallback

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

AddCollectionGroupSnapshotListenerCallbackEvent

GetCollectionGroupResult<T>

Limitations

This plugin currently has the following limitations:

• The Timestamp data type is not yet supported (see https://github.com/capawesome-team/capacitor-firebase/issues/474). Use a number or a string instead.
• The FieldValue data type is not yet supported (see https://github.com/capawesome-team/capacitor-firebase/issues/443).

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