Skip to content

@capacitor-firebase/firestore

Unofficial Capacitor plugin for Firebase Cloud Firestore.1

Installation

npm install @capacitor-firebase/firestore
npx cap sync

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

Android

Variables

This plugin will use the following project variables (defined in your app’s variables.gradle file):

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

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:

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 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(...)

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

Array

Prop Type Description
length number Gets or sets the length of the array. This is a number one higher than the highest index in the array.
Method Signature Description
toString () => string Returns a string representation of an array.
toLocaleString () => string Returns a string representation of an array. The elements are converted to string using their toLocalString methods.
pop () => T | undefined Removes the last element from an array and returns it. If the array is empty, undefined is returned and the array is not modified.
push (...items: T[]) => number Appends new elements to the end of an array, and returns the new length of the array.
concat (...items: ConcatArray<T>[]) => T[] Combines two or more arrays. This method returns a new array without modifying any existing arrays.
concat (...items: (T | ConcatArray<T>)[]) => T[] Combines two or more arrays. This method returns a new array without modifying any existing arrays.
join (separator?: string | undefined) => string Adds all the elements of an array into a string, separated by the specified separator string.
reverse () => T[] Reverses the elements in an array in place. This method mutates the array and returns a reference to the same array.
shift () => T | undefined Removes the first element from an array and returns it. If the array is empty, undefined is returned and the array is not modified.
slice (start?: number | undefined, end?: number | undefined) => T[] Returns a copy of a section of an array. For both start and end, a negative index can be used to indicate an offset from the end of the array. For example, -2 refers to the second to last element of the array.
sort (compareFn?: ((a: T, b: T) => number) | undefined) => this Sorts an array in place. This method mutates the array and returns a reference to the same array.
splice (start: number, deleteCount?: number | undefined) => T[] Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
splice (start: number, deleteCount: number, ...items: T[]) => T[] Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
unshift (...items: T[]) => number Inserts new elements at the start of an array, and returns the new length of the array.
indexOf (searchElement: T, fromIndex?: number | undefined) => number Returns the index of the first occurrence of a value in an array, or -1 if it is not present.
lastIndexOf (searchElement: T, fromIndex?: number | undefined) => number Returns the index of the last occurrence of a specified value in an array, or -1 if it is not present.
every <S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any) => this is S[] Determines whether all the members of an array satisfy the specified test.
every (predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any) => boolean Determines whether all the members of an array satisfy the specified test.
some (predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any) => boolean Determines whether the specified callback function returns true for any element of an array.
forEach (callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any) => void Performs the specified action for each element in an array.
map <U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any) => U[] Calls a defined callback function on each element of an array, and returns an array that contains the results.
filter <S extends T>(predicate: (value: T, index: number, array: T[]) => value is S, thisArg?: any) => S[] Returns the elements of an array that meet the condition specified in a callback function.
filter (predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any) => T[] Returns the elements of an array that meet the condition specified in a callback function.
reduce (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T) => T Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
reduce (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T) => T
reduce <U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U) => U Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
reduceRight (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T) => T Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.
reduceRight (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T) => T
reduceRight <U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U) => U Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

ConcatArray

Prop Type
length number
Method Signature
join (separator?: string | undefined) => string
slice (start?: number | undefined, end?: number | undefined) => T[]

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

SetOptions

An options object that configures the behavior of {@link @firebase/firestore/lite#(setDoc:1)}, {@link

{ readonly merge?: boolean; } | { readonly mergeFields?: Array<string | FieldPath>; }

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>

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.