@capacitor-firebase/firestore¶

Unofficial Capacitor plugin for Firebase Cloud Firestore.¹

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: 24.7.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:

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

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

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 removeSnapshotListener = async (callbackId: string) => {
  await FirebaseFirestore.removeSnapshotListener({
    callbackId,
  });
};

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

API¶

addDocument(...)
setDocument(...)
getDocument(...)
updateDocument(...)
deleteDocument(...)
getCollection(...)
getCollectionGroup(...)
clearPersistence()
enableNetwork()
disableNetwork()
addDocumentSnapshotListener(...)
addCollectionSnapshotListener(...)
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

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

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

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

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

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

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

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