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

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

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

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

Changelog¶

See CHANGELOG.md.

License¶

See LICENSE.

This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries. ↩

@capacitor-firebase/firestore¶

Installation¶

Android¶

Variables¶

Configuration¶

Demo¶

Starter templates¶

Usage¶

API¶

addDocument(...)¶

setDocument(...)¶

getDocument(...)¶

updateDocument(...)¶

deleteDocument(...)¶

writeBatch(...)¶

getCollection(...)¶

getCollectionGroup(...)¶

clearPersistence()¶

enableNetwork()¶

disableNetwork()¶

useEmulator(...)¶

addDocumentSnapshotListener(...)¶

addCollectionSnapshotListener(...)¶

addCollectionGroupSnapshotListener(...)¶

removeSnapshotListener(...)¶

removeAllListeners()¶

Interfaces¶

AddDocumentResult¶

DocumentReference¶

AddDocumentOptions¶

DocumentData¶

SetDocumentOptions¶

GetDocumentResult¶

DocumentSnapshot¶

SnapshotMetadata¶

GetDocumentOptions¶

UpdateDocumentOptions¶

DeleteDocumentOptions¶

WriteBatchOptions¶

WriteBatchOperation¶

GetCollectionResult¶

GetCollectionOptions¶

QueryCompositeFilterConstraint¶

QueryFieldFilterConstraint¶

QueryOrderByConstraint¶

QueryLimitConstraint¶

QueryStartAtConstraint¶

QueryEndAtConstraint¶

GetCollectionGroupResult¶

GetCollectionGroupOptions¶

UseEmulatorOptions¶

AddDocumentSnapshotListenerOptions¶

AddCollectionSnapshotListenerOptions¶

AddCollectionGroupSnapshotListenerOptions¶

RemoveSnapshotListenerOptions¶

Type Aliases¶

QueryFilterConstraint¶

QueryOperator¶

QueryNonFilterConstraint¶

OrderByDirection¶

AddDocumentSnapshotListenerCallback¶

AddDocumentSnapshotListenerCallbackEvent¶

CallbackId¶

AddCollectionSnapshotListenerCallback¶

AddCollectionSnapshotListenerCallbackEvent¶

AddCollectionGroupSnapshotListenerCallback¶

AddCollectionGroupSnapshotListenerCallbackEvent¶

Changelog¶

License¶