@capacitor-firebase/firestore v7.2.0

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

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

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.

Since: 5.2.0

getDocument(...)

getDocument<T extends DocumentData = DocumentData>(options: GetDocumentOptions) => Promise<GetDocumentResult<T>>

Reads the document referred to by the specified reference.

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.

Since: 5.2.0

deleteDocument(...)

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

Deletes the document referred to by the specified reference.

Since: 5.2.0

writeBatch(...)

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

Execute multiple write operations as a single batch.

Since: 6.1.0

getCollection(...)

getCollection<T extends DocumentData = DocumentData>(options: GetCollectionOptions) => Promise<GetCollectionResult<T>>

Reads the collection referenced by the specified reference.

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.

Returns: Promise<GetCollectionGroupResult<T>>

getCountFromServer(...)

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

Fetches the number of documents in a collection.

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.

Since: 6.1.0

addDocumentSnapshotListener(...)

addDocumentSnapshotListener<T extends DocumentData = DocumentData>(options: AddDocumentSnapshotListenerOptions, callback: AddDocumentSnapshotListenerCallback<T>) => Promise<CallbackId>

Adds a listener for document snapshot events.

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.

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.

Returns: Promise<string>

Since: 6.1.0

removeSnapshotListener(...)

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

Remove a listener for document or collection snapshot events.

Since: 5.2.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 5.2.0

Interfaces

AddDocumentResult

DocumentReference

AddDocumentOptions

DocumentData

SetDocumentOptions

GetDocumentResult

DocumentSnapshot

SnapshotMetadata

GetDocumentOptions

UpdateDocumentOptions

DeleteDocumentOptions

WriteBatchOptions

WriteBatchOperation

GetCollectionResult

GetCollectionOptions

QueryCompositeFilterConstraint

QueryFieldFilterConstraint

QueryOrderByConstraint

QueryLimitConstraint

QueryStartAtConstraint

QueryEndAtConstraint

GetCollectionGroupResult

GetCollectionGroupOptions

GetCountFromServerResult

GetCountFromServerOptions

UseEmulatorOptions

AddDocumentSnapshotListenerOptions

AddCollectionSnapshotListenerOptions

AddCollectionGroupSnapshotListenerOptions

RemoveSnapshotListenerOptions

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>

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.